İçeriğe geç
KuryeSoft

Başlarken

Temel kavramlar

Entegrasyonu yazmadan önce bilmeniz gerekenler: veri biçimleri, siparişlere nasıl başvurulduğu, yinelenen gönderimler ve kurye firmasının ayarlarının API'ye etkisi.

Taban adres ve sürüm

Bütün uçlar https://kurye.firmaniz.com/api/v1 altındadır. Adresin v1 kısmı sözleşmenin sürümüdür: bu sürümde mevcut alanlar kaldırılmaz ve anlamları değişmez. Yanıtlara yeni alanlar eklenebilir; tanımadığınız alanları yok sayacak şekilde yazın. Uyumsuz bir değişiklik gerekirse yeni bir sürüm (v2) açılır ve değişiklik günlüğünde duyurulur.

Veri biçimleri

İstek ve yanıt
Biçim:JSON, UTF-8. Gövdeli isteklerde Content-Type: application/json.
Tarih-saat (yanıt)
Biçim:ISO 8601, her zaman UTC: 2026-11-20T18:10:32.000Z. Ekranda gösterirken Europe/Istanbul saatine çevirin.
Tarih-saat (istek)
Biçim:ISO 8601; saat dilimi belirtin: 2026-11-21T19:30:00+03:00 ya da …Z.
İş günü
Biçim:business_date: YYYY-AA-GG. İş günü firmanın ayarındaki saatte başlar (genellikle 06:00); gece yarısından sonraki siparişler önceki güne yazılır.
Tutar
Biçim:Türk lirası, ondalıklı sayı: 285.5. Metin ("285,50") gönderilmez.
Mesafe ve süre
Biçim:Metre (distance_m) ve saniye (duration_s). Yol sunucusu kuruluysa gerçek yol mesafesi, değilse tahmindir.
Konum
Biçim:WGS84 enlem/boylam, ondalık derece: 40.9969, 29.0342.
Telefon
Biçim:+90 532 123 45 67, 905321234567, 5321234567 gibi biçimler kabul edilir; 05321234567 olarak saklanır ve döner.

Sipariş kimlikleri

Bir siparişin dört tanımlayıcısı vardır:

id
Kimin:KuryeSoft
Açıklama:Sayısal kimlik. Değişmez; webhook'larda order.id olarak gelir. Kendi kaydınızda saklayın.
code
Kimin:KuryeSoft
Açıklama:Sipariş numarası, ör. 2611200042: [firma ön eki] + iş günü (YYAAGG) + günün sıra numarası. Panelde ve kurye uygulamasında bu görünür.
external_id
Kimin:Siz
Açıklama:Sizin benzersiz kimliğiniz. Yinelenen gönderimleri ayıklar; siparişi ext: ile bulmanızı sağlar.
external_code
Kimin:Siz
Açıklama:Ekranda gösterilecek kısa numaranız (adisyon no). Kurye işletmede paketi bununla sorar.

Sipariş başvurusu: {ref}

/orders/{ref} biçimindeki yollarda siparişi üç şekilde belirtebilirsiniz:

Aynı sipariş
/orders/1842             sistemdeki kimlik (id)
/orders/2611200042       sipariş numarası (code)
/orders/ext:POS-10452    sizin kimliğiniz (external_id)

Kendi kimliğiniz boşluk, /, # ya da ? içeriyorsa yolda kodlayın (encodeURIComponent). ext: başvurusu yalnızca bu API ile gönderilmiş siparişleri bulur.

Yinelenen gönderim (idempotency)

POST /orders güvenle yeniden denenebilir: aynı işletme için aynı external_id ile gelen ikinci istek yeni sipariş açmaz, mevcut siparişi 200 OK ile döndürür (ilk istekte 201 Created).

  • Zaman aşımı, bağlantı kopması ya da 5xx yanıtında isteği aynı gövdeyle tekrar gönderin.
  • Yinelenen istekteki değişiklikler uygulanmaz. Sipariş bilgisi değiştiyse (ör. adres) kurye firmasına bildirin ya da siparişi iptal edip yeni external_id ile yeniden gönderin.
  • İptal edilen siparişin external_id'si de kayıtlı kalır; aynı kimlikle yeniden gönderirseniz iptal edilmiş sipariş döner.
  • Aynı siparişi aynı anda iki kez göndermeyin (ör. iki iş parçacığından); yeniden denemeyi önceki istek sonuçlandıktan sonra yapın.

İşletmeyi belirtmek

Anahtarınız bir işletmeye bağlıysa hiçbir şey yapmanız gerekmez. Firma geneli anahtarda POST /orders ve POST /quote isteklerinde işletmeyi gövdede (ya da sorgu dizgisinde) belirtin:

json
{
  "restaurant_code": "R001",
  "external_id": "MRK-88123",
  ...
}

restaurant_id sayısal kimliktir, restaurant_code panelde görünen işletme kodudur (ör. R001). İkisini de kurye firmanız verir. Bulunamazsa 404 NOT_FOUND döner.

Teslimat konumu

Mesafe, teslimat ücreti, hizmet bölgesi denetimi ve kurye ataması teslimat konumuna göre yapılır. address.lat ve address.lng göndermeniz şiddetle önerilir. API adres metninden konum bulmaz (geocoding yapmaz); konumu kendi tarafınızda harita seçiciyle ya da adres arama servisinizle alın.

Konumsuz gönderilen siparişin akıbeti kurye firmasının fiyatlandırmasına bağlıdır:

  • Fiyat profili mesafeye ya da bölgeye dayanıyorsa (en yaygın durum) sipariş 400 OUT_OF_ZONE ile reddedilir.
  • Sabit ücretliyse sipariş alınır, ancak firma panelde konumu işaretleyene kadar otomatik atama bekler; bu da teslimatı geciktirir.

Hizmet bölgesi ve ücret

Kurye firması her işletme için bir fiyat profili, en fazla teslimat mesafesi ve hizmet bölgeleri tanımlar. Adres bunların dışındaysa sipariş OUT_OF_RANGE ya da OUT_OF_ZONE ile reddedilir. Müşteri ödeme yapmadan önce POST /quote ile denetleyin; aynı kurallar uygulanır ve teslimat ücreti döner.

delivery_fee, işletmenin kurye firmasına ödeyeceği teslimat ücretidir. Firma işletmelerin ücretleri görmesini kapattıysa bu alan yanıtlarda hiç yer almaz.

Ödeme ve tahsilat

Ödemeyi türüyle (payment.kind) ya da firmanın tanımladığı ödeme tipinin kimliğiyle (payment.payment_type_id) belirtin. Hiçbiri verilmezse kapıda nakit kabul edilir.

cash
Anlamı:Kapıda nakit
card
Anlamı:Kapıda kredi kartı
online
Anlamı:Önceden ödenmiş (online)
meal_card
Anlamı:Yemek kartı
other
Anlamı:Diğer
  • Tür verildiğinde o türdeki ilk etkin ödeme tipi kullanılır. Firmada o türde tip yoksa 400 PAYMENT_TYPE_NOT_FOUND döner.
  • Kurye kapıda tahsilat yapan tiplerde collect_amount verilmezse total_amount kabul edilir. Önceden ödenmiş (online) siparişte tahsilat her zaman 0 olur.
  • Kısmi ödemede (ör. bir kısmı online ödenmiş) kapıda tahsilat yapılan bir tür (ör. cash) seçip kapıda alınacak tutarı collect_amount ile gönderin.

Hazırlık süresi ve hazır bildirimi

Her siparişin bir hazırlık süresi vardır (prep_minutes; verilmezse firmanın varsayılanı, genellikle 15 dakika). Kurye atamasının ne zaman başlayacağını kurye firmasının atama senaryosu belirler:

  • sipariş gelir gelmez (en yaygın),
  • hazır olmasına belirli bir süre kala (hazırlık süresine göre hesaplanır),
  • ya da yalnızca hazır işaretlendiğinde. Bu senaryoda hazır işaretlenmeyen sipariş otomatik atanmaz.

Hangisi kullanılırsa kullanılsın, paket hazır olduğunda hazır işaretleyin: kurye telefonuna bildirim alır, bekleyen siparişin ataması hemen yeniden denenir. Hazırlık süresi kuryenin rotası ve tahmini teslim zamanı hesaplanırken de kullanılır.

İleri tarihli siparişler

scheduled_at ile gelecekte hazırlanacak bir sipariş gönderebilirsiniz. Değer, hazırlığın başlayacağı andır: sipariş o ana kadar bekler, sonra kurye ataması başlar; paket scheduled_at + prep_minutes anında hazır kabul edilir. Müşteriye 20:00'de teslim edilmesi istenen, 15 dakikada hazırlanan ve yolu yaklaşık 15 dakika süren bir sipariş için scheduled_at değerini 19:30 civarına verin.

Kurye firmasının ayarları

API işletme adına çalışır; kurye firmasının işletmeler için belirlediği kurallar API isteklerine de uygulanır. Bir isteğin neden reddedildiğini anlamak için:

Müşteri telefonu zorunlu
Etkisi:Telefonsuz sipariş 422 VALIDATION (customer_phone) ile reddedilir.
En fazla teslimat mesafesi
Etkisi:Daha uzak adres 400 OUT_OF_RANGE.
Aynı anda en fazla açık sipariş
Etkisi:Sınır doluysa 400 OPEN_ORDER_LIMIT.
Borç sınırı
Etkisi:Cari borcu sınırı aşan işletme 400 CREDIT_LIMIT alır.
İşletme pasif
Etkisi:400 RESTAURANT_INACTIVE.
Sipariş iptal edebilir / en geç hangi aşamada
Etkisi:Kapalıysa ya da aşama geçtiyse iptal 403 FORBIDDEN. Varsayılan: kurye kabul edene kadar.
Teslimat ücretlerini görebilir
Etkisi:Kapalıysa delivery_fee yanıtlarda yer almaz.
Müşteri takip sayfası
Etkisi:Kapalıysa tracking_url açıldığında "Sipariş takibi kullanılamıyor" görünür.
Bilgi:

Bu ayarlar kurye firmasına aittir ve işletmeden işletmeye değişebilir. Entegrasyonunuz bunları varsaymak yerine hata kodlarına göre davranmalıdır.