Çoğu kişi tedarikçi API hatası gördüğünde suçluyu hemen tedarikçide arar. Panelde kırmızı bir satır, yanında "API hatası" yazan tek cümlelik bir mesaj ve arkada bekleyen bir sipariş. Telefon açılır, tedarikçiye "sizin sistem çöktü" denir, tedarikçi "bizde sorun yok" der ve iş orada kilitlenir. Oysa bu mesaj bir teşhis değil, teşhis eksikliğinin itirafıdır.
Gerçek şu: "API hatası" tek bir arıza değil, en az altı farklı katmanın konuşabileceği bir başlıktır. Kimlik doğrulama, yetkilendirme, ağ, hız limiti, iş kuralı ve mutabakat. Hangisinin konuştuğunu bilmeden yapılan her müdahale ya hiçbir şeyi düzeltmez ya da çift teslimat gibi daha pahalı bir hataya yol açar. Bu yazıda katmanları tek tek ayıralım.
API hatası tek bir şey değildir: hangi katman konuşuyor?
Her entegrasyon çağrısı dört aşamadan geçer: isteği kur, bağlantıyı aç, yanıtı al, yanıtı yorumla. Hata bu aşamaların hangisinde çıktıysa çözüm tamamen farklıdır. Bağlantı hiç açılmadıysa ağ veya IP izni meselesi vardır. Açıldı ama HTTP 4xx döndüyse senin isteğinde bir sorun var demektir. 5xx döndüyse gerçekten karşı taraf sıkıntıdadır. Yanıt geldi ama yorumlanamadıysa sözleşme değişmiştir.
Bu yüzden bir dijital ürün satış scriptinin entegrasyon kaydı en az beş alan tutmalıdır: gönderilen istek gövdesi, HTTP durum kodu, ham yanıt gövdesi, geçen süre ve deneme sırası. Bu beş alan varsa arızayı beş dakikada sınıflandırırsın; yoksa tedarikçiyle karşılıklı suçlama döngüsüne girersin ve müşteri beklemeye devam eder.
Ham yanıt gövdesini saklamayan bir entegrasyon, teşhis edilemez bir entegrasyondur. Çoğu tedarikçi hatanın gerçek nedenini yanıt gövdesindeki mesaj alanında açıkça yazar; yazılım o gövdeyi atıp yerine kendi genel cümlesini koyduğunda en değerli bilgi çöpe gider.
401 ve 403 aldığında ilk bakacağın yer token değil, IP listesi olabilir
Kimlik doğrulama hataları iki gruba ayrılır. 401 "seni tanımıyorum" demektir: anahtar yanlış, süresi geçmiş veya yanlış başlıkta gönderiliyor. 403 ise "seni tanıdım ama bu işi yapamazsın" demektir ve burada en sık sebep anahtar değil, IP kısıtlamasıdır. Tedarikçilerin büyük kısmı bayi anahtarını belirli IP adresleriyle eşler.
Bu yüzden sunucu taşıdığında, bulut güvenlik katmanı ekledğinde veya barındırma sağlayıcın çıkış IP'sini değiştirdiğinde entegrasyon hiçbir kod değişmeden çöker. Belirti kafa karıştırıcı biçimde "dün çalışıyordu" şeklinde gelir. Kontrol yöntemi basit: sunucunun dışarıya çıkarken kullandığı gerçek IP'yi öğren ve tedarikçi panelindeki izin listesiyle karşılaştır.
İkinci yaygın tuzak jeton yenilemesidir. Süreli erişim jetonu kullanan tedarikçilerde jeton dolduğunda yazılım onu otomatik yenilemeli; yenileme mantığı yoksa entegrasyon her gün aynı saatte kendiliğinden bozulur ve elle müdahaleyle düzelir. Bu belirtiyi görüyorsan sorunun tamamı jeton ömrüdür. Pinova'nın tedarikçi katmanında jeton yenilemesi ve IP değişikliği uyarısı ayrı ayrı izlenir; ayrıntıları özellikler bölümünde bulabilirsin.
| Durum kodu | Gerçek anlamı | En sık kök neden | Doğru davranış |
|---|---|---|---|
| 401 | Kimlik doğrulanamadı | Süresi geçmiş jeton, yanlış başlık | Jetonu yenile, tekrar deneme yapma |
| 403 | Yetki yok | IP izin listesi uyuşmazlığı | Çıkış IP'sini güncelle, yöneticiye bildir |
| 404 | Ürün veya uç nokta yok | Tedarikçi ürün kodu değişmiş | Ürün eşlemesini yeniden kur |
| 409 | Çakışma | Aynı referansla ikinci istek | Mevcut siparişi sorgula, yeni açma |
| 422 | İş kuralı reddi | Bakiye yetersiz, tutar uyumsuz | Siparişi beklemeye al, elle müdahale |
| 429 | Hız limiti aşıldı | Eşzamanlı çok istek | Artan gecikmeyle tekrar dene |
| 5xx | Tedarikçi tarafı arıza | Geçici kesinti veya bakım | Kuyruğa al, yedek tedarikçiye yönlen |
| Zaman aşımı | Sonuç bilinmiyor | Yavaş yanıt, ağ kesintisi | Asla kör tekrar deneme, önce durum sorgula |
Zaman aşımı hatasında para gitti mi, kod geldi mi? Asıl mesele mutabakat
Entegrasyonun en tehlikeli hatası zaman aşımıdır, çünkü bir hata değil bir bilinmezliktir. İstek gitti, yanıt gelmedi. Tedarikçi tarafında sipariş oluşmuş ve kod ayrılmış olabilir; hiç oluşmamış da olabilir. Bu durumda yazılımın körü körüne isteği tekrar göndermesi, aynı müşteriye ikinci kez ürün satın alınması ve senin cebinden çift maliyet çıkması anlamına gelir.
Doğru çözüm her istek için kendi tarafında ürettiğin tekil bir referans numarası göndermektir. Tedarikçi bu referansı destekliyorsa aynı referansla gelen ikinci isteği yeni sipariş olarak işlemez, ilkinin sonucunu döner. Desteklemiyorsa akış değişir: zaman aşımından sonra asla yeni sipariş açma, önce sipariş sorgulama uç noktasından o referansın durumunu sor, sonucu ona göre işle.
Bunun üstüne bir de günlük mutabakat koymalısın. Gün sonunda kendi kayıtlarındaki tedarikçi siparişleriyle tedarikçi panelindeki hareketleri karşılaştır. Bir tarafta olup diğerinde olmayan kayıtlar, tam olarak zaman aşımlarının bıraktığı izlerdir ve düzeltilmediğinde ay sonunda kaybolan paraya dönüşür.
Tedarikçi entegrasyon hatalarının kök neden dağılımı
- Kimlik, yetki ve IP izni sorunları 50%
- Zaman aşımı ve mutabakat kayıpları 25%
- Hız limiti ve eşzamanlılık 15%
- Sözleşme değişikliği ve ürün eşlemesi 10%
Tedarikçi limitini aştığında (429) kuyruğun ne yapıyor?
Kampanya saatinde otuz sipariş aynı saniyede düşer ve yazılım otuz isteği paralel gönderir. Tedarikçi saniyede beş istek kabul ediyorsa geri kalan yirmi beşi reddeder. Kötü kurulmuş bir sistem bu reddi kalıcı hata sayıp siparişleri iptale çeker; işin acısı, tedarikçi tarafında hiçbir arıza yoktur, sadece sen çok hızlı vurdun.
Doğru davranış üç parçadır. Birincisi eşzamanlılık sınırı: tedarikçi başına en çok kaç isteğin aynı anda uçabileceğini yazılımda tanımlamak. İkincisi artan gecikmeli tekrar deneme: ilk denemede bir saniye, sonra iki, sonra dört bekleyip yeniden denemek ve deneme sayısını sınırlamak. Üçüncüsü devre kesici: belirli sayıda üst üste hata aldıktan sonra o tedarikçiyi kısa süre devre dışı bırakıp siparişleri kuyrukta tutmak.
Devre kesici en çok ihmal edilen parçadır ama en çok işe yarayandır. Çöken bir tedarikçiye dakikada yüzlerce istek atmak hem onun toparlanmasını geciktirir hem senin sunucunu meşgul eder hem de bayi hesabının geçici olarak kısıtlanmasına yol açabilir. Kırk beş saniye beklemek, kırk beş dakika beklemekten iyidir.
Yanıt gelmediyse sonuç bilinmiyordur. Önce tekil referansla durum sorgusu yap; kör tekrar deneme çift satın alma ve çift maliyet üretir.
Stok senkronizasyonu bozulduğunda müşteriye boş kutu mu satıyorsun?
Entegrasyonun sessiz arızası stok bilgisidir. Tedarikçi tarafında ürün tükenmiştir ama senin vitrininde hâlâ satılabilir görünür. Müşteri ödemeyi yapar, teslimat adımında tedarikçi "stok yok" der ve elinde tahsil edilmiş bir para, teslim edilemeyen bir sipariş kalır. Bu vaka teknik olarak küçük, itibar olarak büyüktür.
Önlemi iki katmanlıdır. Birincisi periyodik stok tazelemesi: ürün bazında son güncelleme zaman damgası tutmak ve belirli bir süreden eski veriyi "güvenilmez" saymak. İkincisi satın alma anında son kontrol: ödeme tamamlanmadan hemen önce tedarikçiden anlık uygunluk sorgusu yapmak. İkinci kontrol birkaç yüz milisaniye maliyetlidir ve sepet terkine etkisi ihmal edilebilir düzeydedir.
Bir de fiyat senkronizasyonu var. Tedarikçi alış fiyatını güncellediğinde senin satış fiyatın olduğu yerde kalırsa zararına satış yapmaya başlarsın ve bunu genelde ay sonu raporunda fark edersin. Kural bazlı fiyatlandırma, yani alış üzerine yüzde veya sabit marj tanımlayıp fiyatı otomatik hesaplatmak, bu riski tamamen ortadan kaldırır.
Birden fazla tedarikçi ve otomatik yedekleme neden zorunlu?
Tek tedarikçiye bağlı bir dijital ürün satış yazılımı, o tedarikçinin bakım penceresinde kapalı dükkândır. Ciddi hacim yapan işletmelerin ortak refleksi aynı ürün için en az iki tedarikçi tanımlamak ve yazılımın birincil kaynak yanıt vermediğinde ikincisine otomatik geçmesidir.
Yedekleme mantığı basit kurallar üzerine kurulur: maliyet sırası, stok durumu, son yüz istekteki başarı oranı ve ortalama yanıt süresi. Birincil tedarikçi üst üste hata verdiğinde devre kesici onu geçici olarak dışarı alır, sipariş ikinciden karşılanır, birincil toparlandığında otomatik geri döner. Müşteri bu geçişin farkına bile varmaz.
Son olarak izleme: her tedarikçi için başarı oranı, ortalama yanıt süresi ve son hata mesajı panelde görünür olmalı. Böylece "tedarikçi mi ben mi" tartışmasına veriyle girersin. Hangi paketin kaç tedarikçi bağlantısı ve hangi izleme araçlarını içerdiğini fiyat sayfasında karşılaştırabilir, kurulum için panel üzerinden ilerleyebilirsin.
| Kontrol | Nasıl doğrulanır | Beklenen durum | Risk seviyesi |
|---|---|---|---|
| Ham yanıt kaydı | Entegrasyon kaydında bir hatayı aç | İstek, kod, gövde, süre görünüyor | Kritik |
| Tekil referans gönderimi | Aynı siparişi iki kez tetikle | İkinci istek yeni sipariş açmıyor | Kritik |
| Çıkış IP izni | Sunucu çıkış IP'si ile panel listesi | Birebir eşleşiyor | Yüksek |
| Jeton yenileme | Jeton ömrünü bekleyip sipariş ver | Otomatik yenileniyor | Yüksek |
| Eşzamanlılık sınırı | Tedarikçi ayarlarını incele | Limitin altında tanımlı | Orta |
| Devre kesici | Hatalı anahtarla test et | Belirli hatadan sonra duruyor | Orta |
| Satın alma anı stok kontrolü | Tükenmiş ürünle dene | Ödeme öncesi uyarı çıkıyor | Yüksek |
| Yedek tedarikçi geçişi | Birincili kapatıp sipariş ver | İkinciden karşılanıyor | Orta |
| Günlük mutabakat | Kayıtları tedarikçi hareketleriyle karşılaştır | Fark yok veya işaretli | Yüksek |
Entegrasyonu tahminle değil veriyle yönet
Tekil referans, devre kesici, çok tedarikçili yedekleme ve ham yanıt kaydıyla "para gitti kod gelmedi" vakalarını kökünden kaldır.
Dün çalışan entegrasyon bugün 403 veriyorsa ne değişmiştir?
Genelde kod değil, sunucunun dışarıya çıkarken kullandığı IP adresi. Tedarikçiler bayi anahtarını IP ile eşler; sunucu taşıma veya bulut katmanı değişikliği entegrasyonu sessizce kırar.
Zaman aşımı aldığımda isteği tekrar göndermeli miyim?
Hayır. Sonuç bilinmiyordur ve kör tekrar deneme çift satın alma üretir. Tekil referansla durum sorgusu yapıp gerçek sonucu öğrendikten sonra karar vermelisin.
429 hatası tedarikçinin arızası mıdır?
Değil, hız limiti uyarısıdır. Eşzamanlılık sınırı tanımlayıp artan gecikmeli tekrar deneme kurduğunda bu hata büyük ölçüde ortadan kalkar.
Kaç tedarikçi bağlamak yeterli olur?
Çok satan ürünlerde en az iki. Devre kesici ve otomatik yedekleme kuruluysa birincil tedarikçinin bakım penceresi satışını durdurmaz, siparişler ikinciden karşılanır.
Entegrasyon olgunluğu, hata olmamasıyla değil hatanın nasıl karşılandığıyla ölçülür: her yanıtın kaydı tutulur, her istek tekil referans taşır, her tedarikçinin bir yedeği ve bir devre kesicisi olur. Bu dördü kurulduğunda tedarikçi kesintisi bir kriz değil, panelde birkaç dakika bekleyen bir kuyruk satırıdır. Bu akışın gerçek bir sistemde nasıl göründüğünü merak ediyorsan canlı demo üzerinde tedarikçi ekranlarını açıp hata kayıtlarını ve yedekleme kurallarını kendi gözünle inceleyebilirsin.