Siparişler

POST /api/vendor/v1/orders

Teslimat isteği oluşturur. Sonuç aynı yanıtta bildirilir: teslimat ya oluşturulmuştur ya da oluşturulamama nedeni açıkça belirtilir.

İstek

POST /api/vendor/v1/orders
Authorization: Bearer <token>
X-Idempotency-Key: ADS-ORD-99213
Content-Type: application/json

{
  "externalStoreId": "ADS-34781",
  "externalOrderId": "ADS-ORD-99213",
  "orderedAt": "2026-08-04T18:42:11+03:00",
  "readyAt": "2026-08-04T18:57:00+03:00",
  "recipient": {
    "name": "Merve Yıldırım",
    "phone": "5339876543"
  },
  "dropoff": {
    "text": "Cemal Gürsel Cad. No:45 D:8, Kurtuluş, Çankaya/Ankara",
    "latitude": 39.925310,
    "longitude": 32.862440,
    "buildingNo": "45",
    "doorNo": "8",
    "floor": "3",
    "note": "Zil çalışmıyor, kapıyı çalın"
  },
  "packageNote": "2 dürüm, 1 ayran",
  "orderAmount": 480.00,
  "payment": {
    "type": "Cash",
    "collectionAmount": 480.00
  }
}

Alanlar

Alan	Zorunlu	Kural	Karşılanmazsa
externalStoreId	evet	Kayıtlı ve Active durumda olmalı	409 STORE_NOT_CONFIGURED
externalOrderId	evet	Hesabınızda benzersiz, en fazla 64 karakter	409 DUPLICATE_ORDER
recipient.name	evet	En az 2 karakter	422 INVALID_RECIPIENT
recipient.phone	evet	10 hane; baştaki 0 ve +90 ön eki ayıklanır	422 INVALID_PHONE
dropoff.text	evet	En az 10 karakter	422 INVALID_ADDRESS
dropoff.latitude / longitude	evet	Türkiye sınırları içinde ve kurye şirketinin hizmet bölgesinde olmalı	422 COORDINATE_MISMATCH · 422 DROPOFF_OUT_OF_COVERAGE
orderedAt	hayır	ISO-8601. Saat dilimi belirtilmezse UTC+3 kabul edilir	—
readyAt	hayır	Boş bırakılırsa "şimdi" kabul edilir. Geçmiş bir saat verilirse şimdiye çekilir; 4 saatten uzak bir zaman kabul edilmez	422 READY_AT_TOO_FAR
packageNote	hayır	En fazla 500 karakter	—
orderAmount	hayır	Kayıt ve raporlama amacıyla saklanır	—
payment.type	hayır	Cash, Card veya Prepaid	—
payment.collectionAmount	hayır	Kuryenin kapıda tahsil edeceği tutar	—

readyAt

Bu alan, siparişin alındığı saati değil paketin mutfaktan çıkacağı saati belirtir. Kurye çağrısı bu saate göre planlanır. Teslimat kalitesini en çok etkileyen unsur, bu alanın doğru gönderilmesidir: erken gelen kurye beklemek zorunda kalır, geç gelen kurye soğumuş ürün taşır.

Koordinatlar

Kurye dropoff.text alanındaki adrese değil, koordinata yönlendirilir. Adres metni kuryenin kapıda okuduğu bilgidir; konum ise uygulamanın kuryeyi ulaştırdığı noktadır.

Türkiye sınırları dışındaki ve anlaşmalı kurye şirketinin hizmet vermediği koordinatlar reddedilir. Buna karşılık, geçerli görünen bir noktanın gönderilen adrese ait olup olmadığı doğrulanamaz. Bu nedenle mahalle merkezini değil, kendi harita servisinizin çözümlediği noktayı gönderin. Hatalı koordinat kuryeyi farklı bir adrese yönlendirir ve kurye yola çıktıktan sonra düzeltilemez.

payment

Tutar saklanır, kuryeye iletilir ve raporlara yansıtılır. Buna karşılık tahsilat süreci yürütülmez: kurye uygulamasında ödemenin alındığını bildiren bir onay adımı bulunmaz. Böyle bir adım, Hızlıyo'yu ödeme sürecini işleten taraf konumuna getirirdi. Kapıda ödeme, restoran ile kurye şirketi arasındaki ilişkide kalır.

Yanıt

{
  "success": true,
  "data": {
    "orderId": "e5a9f0d3-7c21-4b88-a06e-3f9182bd4471",
    "externalOrderId": "ADS-ORD-99213",
    "status": "Searching",
    "fleet": { "fleetId": "9d41...5e64", "name": "Başkent Moto Kurye" },
    "trackingUrl": "https://takip.hizliyo.com/d/8fK2mQ",
    "estimatedPickupAt": "2026-08-04T18:59:00+03:00"
  }
}

orderId değerini saklayın. Durum sorgusunda, iptal işleminde ve gelen bildirimlerde teslimat bu değerle tanımlanır.

Mükerrer gönderimin önlenmesi

X-Idempotency-Key başlığına siparişe özgü bir değer verin; kendi sipariş numaranız bu amaçla kullanılabilir. Aynı anahtar aynı içerikle yeniden gönderildiğinde ikinci bir teslimat oluşturulmaz, ilk yanıt aynen döndürülür. Aynı anahtarın farklı bir içerikle gönderilmesi 409 DUPLICATE_ORDER ile sonuçlanır.

Bu davranış sayesinde bağlantı kesintilerinde izlenecek yol nettir: aynı anahtarla yeniden gönderin; sipariş ya oluşturulur ya da hâlihazırda var olduğu bildirilir.

Yeniden gönderim

Başarısız istekler otomatik olarak yeniden denenmez

Başarısız olan istek orada sonlanır. İsteğin yeniden gönderilip gönderilmeyeceğine siz karar verirsiniz.

Bu davranış bilinçli bir tasarım tercihidir. Teslimat zamana duyarlı bir süreçtir. Kuyrukta bekletilip on dakika sonra işlenen bir sipariş, sorunu çoktan başka yolla çözmüş bir restorana ulaşır. Daha olumsuz bir sonuç olarak, hazırlanmayan bir ürün için kurye görevlendirilir.

Durumlara göre izlenecek yol:

• 401 TOKEN_EXPIRED — token'ı yenileyin ve isteği bir kez daha gönderin. Aynı idempotency anahtarıyla güvenlidir.
• 503 FLEET_UNAVAILABLE — o an müsait kurye yoktur. 60 saniye sonra yeniden denemek uygundur; bu süre zarfında restoranı bilgilendirin.
• 429 RATE_LIMITED — Retry-After başlığında belirtilen süre kadar bekleyin.
• Diğer kodlar — yeniden denemeyin. Durumu restorana bildirin, bkz. Hatalar.

Reddedilme durumları

Kod	Hata	Oluşma koşulu
423	FLEET_SUSPENDED	Mağazanın kurye şirketi geçici olarak sipariş kabul edemiyor
503	FLEET_UNAVAILABLE	İlgili bölgede müsait kurye bulunmuyor
409	STORE_NOT_CONFIGURED	Kurye şirketi bağlanmamış ya da mağaza kapalı
422	DROPOFF_OUT_OF_COVERAGE	Teslimat adresi kurye şirketinin hizmet bölgesi dışında

Kodların tamamı Hatalar sayfasında yer alır.