1 · Siparişi gönder
Kaynak kimliğinizi koruyarak idempotent sipariş bırakın. Aynı deneme ikinci sipariş oluşturmaz.
Partner API · v1
WordPress, POS veya kendi uygulamanız siparişi Paket X'e yollar. Yol mesafesini, fiyatı, kurye atamasını ve canlı operasyonu Paket X hesaplar; sonuçlar imzalı webhook ile kaynağa geri döner.
Hızlı başlangıç
Sipariş pazar yerinden mi geliyor?
Kod yazmanıza gerek yok; bu bağlantılar hazır:
BODY='{"external_order_id":"site-1001","external_order_number":"#1001","currency":"TRY","amounts":{"delivery_fee_amount":3000,"service_fee_amount":0,"discount_amount":0},"payment":{"status":"prepaid","collection_party":"restaurant","amount_due_to_collect":0},"customer":{"name":"Ayşe Yılmaz","phone":"+905551112233"},"delivery":{"address_line":"Örnek Cd. 10","district":"Odunpazarı","city":"Eskişehir","latitude":39.7767,"longitude":30.5206},"items":[{"name":"Lahmacun","quantity":2,"unit_price_amount":18500}]}'
PATH_="/api/v1/partner/orders"
TS=$(date +%s)
IDEM="site-1001-v1" # aynı sipariş için hep aynı
EVENT_ID="site:1001"
EVENT_TYPE="order.created"
CANONICAL=$(printf 'kurye-x:v1\nPOST\n%s\n%s\n%s\n%s\n%s\n%s' "$PATH_" "$TS" "$IDEM" "$EVENT_ID" "$EVENT_TYPE" "$BODY")
SIG=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$PAKETX_SIGNING_SECRET" | sed 's/^.* //')
curl -sS "https://paketx.com.tr$PATH_" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PAKETX_BEARER" \
-H "X-KuryeX-Key-Id: $PAKETX_KEY_ID" \
-H "X-KuryeX-Timestamp: $TS" \
-H "X-KuryeX-Signature-Version: v1" \
-H "X-KuryeX-Signature: sha256=$SIG" \
-H "Idempotency-Key: $IDEM" \
-H "X-Provider-Event-Id: $EVENT_ID" \
-H "X-Provider-Event-Type: $EVENT_TYPE" \
--data-binary "$BODY" Örnekler üretim adresini kullanır. Önce sandbox’ta denemek için yolu /api/v1/partner/sandbox/orders/validate yapın ve aşağıdan aldığınız geçici anahtarları PAKETX_BEARER, PAKETX_KEY_ID, PAKETX_SIGNING_SECRET ortam değişkenlerine yazın.
1 · Siparişi gönder
Kaynak kimliğinizi koruyarak idempotent sipariş bırakın. Aynı deneme ikinci sipariş oluşturmaz.
2 · Paket X hesaplasın
OSRM yol rotası, hizmet bölgesi ve fiyat kuralı sunucuda çalışır. İstemcinin mesafe/fiyat beyanı kabul edilmez.
3 · Durumu geri al
Atama, yola çıkma, teslim ve iptal olayları ham gövdeyi kapsayan HMAC ile callback adresinize gelir.
HTTP sözleşmesi
Para alanları kuruş cinsinden tam sayıdır. Partner kendi tenant/restoran kimliğini gönderemez. Teklif isteğinde yol mesafesi ve hesaplanmış teslimat fiyatı da kabul edilmez; bunlar hesaptan ve Paket X motorundan çözülür.
| Yöntem | Yol | Kapsam | İş |
|---|---|---|---|
| POST | /api/v1/partner/bridge/report | orders.write | POS köprüsünün dakikalık durum raporu ve aktaramadığı siparişler |
| POST | /api/v1/partner/calls | calls.write | Telefon santralinden gelen çağrı olayını kaydeder |
| POST | /api/v1/partner/delivery-quotes | delivery-quotes.read | Sipariş açmadan Paket X rota mesafesi ve teslimat ücreti hesaplar |
| POST | /api/v1/partner/orders | orders.write | Restoran sitesi, POS veya pazar yeri adaptöründen sipariş kabul eder |
| GET | /api/v1/partner/orders/{externalOrderId} | orders.read | Partnerin bıraktığı siparişin durumu |
| POST | /api/v1/partner/orders/{externalOrderId}/cancel | orders.write | Mağazada iptal edilen siparişi kapatır |
| POST | /api/v1/partner/receipt-orders | orders.write | Restoranın yazıcıya bastığı fişten sipariş açar |
| POST | /api/v1/partner/yemeksepeti-extension/stores | orders.write | Yemeksepeti eklentisinin panelde gördüğü mağazaları bağlantıya yazar |
| POST | /api/v1/yemeksepeti-extension/pair | — | Yemeksepeti eklentisinin bağlantı kodunu partner anahtarlarına çevirir |
JSON'u imzaladıktan sonra yeniden biçimlendirmeyin. Büyük harfli HTTP yöntemi, istek yolu, Unix zamanı, idempotency/olay alanları ve değiştirilmemiş gövde satır satır birleştirilir.
Kanonik metin
UTF-8 · LFkurye-x:v1
POST
/api/v1/partner/orders
1723147200
wc-order-42-v1
wc:1:42
order.created
{"external_order_id":"wc:1:42",...} Başlık: X-KuryeX-Signature: sha256=<hex>
Veri yazmayan sandbox
Geçici anahtar bir saat yaşar. Aynı HMAC ve idempotency duvarından geçer; sipariş, müşteri, OSRM rotası veya finans kaydı oluşturmaz.
Uçlar, alan kuralları, hata gövdeleri ve güvenlik başlıkları makine tarafından okunabilir YAML dosyasında.
YAML dosyasını açSipariş, Paket X fiyatı, iptal ve imzalı kurye durumu senkronizasyonu hazır eklentide bulunur. İlk sürüm klasik checkout içindir.
Eklentiyi indirBuradaki durum listeleri, limitler ve webhook gövdesi elle yazılmadı; çalışan koddan üretiliyor. Sunucuda bir durum eklenirse bu sayfa da değişir.
142 uç, OpenAPI sözleşmesinden okunuyor — burada listelenen her yol gerçekten var, çünkü liste elle yazılmadı. Entegrasyon yazacaksanız ilgilendiğiniz yer Partner grubudur; diğer gruplar kendi uygulamalarımızın kullandığı uçlardır ve tamlık için listelenir.
| Yöntem | Yol | Ne yapar | Kapsam | Kimlik |
|---|---|---|---|---|
| POST | /api/v1/partner/bridge/report | POS köprüsünün dakikalık durum raporu ve aktaramadığı siparişler | orders.write | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/calls | Telefon santralinden gelen çağrı olayını kaydeder | calls.write | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/delivery-quotes | Sipariş açmadan Paket X rota mesafesi ve teslimat ücreti hesaplar | delivery-quotes.read | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/ordersidempotency anahtarı zorunlu | Restoran sitesi, POS veya pazar yeri adaptöründen sipariş kabul eder | orders.write | İmzalı (Bearer + Key-Id + HMAC) |
| GET | /api/v1/partner/orders/{externalOrderId} | Partnerin bıraktığı siparişin durumu | orders.read | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/orders/{externalOrderId}/cancelidempotency anahtarı zorunlu | Mağazada iptal edilen siparişi kapatır | orders.write | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/receipt-ordersidempotency anahtarı zorunlu | Restoranın yazıcıya bastığı fişten sipariş açar | orders.write | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/sandbox/delivery-quotes/validate | Teslimat teklifi isteğini rota veya fiyat uydurmadan doğrular | sandbox: read | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/sandbox/orders/validateidempotency anahtarı zorunlu | Sipariş gövdesi, imza ve idempotency sözleşmesini veri yazmadan doğrular | sandbox: write | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/partner/sandbox/sessions | Geçici ve verisiz partner sözleşme sandbox kimliği üretir | — | Kimliksiz |
| POST | /api/v1/partner/yemeksepeti-extension/stores | Yemeksepeti eklentisinin panelde gördüğü mağazaları bağlantıya yazar | orders.write | İmzalı (Bearer + Key-Id + HMAC) |
| POST | /api/v1/yemeksepeti-extension/pair | Yemeksepeti eklentisinin bağlantı kodunu partner anahtarlarına çevirir | — | Kimliksiz |
| Yöntem | Yol | Ne yapar | Kapsam | Kimlik |
|---|---|---|---|---|
| POST | /api/v1/webhooks/integrations/{integrationAccount} | Sağlayıcı sipariş ve iptal webhook'larını kabul eder | — | Kimliksiz |
| POST | /api/v1/webhooks/migros-yemek | Migros Yemek webhook'larını tek entegratör adresinden kabul eder | — | Kimliksiz |
| POST | /api/v1/yemeksepeti/order/{integrationAccount} | Delivery Hero (Yemeksepeti) siparişlerini kendi yol kalıbıyla kabul eder | — | Kimliksiz |
| PUT | /api/v1/yemeksepeti/remoteId/{integrationAccount}/availability | Delivery Hero (Yemeksepeti) restoran açık/kapalı bildirimini kabul eder | — | Kimliksiz |
| PUT | /api/v1/yemeksepeti/remoteId/{integrationAccount}/remoteOrder/{remoteOrderId}/posOrderStatus | Delivery Hero (Yemeksepeti) sipariş durum bildirimlerini kabul eder | — | Kimliksiz |
| Yöntem | Yol | Ne yapar | Kapsam | Kimlik |
|---|---|---|---|---|
| POST | /api/v1/webhooks/softpos/{providerAccount} | Sağlayıcının imzalı SoftPOS durum bildirimini işler | — | Kimliksiz |
Siparişi bırakırsınız
POST /api/v1/partner/orders. Yanıt sipariş numarasını ve Paket X kimliğini döndürür. Bu noktada durum `pending`.
Restoran onaylar
Durum `confirmed` olur. Şubede eşleşmiş yazıcı varsa mutfak fişi burada basılır.
Kurye atanır
Otomatik tur uygun kuryeye teklif gönderir, kabul edilince atama yazılır. Size `delivery.status.assigned` webhook'u gider.
Paket alınır ve yola çıkar
`order.status.ready_for_pickup` ve `delivery.status.in_transit` olayları gider.
Teslim edilir
`delivery.status.delivered` gider. Sipariş durumu `delivered` olur ve kapanır.
İptal olursa
Teslim edilmemiş sipariş iptal edilebilir; `order.status.cancelled` olayı sebebiyle birlikte gider.
Sandbox
https://paketx.com.trTarayıcıdan tek tıkla kimlik alınır, süresi 60 dakikadır. Sipariş ve teklif gövdeniz doğrulanır; gerçek sipariş oluşmaz, kurye çağrılmaz.
Üretim
https://paketx.com.trKimlik bilgileri bayiniz tarafından panelden üretilir. Aynı yollar, aynı imza şeması; fark yalnız hesabın gerçek olmasıdır.
Sınır aşılınca 429 döner. Yanıt gövdesi diğer hatalarla aynı biçimdedir; üstel bekleyerek tekrar deneyin.
Yazma uçlarında Idempotency-Key zorunludur.
pending | Onay bekliyor | |
confirmed | Onaylandı | |
preparing | Hazırlanıyor | |
ready_for_pickup | Kuryeye hazır | |
picked_up | Kurye teslim aldı | |
delivered | Teslim edildi | kapanış |
cancelled | İptal edildi | kapanış |
pending_assignment | Atama bekliyor |
assigned | Kurye atandı |
courier_arriving | Kurye restorana gidiyor |
picked_up | Kurye teslim aldı |
in_transit | Müşteriye gidiyor |
delivered | Teslim edildi |
failed | Teslimat başarısız |
cancelled | İptal edildi |
Bu örnek, gerçek gönderim işinin kullandığı sınıftan üretiliyor. Alan sırası imzanın parçasıdır.
{
"event_id": "01JQ6M0Z7K8N2P4R6T8V0X2Z4A",
"event_type": "delivery.status.assigned",
"occurred_at": "2026-08-17T21:14:03+03:00",
"data": {
"external_order_id": "wc:1:42",
"status": "assigned"
}
} Her hata aynı zarfı kullanır: error.code, error.message ve doğrulama hatalarında error.details. Yanıtta yığın izi, SQL ya da sunucu yolu bulunmaz.
| Kod | HTTP | Anlamı |
|---|---|---|
unauthenticated | 401 | Kimlik doğrulanamadı; jeton veya key id hatalı. |
forbidden | 403 | Hesabın bu kapsam için yetkisi yok. |
not_found | 404 | Kayıt yok ya da hesabınızın kapsamında değil. İkisi bilinçli olarak ayırt edilmez. |
invalid_transition | 422 | İstenen durum geçişi sipariş akışında geçerli değil. |
validation_failed | 422 | Gövde doğrulanamadı; `details` alanı alan bazında sebebi taşır. |
too_many_requests | 429 | Oran sınırı aşıldı. |
http_error | — | Sınıflandırılmamış HTTP hatası. |
Her olay event_id ile tekilleştirilebilir. Önce ham gövde imzasını doğrulayın, sonra sipariş durumunu değiştirin.
order.status.acceptedSipariş kabul edildi
order.status.ready_for_pickupSipariş alıma hazır
order.status.cancelledSipariş iptal edildi
delivery.status.assignedKurye atandı
delivery.status.in_transitKurye yola çıktı
delivery.status.deliveredTeslim edildi
Paket X platformu Rentondiji tarafından geliştirilmektedir.