Entegrasyon projelerinde hatalar nerede toplanır?
İki başlıkta: tekrarlanan isteklerin çift kayıt üretmesi ve gelen bildirimlerin doğrulanmaması. Ağ zaman aşımında istemci isteği tekrarlar; sunucu bunu yeni işlem sayarsa ikinci sipariş, ikinci fatura veya ikinci ödeme oluşur. Her iki konuyu [idempotency ve callback güvenliği rehberimizde](/blog/entegrasyon-api-rehberi) ayrıntılandırıyoruz.
Ne yapıyoruz?
- Entegrasyon envanteri: hangi veri hangi sistemde doğrulanır, çakışmada hangisi kazanır
- İşlem anahtarı (idempotency) tasarımı ve tekrar koruması
- Webhook imza doğrulama, zaman penceresi ve tekrar oynatma koruması
- Kuyruk tabanlı işleme, yeniden deneme politikası ve hatalı kayıt kuyruğu
- Mutabakat raporları ve fark analizi
- İzleme panosu: bekleyen kuyruk, işlenme gecikmesi, hatalı kayıt sayısı
Bildirimi kaynak olarak kabul etmiyoruz
Gelen webkanca çağrısı yalnızca “bir şey oldu” bilgisidir. Tutar, durum ve sonuç, göndericinin API'sinden yeniden okunarak doğrulanır. Çağrıyı hızla kabul edip kuyruğa yazıyor, iş mantığını kuyruktan yürütüyoruz; böylece gönderici tarafında zaman aşımı ve gereksiz tekrar oluşmuyor.
Sık kurduğumuz uçlar
Banka hesap hareketi ve ödeme talimatı ([banka entegrasyonu](/urunler/banka-entegrasyonu)), e-fatura ve e-arşiv, sanal POS, kargo firmaları, pazaryeri servisleri, muhasebe ve ERP sistemleri, PDKS cihazları ve kurumsal kimlik doğrulama.
“Tam olarak bir kez” bir yanılgıdır
Dağıtık sistemlerde mesajın tam olarak bir kez ulaştığı garanti edilemez. Gerçekçi hedef, mesajın en az bir kez ulaşması ve alıcının tekrarları etkisiz hâle getirmesidir; bu yüzden tüketici tarafında da olay kimliğiyle tekrar kontrolü kuruyoruz.
Sık sorulan sorular
Webhook mu, düzenli sorgulama mı?
Hacim düşük ve gecikme toleransı varsa düzenli sorgulama daha basit ve daha güvenilirdir. Yüksek hacimde ikisini birlikte kullanmak yaygındır: webhook hızlı bildirim için, periyodik sorgulama kaçan olayların telafisi için.
Mevcut sistemimizin API'si yoksa ne yapılır?
Veritabanı seviyesinde okuma, dosya tabanlı aktarım veya ara katman servis geliştirme seçenekleri değerlendirilir. Hangi yöntem seçilirse seçilsin, tekrar koruması ve mutabakat raporu aynı şekilde kurulur.
Entegrasyonun sağlıklı çalıştığını nasıl anlarız?
Üç sayı izlenir: bekleyen kuyruk uzunluğu, ortalama işlenme gecikmesi ve hatalı kuyruğa düşen kayıt sayısı. Bu üçü panoda görünmüyorsa entegrasyonun çalıştığı bir varsayımdır.