Tekrar ve tekilleştirme

Ağ güvenilmez. Bu yüzden her iki yönde de aynı şeyin iki kez olabileceğini varsayarız ve iki tarafa da bunu zararsız kılacak bir araç veririz.

Size gelen: aynı olay iki kez

Bir olay gönderildi, siz işlediniz, ama yanıtınız bize ulaşmadı. Biz başarısız sayıp yeniden deneriz — siz aynı olayı ikinci kez alırsınız. Bu bir hata değil, normal çalışma.

Çözüm X-Veni-Delivery başlığıdır. Değeri teslimatın kimliğidir ve yeniden denemelerde değişmez (gövdedeki id ile aynıdır).

async function veniOlayiIsle(olay) {
  // Daha önce gördüysek hiçbir şey yapma.
  const yeni = await db.teslimatKaydet(olay.id); // benzersiz indeks
  if (!yeni) return;

  await isMantigi(olay);
}

Pratik kurallar:

• Teslimat kimliğini kalıcı bir yere yazın, bellekte tutmayın.
• Kaydı, işi yapmadan önce benzersiz bir kısıtla açın; sonra yazarsanız iki istek yarışır.
• Birkaç gün saklamak yeter: yeniden denemeler en geç ~2 günde biter.

Yanıtınız ne kadar sürerse

İşi yanıt vermeden önce yapmayın. Doğru akış: imzayı doğrula, olayı kendi kuyruğuna yaz, 200 dön, işi arkada yap.

Yavaş yanıt veren bir alıcı yalnız kendini yormaz — teslimat zaman aşımına uğrar, yeniden denenir ve siz aynı işi birkaç kez yaparsınız.

Yeniden deneme takvimi

Restoran ve POS webhook'ları gecikmeye duyarlı profille gider:

Deneme	Bekleme
1 → 2	10 saniye
2 → 3	30 saniye
3 → 4	2 dakika
4 → 5	10 dakika
5 → 6	30 dakika

Her beklemeye ±%20 rastgelelik eklenir. Bir teslimat 6 deneme yapar; altıncı da tutmazsa ulaşamayanlar listesine düşer ve oradan elle yeniden gönderilebilir.

Daha toleranslı alıcılar için 8 denemeli, iki günü aşan bir takvim de var. Profilleri ve ulaşamayanlar listesini Webhook'lar sayfası anlatır.

Bizim aldığımız: aynı isteği iki kez

Teslimat talebi açarken (POST /api/v1/b2b/deliveries) ağ zaman aşımına uğrarsa, isteğin bize ulaşıp ulaşmadığını bilemezsiniz.

Idempotency-Key teslimatı tekilleştirmez

Başlık okunuyor ve ödeme adımına iletiliyor; teslimat kaydı için tekilleştirme yok. Aynı anahtarla ikinci kez POST atarsanız ikinci bir teslimat açılır ve ikinci bir kurye çağrılır.

Nakit (payment_method: "cash") akışında başlık hiç kullanılmaz, çünkü o yolda ödeme adımı yoktur.

Başlığı yine de gönderin — ödeme tarafındaki tekrarı o çözüyor:

POST /api/v1/b2b/deliveries
Authorization: Bearer <partner anahtarı>
Idempotency-Key: SIP-1024
Content-Type: application/json

Anahtar olarak kendi sipariş numaranızı kullanmak en sağlıklısı: doğal olarak benzersizdir ve yeniden denemede aynı değeri üretmek kolaydır.

Zaman aşımında güvenli sıra

1. Yeniden göndermeyin.
2. GET /api/v1/b2b/deliveries ile son teslimatlarınızı okuyun.
3. Kendi siparişinize karşılık gelen bir kayıt var mı bakın. ⚠️ external_ref yanıt gövdesinde dönmez; eşlemeyi (delivery.id ↔ sizin sipariş numaranız) delivery.created webhook'undan kendi tarafınızda kurup saklamanız gerekir.
4. Kayıt yoksa gönderin.

Sizin bize gönderdikleriniz (gelen uçlar)

Size özel açılan POST /webhooks/in/{slug} adresinde tekillik (kaynak, olay kimliği) çiftiyle kurulur. Gövdenizde bir olay kimliği yoksa gövdenin özeti kullanılır — yani aynı gövdeyi iki kez göndermek iki kez işlenmez.

Ayrıntı: Gelen uçlar.

Özet

Yön	Araç	Kim kullanır
Veni → siz	X-Veni-Delivery	Siz, tekrarı atlamak için
Siz → Veni (teslimat)	Idempotency-Key	Siz, ödeme adımındaki tekrarı çözmek için
Siz → Veni (gelen uç)	Olay kimliği ya da gövde özeti	Biz, otomatik