Güvenilir API Entegrasyonu: Zaman Aşımında Siparişleri Tekrarlamadan İlerlemek

Kargo oluştur düğmesine bastınız, ancak yanıt gelmedi. İstek taşıyıcıya hiç ulaşmamış olabilir. Etiket oluşturulmuş, fakat dönüş sırasında bağlantı kopmuş da olabilir. İki durumu da başarısız diye göstermek, çalışanı yeniden denemeye yönlendirir ve iki etiketle iki ücret doğurabilir. Güvenilir API entegrasyonu, tek bir başarılı çağrıdan ibaret değildir; bilinmeyen sonucu saklayıp güvenli biçimde açıklığa kavuşturabilmelidir.

Uç noktadan önce iş işlemini tanımlayın

Her entegrasyon için kısa bir işlem kartı hazırlayın: hangi iş yapılacak, hangi bilgiler gerekli, nihai sonucun kaynağı kim, sonuç sonradan sorgulanabilir mi, tekrarlamanın maliyeti nedir? Harita hizmetinden şehir aramak ile kurye rezervasyonu oluşturmak aynı riskte değildir. API adresi ve erişim anahtarı, eksik yanıtın işletmede nasıl ele alınacağını açıklamaz.

Varsayımsal bir kitapçıda ORD-204 siparişi için tek kargo oluşturulduğunu düşünün. Müşteri teslimat adresini onaylamıştır. Onaylanan adres sürümünü, gönderilecek ürünlerle birlikte kaydedin. Sipariş sayfasını yeniden açmak, gönderilmiş işleme ait veriyi sessizce değiştirmesin. İptalin anlamını da belirleyin: yerel taslağı bırakmak ile taşıyıcının kabul ettiği rezervasyonu iptal etmek ayrı işlemlerdir. Bu sınırları proje özetine ekleyin.

Düğmenin görünümünü değil, bilinen durumu modelleyin

Örnek akış; hazır, işleniyor, doğrulama bekliyor, onaylandı ve inceleme gerekiyor durumlarını ayırabilir. Dış hizmete bağlanmadan önce kalıcı bir işlem referansı oluşturun. Güvenilir başarı yanıtı gelince taşıyıcının kargo kimliğini buna bağlayın. Kesin yanıt alınmadan süre dolarsa işlemi doğrulama bekliyor durumuna taşıyın; iptal edilmiş veya yeniden oluşturulmaya hazır kabul etmeyin.

MDN'nin idempotency açıklaması, çağrının tekrarı ile etkisinin tekrarı arasındaki farkı anlatır; POST için bu özellik kendiliğinden garanti edilmez. Yeniden deneme kararını sağlayıcının sözleşmesine göre verin. Düğmeyi kısa süre kapatmak arayüzü iyileştirir, fakat sayfa yenilemesini, başka cihazı veya eşzamanlı istekleri güvence altına almaz.

Bir mantıksal işlem için aynı yeniden deneme kimliğini koruyun

Sağlayıcı tekrarları önleyen bir idempotency anahtarı destekliyorsa, aynı işlemi aynı parametrelerle tekrar ederken anahtarı koruyun. Her tıklamada yeni anahtar üretmek amacını bozar. Eski kargonun anahtarını yeni bir kargoda kullanmak da yanlıştır. Stripe belgelerinde saklama süresi ve parametre karşılaştırması için belirli kurallar bulunur; başka sağlayıcıların da aynı şekilde çalıştığını varsaymayın.

Taşıyıcının SH-781 kaydını oluşturduğunu, ancak yanıtın kaybolduğunu varsayalım. ORD-204 ilk işlemle bağlantılı kalır. Takip görevi, desteklenen satıcı referansı veya anahtarla sonucu sorgular, eşleşmeyi doğrular ve SH-781 kimliğini kaydeder. Güvenli sorgulama ya da tekrar önleme yoksa başka bir yazma işleminden önce insan incelemesi gerekebilir. Ücretli işlemin gerçekleşip gerçekleşmediğini tahmin etmek yerine kontrollü beklemek daha doğru olabilir.

Süre ve deneme sayısına sınır koyun

• Her çağrıya zaman aşımı, bütün işleme de azami süre tanımlayın; müşteri sonsuza kadar beklemesin.
• Eksik adresi, geçersiz erişim bilgisini, hız sınırlamasını ve sonucu belirsiz kesintiyi ayrı değerlendirin.
• Tekrar güvenliyse giderek uzayan, küçük rastgele farklılıklar içeren aralıklar ve sınırlı deneme sayısı kullanın.
• Denemeler tükenince kaydı kaybetmek yerine açıklanmış bir sonraki adımla inceleme listesine alın.

Sağlayıcının Retry-After yanıtı tarih veya saniye cinsinden süre içerebilir. JavaScript kullanırken fetch çağrısının yalnızca 404 gibi bir HTTP hatası nedeniyle reddedilmediğini unutmayın; yanıt durumunu inceleyin. Yerel beklemeyi durdurmak, uzak sunucunun tamamladığı işi geri almaz.

Sonradan gelen olayları iş akışına dahil edin

Sonuç, müşterinin dönüş sayfası yerine webhook ile gelebilir. Stripe olay belgeleri imza doğrulamasını ve yinelenen olayları ele alır; kullandığınız sağlayıcının karşılık gelen kurallarını ayrıca inceleyin. Kitapçı örneğinde eski bir olay, teslim edilmiş kargoyu yeniden hazırlanıyor durumuna döndürmemelidir. Güncellemeden önce sağlayıcı hesabını, işlem referansını ve olay türünü karşılaştırın.

Doğrulanmış olayı daha sonra işleyecekseniz, alındığını bildirmeden önce kalıcı biçimde saklayın. İşlenen olayların kaydını tutun; uzun süredir doğrulama bekleyen işler için mutabakat kontrolü ekleyin. Yalnızca bildirim beklemek kurtarma planı değildir. Çalışanın ekranında işlem referansı, son deneme zamanı, ne kadar süredir beklediği ve güvenli sonraki adım bulunsun. Erişim anahtarını veya müşteri bilgileri içeren ham yanıtı göstermeyin.

Başarısızlık senaryosunu kabul testine dönüştürün

1. Taşıyıcı isteği kabul etti, yanıt kayboldu: takip sonunda iki değil tek kargo bulunuyor mu?
2. Aynı onay iki kez geldi: işletme sonucu yalnızca bir kez kaydediliyor mu?
3. Eski olay yenisinden sonra geldi: geçerli son durum korunuyor mu?
4. Arka plan görevi yarıda yeniden başladı: kalıcı kaydı bulup güvenli devam ediyor mu?
5. Hizmet düzelmedi: çalışan gizli bilgi görmeden uygulanabilir bir talimat alıyor mu?

Önce kontrollü veriler ve taklit sağlayıcıyla, ardından yetkili deneme ortamında çalışın. Senaryoları otomatik test planınıza dahil edin. Neleri maskeleyeceğinizi belirlerken OWASP günlükleme rehberini kullanın. Paylaşılması güvenli, zaman damgalı bir işlem özeti; okunamayan büyük bir veri dökümünden daha faydalıdır.

Her çağrı için arka plan kuyruğu gerekir mi? Hayır. Hızlı bir okuma için süre sınırı ve anlaşılır mesaj yeterli olabilir. Yavaş, maliyetli veya tarayıcı kapansa da takip edilmesi gereken işlerde kalıcı kayıt önem kazanır. Ayrıca kuyruk, eksik tekrar önleme politikasını kendiliğinden çözmez; kuyruktaki aynı iş tekrar çalışabilir. Kullanacağınız yapıyı aracın popülerliğine değil, kesintinin sonucuna göre seçin.

Bu yazı yapay zekâ desteğiyle hazırlanmıştır; ayrıntıların doğrulanabilmesi için teknik kaynaklar eklenmiştir.