API Entegrasyonu Öncesi: Veri Eşleme ve Hata Senaryoları

API entegrasyonlarında işin zor kısmı bağlantı kurmak değildir; iki sistemin aynı şeyi farklı isimlerle, farklı biçimlerde ve farklı kurallarla tutmasıdır. Kodu yazmadan önce iki tabloyu hazırlamak, geliştirme sırasında çıkan sürprizlerin büyük bölümünü masaya erken taşır: bir alan eşleme tablosu, bir de hata senaryosu tablosu.

Önce şu dört soruyu cevaplayın

Entegrasyon toplantısına bu cevaplar olmadan girmeyin. Hepsi teknik değil, ama hepsi projenin gidişatını belirler.

1. Doğruluk kaynağı kim? Stok, fiyat ve müşteri bilgisi hangi sistemde tutulur, hangisi kopya taşır? İki taraf da "ben yazarım" derse çakışma kaçınılmazdır.
2. Yön nedir? Tek yönlü mü (muhasebeye sipariş gönder), çift yönlü mü (stok gelsin, sipariş gitsin)? Çift yönde çakışma çözümü, döngü koruması ve iki ayrı hata yolu da eklenir; bu yüzden iş yükü tek yönün basit bir katı değildir.
3. Tetikleyici nedir? Anlık çağrı mı, webhook mu, zamanlanmış görev mi? Paylaşımlı hosting'de cron çoğu zaman en gerçekçi seçenektir.
4. Gecikme toleransı ne? Stok 5 dakika geç güncellenirse ne olur? "Anlık" talebi, gerçek ihtiyaç 15 dakikayken bütçeyi gereksiz büyütür.

Veri eşleme tablosu: entegrasyonun omurgası

Her alan için sütunları belli bir tablo çıkarın. Bunu bir e-tablo olarak tutmak ve karşı tarafla mutabık kalmak, sonradan çıkacak "biz öyle anlamamıştık" tartışmasını bitirir.

Eşlemede en sık patlayan yerler

• Para ve yuvarlama: kuruş farkları toplamda tutmazsa muhasebe entegrasyonu kaydı reddeder. Tek kural belirleyin: satır bazında mı yuvarlanacak, toplamda mı? İkisi farklı sonuç verir.
• Ondalık ayırıcı: ekranda 1.299,90 gördüğünüz değer API'ye 1299.90 gider. Biçimlendirmeyi sunuma bırakın, veriye karıştırmayın.
• Tarih ve saat dilimi: karşı taraf UTC gönderiyorsa üç saatlik kayma gün sınırındaki raporları bozar. Depolamayı tek dilimde yapın, çevrimi gösterimde uygulayın.
• Karakter kodlaması: Türkçe karakterlerin bozulmaması için iki uçta da UTF-8 doğrulayın; özellikle CSV alışverişinde kontrol edin.
• Uzunluk sınırları: ürün adınız 200 karakterse ve karşı taraf 100 kabul ediyorsa kesme kuralını siz yazın, yoksa API sizin yerinize keser.
• Sabit listeler: sipariş durumu, ödeme tipi, birim gibi alanlar için iki taraflı bir sözlük tutun; serbest metin göndermeyin.

Kimlik ve mükerrer kayıt: en pahalı hata

Aynı siparişin muhasebeye iki kez düşmesi, entegrasyon projelerinin klasik kazasıdır. Aşağıdaki üç önlem birlikte uygulandığında bu kaza pratikte ortadan kalkar.

• Kendi tablonuza harici kimlik kolonu ekleyin ve benzersiz indeksle koruyun. Karşı sistemin verdiği kayıt numarasını bu kolonda tutarsınız.
• Gönderdiğiniz her isteğe tekrar-güvenli anahtar koyun (örneğin sipariş numarası). Aynı anahtarla ikinci istek geldiğinde karşı taraf yeni kayıt açmamalıdır.
• Webhook alırken imza doğrulayın ve aynı olay kimliğini ikinci kez işlemeyin. Ödeme sağlayıcıları ağ sorunlarında aynı bildirimi tekrar gönderebilir; bu normaldir, buna hazırlıklı olmak sizin işinizdir.

Hata senaryolarını kod yazmadan listeleyin

Her şeyin yolunda gittiği senaryo genelde ilk günde çalışır; zaman kaybı diğer senaryolarda yaşanır. Aşağıdaki sekiz satırın her biri için "ne yaparız" cevabını yazılı olarak verin.

• Zaman aşımı: istek gitti, cevap gelmedi; kayıt oluştu mu bilmiyorsunuz. Çözüm: harici kimlikle sorgula, yoksa tekrar-güvenli anahtarla yeniden dene.
• Hız sınırı (429): dakikada kaç istek hakkınız var? Toplu aktarımı gruplara bölün, aralarda bekleyin.
• Sunucu hatası (5xx): karşı taraf geçici olarak kapalı. Artan aralıklarla yeniden deneyin (1, 5, 15, 60 dakika), belli bir denemeden sonra kaydı "elde işlenecek" listesine taşıyın.
• Yetki hatası (401/403): anahtar süresi doldu veya IP kısıtı devrede. Bu hata yeniden denemeyle çözülmez, insana bildirim gitmelidir.
• Doğrulama hatası: zorunlu alan eksik, ilçe kodu tanınmıyor. Kaydı reddedin ve nedenini panelde okunur biçimde gösterin; sessizce atlamayın.
• Kısmi başarı: 20 kalemin 18'i geçti. Ya hepsi ya hiçbiri kuralını uygulayın veya kalem bazında durum tutun; ortası kaos üretir.
• Şema değişikliği: karşı taraf haber vermeden alan adı değiştirdi. Beklenmeyen yanıtta çökmek yerine kaydedip alarm üretin.
• Ters kayıt: sipariş iptal edildi veya iade oldu. İptalin karşı sisteme nasıl gideceğini baştan tasarlayın; sonradan eklemesi en zor parça budur.

Yeniden deneme ve kuyruk

Entegrasyonu doğrudan kullanıcının bastığı butona bağlamayın. Doğru desen şudur: işlem bir kuyruk tablosuna yazılır, zamanlanmış görev kuyruğu işler, başarısızlar deneme sayısıyla birlikte kalır, üç denemeyi geçenler ayrı bir listeye düşer ve sorumluya e-posta gider. Bu yapı hem müşteriyi bekletmez hem de karşı taraf çöktüğünde veri kaybettirmez.

Canlıya alma kontrol listesi

• Test ortamında en az 20 gerçekçi kayıtla deneme yapıldı mı; aralarında Türkçe karakterli ve uzun adlı olanlar var mı?
• Anahtarlar kod içine gömülmek yerine ortam dosyasında mı tutuluyor?
• Her istek ve yanıt kaydediliyor mu; kart bilgisi ve kişisel veriler kayıtlarda maskeleniyor mu? Kişisel veri barındıran günlüklerde maskeleme, KVKK uyumu açısından tercih değil gerekliliktir.
• İlk gün için sınırlı kapsam belirlendi mi (örneğin yalnızca tek kategori ya da günde 50 sipariş)?
• Entegrasyonu kapatma anahtarı var mı? Karşı taraf çökerse sitenizi ayakta tutan tek şey budur.
• Mutabakat raporu tanımlandı mı: iki sistemdeki kayıt sayısı ve toplam tutar günlük karşılaştırılıyor mu?

Uygulanabilir özet

1. Alan eşleme tablosunu kod yazmadan çıkarın ve karşı tarafla yazılı mutabık kalın.
2. Mükerrer kaydı harici kimlik kolonu ve tekrar-güvenli anahtarla baştan engelleyin.
3. Yukarıdaki sekiz hata senaryosunun her biri için davranışı yazın; "olmaz herhalde" bir cevap değildir.
4. Kuyruk ve zamanlanmış görev deseniyle çalışın, arayüzü karşı tarafın hızına bağlamayın.
5. İlk hafta günlük mutabakat yapın; fark bir kalemse bugün, bin kalemse üç ay sonra fark edersiniz.