Başlarken
Hızlı başlangıç
Deneme siparişleri gerçek kuryelere gider
Ayrı bir deneme ortamı yoktur: gönderdiğiniz sipariş kurye firmasının canlı sistemine düşer ve kuryelere teklif edilir. Geliştirme sırasında kurye firmanızdan bir deneme işletmesi ve ona bağlı bir anahtar isteyin, denemeleri firmayla önceden konuşun ve her deneme siparişini işiniz bitince iptal edin (5. adım).
API anahtarınızı alın
Anahtarı kurye firmanızın yöneticisi oluşturur: panelde Ayarlar → API Anahtarları ve Webhook → API Anahtarları. Anahtar
ks_ile başlar ve yalnızca oluşturulduğu anda bir kez gösterilir; size güvenli bir kanaldan iletilmelidir.Anahtarı bir işletmeye bağlamak en kolayıdır: siparişler kendiliğinden o işletmeye yazılır. Firma geneli anahtarla her siparişte işletmeyi belirtirsiniz. Ayrıntı: Kimlik doğrulama.
Firmanın sunucu adresini de alın ve aşağıya yazın; bu sayfadaki örnekler sizin adresinizle gösterilir:
Bağlantıyı sınayın
Anahtarı ortam değişkenine koyun (örnek kodlar oradan okur) ve ilk isteği gönderin:
bashexport KURYESOFT_API_KEY="ks_..."GET /pingcurl "https://kurye.firmaniz.com/api/v1/ping" \ -H "X-Api-Key: $KURYESOFT_API_KEY"Yanıt anahtarın adını ve bağlı olduğu işletmeyi verir:
200 · application/json{ "ok": true, "key": "Kasa POS", "restaurant_id": 1 }401 API_KEY_INVALIDalırsanız anahtar yanlış kopyalanmış ya da pasif yapılmıştır.İlk siparişinizi gönderin
Zorunlu olanlar
external_id(sizin sipariş kimliğiniz) veaddress. Konumu (lat,lng) mutlaka gönderin: mesafe, ücret ve kurye ataması konuma göre yapılır.POST /orderscurl -X POST "https://kurye.firmaniz.com/api/v1/orders" \ -H "X-Api-Key: $KURYESOFT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "external_id": "DENEME-1", "customer": { "name": "Deneme Müşteri", "phone": "05321234567" }, "address": { "text": "Caferağa Mah. Moda Cad. No:12 Kadıköy", "lat": 40.9969, "lng": 29.0342 }, "payment": { "kind": "cash" }, "total_amount": 150 }'Yanıt
201 Createdile oluşturulan siparişi döndürür.iddeğerini kendi kaydınızda saklayın; webhook'larda sipariş bu kimlikle gelir.201 · application/json{ "id": 1842, "code": "2611200042", "external_id": "DENEME-1", "status": "pending", "status_label": "Bekliyor", "restaurant_id": 1, "tracking_url": "https://kurye.firmaniz.com/takip/oKe9xPqrlr7b_4jbNQiNCw", "courier": null, "distance_m": 1754, "eta_at": null, "delivery_fee": 70, "total_amount": 150, "collect_amount": 150, "created_at": "2026-11-20T18:10:32.000Z", "assigned_at": null, "picked_up_at": null, "delivered_at": null, "cancelled_at": null, "cancel_reason": null }İpucu:İstek zaman aşımına uğrarsa aynı gövdeyle tekrar gönderin: aynı
external_idikinci bir sipariş açmaz, mevcut siparişi döndürür.Durumu izleyin
İki yol var; canlı kullanımda ikisini birlikte kullanın:
- Webhook (önerilen): kurye firmanızdan, panelde Webhook'lar sekmesine sizin adresinizi eklemesini isteyin. Sipariş her durum değiştirdiğinde adresinize imzalı bir POST isteği gelir. Bkz. Webhook'lar.
- Sorgu: son durumu her zaman
GET /orders/ext:DENEME-1ile alabilirsiniz.
GET /orders/{ref}curl "https://kurye.firmaniz.com/api/v1/orders/ext:DENEME-1" \ -H "X-Api-Key: $KURYESOFT_API_KEY"Deneme siparişini iptal edin
Sipariş bir kuryeye gitmeden iptal edin:
POST /orders/{ref}/cancelcurl -X POST "https://kurye.firmaniz.com/api/v1/orders/ext:DENEME-1/cancel" \ -H "X-Api-Key: $KURYESOFT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "Entegrasyon denemesi" }'Kurye işletmeye vardıktan sonra işletme adına iptal yapılamaz (
403); o durumda kurye firmasına haber verin.
Sonraki adımlar
- Temel kavramlar: sipariş başvurusu, yinelenen gönderim, konum, ödeme ve firma ayarlarının etkisi.
- Sipariş oluştur: bütün alanlar.
- İmza doğrulama: webhook isteklerinin gerçekten kurye firmanızdan geldiğini doğrulayın.
- Canlıya geçiş listesi.