İçeriğe geç
KuryeSoft

Kaynaklar

En iyi uygulamalar

Sağlam bir entegrasyon için önerilen akış, hata ve yeniden deneme davranışı ve canlıya geçmeden önce denetlenecekler.

Önerilen akış

Müşteri adresi seçildi (ödeme öncesi)
KuryeSoft çağrısı:POST /quote: hizmet bölgesi ve teslimat ücreti. ok: false ise siparişi almayın.
Sipariş onaylandı
KuryeSoft çağrısı:POST /orders (konumla). Yanıttaki id ve tracking_url'yi saklayın; takip bağlantısını müşteriye gönderin.
Paket hazır
KuryeSoft çağrısı:POST /orders/{ref}/ready.
Sipariş iptal edildi
KuryeSoft çağrısı:POST /orders/{ref}/cancel (sebep ile). 403 gelirse kurye firmasına haber verin.
Webhook geldi
KuryeSoft çağrısı:İmzayı doğrulayın, durumu güncelleyin, 200 dönün.
Her 1–2 dakikada (yedek)
KuryeSoft çağrısı:Açık siparişler için 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ı, 429 ve 5xx durumunda artan aralıklarla birkaç kez yeniden deneyin; 429'da retry-after başlığına uyun.
  • 4xx hatalarını yeniden denemeyin; isteği düzeltin. Bkz. Hatalar.
  • Sipariş oluşturmayı tekrar denemek güvenlidir; aynı external_id yeni 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.
Örnek istemci
// 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:

  1. Webhook geldiğinde siparişin durumunu ve son güncelleme zamanını kaydedin.
  2. Her 1–2 dakikada bir, sonuçlanmamış ve son birkaç dakikada webhook almamış siparişleri GET /orders/{ref} ile sorgulayın.
  3. delivered, cancelled ya da failed olan 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, iptalde cancel çağrılıyor.
  • Webhook alıcısı imzayı ham gövdeyle doğruluyor, 8 saniyeden kısa sürede 200 dönüyor ve yinelenen olayları ayıklıyor.
  • Açık siparişler için yedek sorgu çalışıyor.
  • 4xx hataları kullanıcıya anlaşılır biçimde gösteriliyor; 429 ve 5xx yeniden deneniyor.
  • Deneme sırasında açılan siparişler iptal edildi.