En iyi uygulamalar

Adres

• Koordinat gönderin. dropoff.lat/lng varsa sipariş hemen kurye arar; yoksa adres doğrulanana kadar bekler (dakikalar kaybedilir).
• Konum yoksa alanı hiç göndermeyin; 0,0 yazmayın. 0,0 ve Türkiye dışı konum yok sayılır, sipariş adres çözümüne düşer.
• Sipariş almadan önce POST /v1/quotes ile hizmet alanını sorun. Alan dışı adres sipariş açılırken 422 HIZMET_DISI ile reddedilir; restorana hemen gösterin.
• Kat, daire, zil, “eczanenin üstü” gibi tarifleri dropoff.directions'a yazın; text yalnız adres olsun. Tarif kuryeye adresin yanında görünür ama adres aramasına karışmaz.
• Mahalle, ilçe, il biliniyorsa ayrı alanlarda gönderin (neighborhood, district, city); koordinatsız siparişte adres aramasına ipucu olur.
• Müşteri telefonu kurye için en önemli alandır; mümkünse her siparişte gönderin.

Hazır olma saati

• Mutfak tahmini biliyorsanız ready_at gönderin: kurye o saatte restoranda olmayı hedefler, boşuna beklemez.
• Paket erken hazır olursa PATCH ile ready_at'i şimdiye çekin.
• Müşteri belli saatte istiyorsa ready_at değil scheduled_for kullanın: kurye ataması o saatten önce başlar.

Tekrar güvenliği

• Her sipariş için sabit bir Idempotency-Key kullanın (ör. kendi sipariş numaranız). Zaman aşımı aldığınızda aynı anahtarla yeniden gönderin; çift teslimat açılmaz.
• Webhook'ları webhook-id ile tekrar işlemeyin; sırayı data.version ile belirleyin.
• Webhook adresiniz kapalı kaldıysa GET /v1/deliveries?since=… ile eşitleyin.
• Yanıtı gelmeyen gönderim: önce GET /v1/deliveries?external_ref=…&external_store_id=… ile siparişin açılıp açılmadığını sorun; açılmışsa yeniden göndermeyin. 409 EXTERNAL_REF_TEKRAR aldığınızda error.details.delivery_id mevcut siparişi gösterir.
• Erişim jetonunu 30 dakika saklayıp yeniden kullanın; her istekte jeton almayın (/oauth/token dakikada 30).
• Bağlantıyı canlı kimlikle sınamak için test: true gönderin: sipariş kuryeye düşmez, hemen iptal edilir, webhook'lar gider.

Saat dilimi

Zamanları her zaman saat dilimiyle gönderin: 2026-10-11T19:30:00+03:00. Saat dilimsiz zaman reddedilir (yanlış saatte kurye çağırmaktansa). Yanıtlar UTC'dir (…Z); ekranda İstanbul saatine çevirin.

İptal ve değişiklik

• Müşteri vazgeçerse hemen iptal edin (POST /v1/deliveries/{id}/cancel, sebeple). Kurye yola çıkmadan iptal hem kuryeyi hem restoranı kurtarır.
• Paket kuryedeyse (KURYE_ALDI) yazılımınız kullanıcıya “restoranın kurye firmasını arayın” demeli; değişiklik ve iptal artık firmanın elindedir.

Pazaryeri siparişleri (Yemeksepeti, Getir, Trendyol, Migros)

Betakurye pazaryerlerine doğrudan bağlanmaz; siparişi POS'unuz iletir. Restoranın kendi kuryesiyle çalıştığı pazaryeri siparişini Betakurye'ye gönderirken:

• origin_channel'a kaynağı yazın (yemeksepeti, getir, trendyol, migros); kurye ve restoran ekranında rozet olarak görünür.
• Ödeme platformda alındıysa platformun ödeme kodunu ve prepaid: true gönderin. Aynı kod kanala göre değişebilir: örneğin 13 (SETCARDCEK) Trendyol'da çevrim içi ödenmiş Setcard'dır, telefon siparişinde kapıda alınan Set Çeki. Kanal platformsa prepaid: true gönderin.
• Müşteri numarası gizliyse (Getir, Trendyol): customer.phone'a platformun çağrı merkezini, customer.phone_extension'a arama kodunu yazın. Kurye uygulaması santrali arar ve kodu kendisi tuşlar; müşteriye takip SMS'i gitmez.
• Pazaryerine durum bildirmeniz gerekiyorsa Betakurye webhook'larını çevirin: örneğin Getir Yemek'in restoran kuryesi uçlarında delivery.picked_up → “kuryeye verildi”, delivery.delivered → “teslim edildi”.

Teslim PIN'i

Değerli ya da kapıda tartışma çıkan siparişlerde require_pin: true gönderin ve delivery_pin'i müşteriye kendi kanalınızdan (SMS, uygulama bildirimi, sipariş ekranı) iletin. Kod takip sayfasında da görünür.