Partner API · v1

Sipariş sizden,
teslimat bizden.

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.

Sandbox'ta dene OpenAPI indir

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

Dört uç, tek teslimat gerçeği.

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/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

HMAC-SHA256

İmza ham JSON'u kapsar.

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.

• Bearer ve key id hesabı bulur.
• Zaman damgası beş dakikalık replay penceresindedir.
• Yazma uçlarında Idempotency-Key zorunludur.
• Okuma/teklif imzasında idempotency ve olay satırları boştur.

Kanonik metin

UTF-8 · LF

kurye-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

İmzayı ve gövdeyi şimdi doğrula.

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.

OpenAPI sözleşmesi

Uçlar, alan kuralları, hata gövdeleri ve güvenlik başlıkları makine tarafından okunabilir YAML dosyasında.

YAML dosyasını aç

WooCommerce 0.1.0

Sipariş, Paket X fiyatı, iptal ve imzalı kurye durumu senkronizasyonu hazır eklentide bulunur. İlk sürüm klasik checkout içindir.

Eklentiyi indir

Referans

Buradaki durum listeleri, limitler ve webhook gövdesi elle yazılmadı; çalışan koddan üretiliyor. Sunucuda bir durum eklenirse bu sayfa da değişir.

Uçların tamamı

119 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/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/orders`idempotency 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}/cancel`idempotency anahtarı zorunlu	Mağazada iptal edilen siparişi kapatır	`orders.write`	İmzalı (Bearer + Key-Id + HMAC)
POST	`/api/v1/partner/receipt-orders`idempotency 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/validate`idempotency 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

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

Bir siparişin yolculuğu

1
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`.
2
Restoran onaylar
Durum `confirmed` olur. Şubede eşleşmiş yazıcı varsa mutfak fişi burada basılır.
3
Kurye atanır
Otomatik tur uygun kuryeye teklif gönderir, kabul edilince atama yazılır. Size `delivery.status.assigned` webhook'u gider.
4
Paket alınır ve yola çıkar
`order.status.ready_for_pickup` ve `delivery.status.in_transit` olayları gider.
5
Teslim edilir
`delivery.status.delivered` gider. Sipariş durumu `delivered` olur ve kapanır.
6
İptal olursa
Teslim edilmemiş sipariş iptal edilebilir; `order.status.cancelled` olayı sebebiyle birlikte gider.

Ortamlar

Sandbox

https://paketx.com.tr

Tarayı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.tr

Kimlik bilgileri bayiniz tarafından panelden üretilir. Aynı yollar, aynı imza şeması; fark yalnız hesabın gerçek olmasıdır.

Oran sınırları

Hesap başına: 300 istek/dk
IP başına: 15000 istek/dk
En büyük gövde: 1024 KB

Sınır aşılınca 429 döner. Yanıt gövdesi diğer hatalarla aynı biçimdedir; üstel bekleyerek tekrar deneyin.

Aynı isteği iki kez göndermek

Yazma uçlarında Idempotency-Key zorunludur.

Aynı anahtarla gelen ikinci istek yeni sipariş açmaz; ilk isteğin yanıtını döndürür.
Aynı anahtar farklı gövdeyle gelirse istek reddedilir — sessizce üzerine yazmaz.
İlk istek hâlâ işleniyorsa ikinci istek bekletilmez, "işleniyor" yanıtı alır.
Ağ zaman aşımından sonra aynı anahtarla tekrar denemek güvenlidir; sipariş iki kez oluşmaz.

Sipariş durumları

`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ış

Teslimat durumları

`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

Webhook gövdesi

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"
    }
}

Hatalar

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ı.

Callback olayları

Her olay event_id ile tekilleştirilebilir. Önce ham gövde imzasını doğrulayın, sonra sipariş durumunu değiştirin.

order.status.accepted

Sipariş kabul edildi

order.status.ready_for_pickup

Sipariş alıma hazır

order.status.cancelled

Sipariş iptal edildi

delivery.status.assigned

Kurye atandı

delivery.status.in_transit

Kurye yola çıktı

delivery.status.delivered

Teslim edildi

Sipariş sizden,teslimat bizden.