Kaynaklar
En iyi uygulamalar
Önerilen akış
POST /quote: hizmet bölgesi ve teslimat ücreti. ok: false ise siparişi almayın.POST /orders (konumla). Yanıttaki id ve tracking_url'yi saklayın; takip bağlantısını müşteriye gönderin.POST /orders/{ref}/ready.POST /orders/{ref}/cancel (sebep ile). 403 gelirse kurye firmasına haber verin.200 dönün.GET /orders/{ref}.Zaman aşımı ve yeniden deneme
- Her isteğe 10–15 saniyelik bir zaman aşımı koyun.
- Zaman aşımı, bağlantı hatası,
429ve5xxdurumunda artan aralıklarla birkaç kez yeniden deneyin;429'daretry-afterbaşlığına uyun. 4xxhatalarını yeniden denemeyin; isteği düzeltin. Bkz. Hatalar.- Sipariş oluşturmayı tekrar denemek güvenlidir; aynı
external_idyeni sipariş açmaz. - KuryeSoft'a ulaşılamadığında siparişi kaybetmeyin: kendi tarafınızda "gönderilecek" olarak kuyrukta tutun ve bağlantı gelince gönderin.
// Node.js: zaman aşımı, 429 ve 5xx'te artan beklemeyle yeniden dener.
// Sipariş oluşturmada güvenlidir: aynı external_id ikinci sipariş açmaz.
async function kuryesoft(method, path, body, attempt = 0) {
let res;
try {
res = await fetch(`${process.env.KURYESOFT_URL}/api/v1${path}`, {
method,
headers: { "X-Api-Key": process.env.KURYESOFT_API_KEY, "Content-Type": "application/json" },
body: body ? JSON.stringify(body) : undefined,
signal: AbortSignal.timeout(15000),
});
} catch (err) {
if (attempt < 4) return retry();
throw err;
}
if ((res.status === 429 || res.status >= 500) && attempt < 4) {
return retry(Number(res.headers.get("retry-after")) || 0);
}
const data = await res.json();
if (!res.ok) throw Object.assign(new Error(data.error.message), { status: res.status, code: data.error.code, fields: data.error.fields });
return data;
function retry(seconds = 0) {
const wait = Math.max(seconds * 1000, 1000 * 2 ** attempt);
return new Promise((r) => setTimeout(r, wait)).then(() => kuryesoft(method, path, body, attempt + 1));
}
}Webhook ve yedek sorgu
Webhook'lar başarısız olursa yeniden gönderilmez. Durumun kaçmaması için webhook'u asıl kaynak, sorguyu yedek olarak kullanın:
- Webhook geldiğinde siparişin durumunu ve son güncelleme zamanını kaydedin.
- Her 1–2 dakikada bir, sonuçlanmamış ve son birkaç dakikada webhook almamış siparişleri
GET /orders/{ref}ile sorgulayın. delivered,cancelledya dafailedolan siparişleri sorgulamayı bırakın.
Webhook ve sorgu farklı sırada gelebilir. Bir siparişi, elinizdeki bilgiden daha eski bir duruma geri çekmeyin; zaman damgalarını (picked_up_at, delivered_at vb.) karşılaştırın.
Veri kalitesi
Adres ve konum
- Konumu mutlaka gönderin. Müşterinin haritada işaretlediği nokta, adres metninden bulunan noktadan daha doğrudur.
- Kat, daire ve tarifi ayrı alanlarda (
floor,apartment,directions) gönderin; kurye uygulamasında ayrı satırlarda görünür.
Telefon
Müşteri telefonunu gönderin: kurye gerektiğinde müşteriyi arar ve firma "yola çıktı" SMS'i ya da teslimat kodu kullanıyorsa bu numaraya gider. Türkiye dışındaki numaraların yalnızca rakamları saklanır (ör. +49 151 2345678 → 491512345678).
Tutarlar
total_amount sipariş tutarıdır; kapıda tahsilat farklıysa collect_amount verin. Ödeme alınmış siparişte ödeme türünü online göndermeyi unutmayın; aksi halde kurye kapıda para ister.
Canlıya geçiş listesi
Yayına almadan önce denetleyin
- API anahtarı yalnızca sunucuda, ortam değişkeninde; kodda ve günlüklerde yok.
- Taban adres kurye firmasının canlı adresi; HTTPS.
- Her siparişte benzersiz ve kalıcı bir
external_id; yeniden denemede aynısı gönderiliyor. - Konum (
lat,lng) her siparişte var. - Ödeme türü doğru eşleniyor (online ödenmiş sipariş kapıda tahsil edilmiyor).
- Paket hazır olduğunda
ready, iptaldecancelçağrılıyor. - Webhook alıcısı imzayı ham gövdeyle doğruluyor, 8 saniyeden kısa sürede
200dönüyor ve yinelenen olayları ayıklıyor. - Açık siparişler için yedek sorgu çalışıyor.
4xxhataları kullanıcıya anlaşılır biçimde gösteriliyor;429ve5xxyeniden deneniyor.- Deneme sırasında açılan siparişler iptal edildi.