Başlarken
Temel kavramlar
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
Content-Type: application/json.2026-11-20T18:10:32.000Z. Ekranda gösterirken Europe/Istanbul saatine çevirin.2026-11-21T19:30:00+03:00 ya da …Z.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.285.5. Metin ("285,50") gönderilmez.distance_m) ve saniye (duration_s). Yol sunucusu kuruluysa gerçek yol mesafesi, değilse tahmindir.40.9969, 29.0342.+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:
idorder.id olarak gelir. Kendi kaydınızda saklayın.code2611200042: [firma ön eki] + iş günü (YYAAGG) + günün sıra numarası. Panelde ve kurye uygulamasında bu görünür.external_idext: ile bulmanızı sağlar.external_codeSipariş başvurusu: {ref}
/orders/{ref} biçimindeki yollarda siparişi üç şekilde belirtebilirsiniz:
/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_idile 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:
{
"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_ZONEile 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.
cashcardonlinemeal_cardother- Tür verildiğinde o türdeki ilk etkin ödeme tipi kullanılır. Firmada o türde tip yoksa
400 PAYMENT_TYPE_NOT_FOUNDdöner. - Kurye kapıda tahsilat yapan tiplerde
collect_amountverilmezsetotal_amountkabul edilir. Önceden ödenmiş (online) siparişte tahsilat her zaman0olur. - 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_amountile 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:
422 VALIDATION (customer_phone) ile reddedilir.400 OUT_OF_RANGE.400 OPEN_ORDER_LIMIT.400 CREDIT_LIMIT alır.400 RESTAURANT_INACTIVE.403 FORBIDDEN. Varsayılan: kurye kabul edene kadar.delivery_fee yanıtlarda yer almaz.tracking_url açıldığında "Sipariş takibi kullanılamıyor" görünür.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.