Tek Tedarikçiye Bağlı Epin Script Mimarisi Bir Gün Seni Kapatır: Adaptör Katmanı, Devre Kesici ve Kimsenin Anlatmadığı Sözleşme Testi

Çoğu kişi «tedarikçi entegrasyonu» deyince tek bir dosya düşünür: içinde anahtarın, adresin ve birkaç isteğin bulunduğu bir bağlantı kodu. İlk tedarikçide bu yaklaşım işe yarar, ikincisinde kopyalanır, üçüncüsünde kimse hangi dosyanın canlı olduğunu bilemez. Altı ay sonra elinde yazılım değil, birbirine benzeyen ama birbirinden habersiz üç ayrı kurgu olur.

Asıl mesele bağlantı değil mimari: tedarikçilerin farklılıklarını tek bir yerde soğurup, geri kalan her şeyi bu farklardan habersiz bırakma sanatı. Bu yazıda bir dijital ürün satış scriptinin tedarikçi tarafını katman katman kuruyoruz. Adaptör sınırı nereden geçer, yönlendirme kararını hangi veri verir, kuyruk ve devre kesici neyi kurtarır, sözleşme testi neden lüks değil zorunluluktur.

Neden «API bağladım» bir mimari değildir?

Bağlantı, tek bir tedarikçiyle tek bir senaryoyu çalıştırmaktır. Mimari ise şu soruların hepsine tek yerden cevap verebilmektir: yeni bir tedarikçi eklemek kaç saat sürer, bir tedarikçi düşerse satış devam eder mi, iki tedarikçinin aynı ürünü varsa hangisini seçeriz, tedarikçi alan adını değiştirirse kaç dosyaya dokunmak gerekir.

Bu sorulara «bakmak lazım» diye cevap veriyorsan mimari yok demektir. Mimarinin tanımı, cevapların önceden belli olmasıdır. İyi kurulmuş bir e-pin scripti yeni tedarikçiyi tek bir sınıf ve tek bir yapılandırma kaydıyla kabul eder; sipariş akışına, ürün eşleştirmeye veya raporlamaya dokunmak gerekmez.

Pratik sınama şu: yeni tedarikçi eklerken sipariş dosyasını açman gerekiyorsa sınır yanlış çizilmiş. Sipariş akışı, tedarikçinin adını bile bilmemeli.

Adaptör katmanı: her tedarikçiyi aynı dile çeviren tek yer

Adaptör, dışarıdaki kaosu içeride tek bir sözlüğe çeviren tercümandır. Tedarikçi A ürün kimliğini metin, B sayı olarak bekler; A hata kodunu gövdede, B başlıkta döner; A stoku adet, B seviye olarak bildirir. Bu farklar var olmaya devam edecek; senin kararın bunların nerede yaşayacağı.

Doğru tasarımda her tedarikçi için dört yetenek tanımlarsın: ürün listesi çekme, stok sorgulama, satın alma, sipariş teyidi. Bu dördü tüm tedarikçilerde aynı imzaya, aynı dönüş yapısına ve aynı hata sınıflarına sahip olur. İçeride ne çeviriyorsa çevirsin; dışarıya tek tip konuşur.

Hata sınıflandırması burada kritik. «Hata oldu» yeterli değil; hatanın tekrar denenebilir mi, kalıcı mı, yoksa sonucu bilinmiyor mu olduğunu adaptör söylemeli. Yürütme katmanının tüm davranışı bu üç ayrımdan türer.

Çoklu tedarikçi yönlendirmesi: fiyat mı, başarı oranı mı?

Yeni başlayanlar yönlendirmeyi fiyat tablosu sanır: en ucuz kaynaktan al, kârı büyüt. Bu strateji, kâr marjı ile iade maliyetini aynı hesaba koymadığı için genelde zarar üretir. Yüzde iki daha ucuz ama yüzde beş daha çok hata veren bir kaynak, seni her ay destek masasında karşılar.

Sağlıklı yönlendirme puanlama yapar. Üç değişken yeter: birim maliyet, son yirmi dört saatteki başarı oranı ve medyan yanıt süresi. Bu üçünü ağırlıklandırıp kaynakları sıralarsın; birinci düşerse ikinciye geçersin. Ağırlıkları ürün grubuna göre değiştirebilmen de büyük avantaj: hızlı tüketilen popüler ürünlerde hız, nadir ürünlerde maliyet öne çıkar.

Bir de öğrenen kısım var: yönlendirme puanı canlı verilerle güncellenmezse, tedarikçi bozulduğunda sen fark etmeden siparişleri ona göndermeye devam edersin. Puanı besleyen metrik boruları, mimarinin en çok ihmal edilen parçasıdır.

Kuyruk, tekrar deneme ve devre kesici birlikte ne yapar?

Kuyruk yükü zamana yayar, tekrar deneme geçici hataları yutar, devre kesici kalıcı hatada kaynağı devre dışı bırakır. Üçü birlikte çalışırsa kesinti bir felaket değil, kısa bir yavaşlama olur. Biri eksikse diğer ikisi zarar verebilir: devre kesicisi olmayan bir tekrar deneme mekanizması, bozuk tedarikçiye saniyede yüz istek gönderip anahtarını da yakar.

Devre kesiciyi kurarken iki sayıya karar vermen yeterli: kaç hatadan sonra kapansın ve kaç dakika kapalı kalsın. Beş dakikalık soğuma, çoğu geçici kesinti için yeterli bir başlangıçtır. Kapanma anında yönlendirme puanı otomatik düşer, siparişler ikinci kaynağa akar ve müşteri hiçbir şey fark etmez. Fark eden tek kişi, panelde uyarıyı gören sensin.

Sözleşme testleri ve sahte tedarikçi neden zorunlu?

Tedarikçiler sana haber vermeden değişir: bir alan adı adı değişir, hata biçimi farklılaşır, limit düşer. Bu değişiklikleri ilk öğrenen, canlı siparişler olmamalı. Sözleşme testi tam bunu engeller: adaptörün beklediği yapıyı sabitler, tedarikçi yanıtı bozulduğunda test kırmızıya döner.

İkinci araç sahte tedarikçidir. Yerel ortamda çalışan, istediğinde gecikme üreten, istediğinde bozuk yanıt döndüren küçük bir taklit uç. Böylece zaman aşımı davranışını, çift istek korumasını ve devre kesiciyi gerçek para harcamadan denersin. Bir e-pin satış yazılımını değerlendirirken «test tedarikçisi var mı» sorusu, özellik listesindeki çoğu maddeden daha bilgilendiricidir.

Bu iki araç bir arada geliştirme hızını da artırır. Yeni tedarikçi eklemek artık cesaret işi değil, tanımlı bir kontrol listesinin uygulanmasıdır.

Gözlemlenebilirlik: mimarinin sağlığını tek ekranda görmek

Mimari ne kadar zarif olursa olsun, göremediğin şeyi yönetemezsin. Tedarikçi bazlı tek bir ekran istiyorsun: istek sayısı, başarı oranı, medyan ve p95 süre, devre kesici durumu, son hata mesajı ve günlük maliyet. Bu altı sütun, haftalık tedarikçi kararlarının tamamını almanı sağlar.

Uyarıları da eşikli kur. Başarı oranı eşiğin altına indiğinde, devre kesici kapandığında veya anahtar süresi dolmaya yakınken haber alman gerekir. Uyarı gelmeyen sistemde herkes kahraman olmak zorunda kalır; uyarı gelen sistemde kimse kahraman olmaz, işler yürür. Yazılım seçerken bu ekranın hazır gelip gelmediğini sormak, sonradan yaptırmaktan çok daha ucuz.

Tedarikçi entegrasyonu, e-pin işinin görünmeyen ama en belirleyici altyapısıdır: doğru kurulduğunda yeni kaynak eklemek rutin bir işe, yanlış kurulduğunda her kesinti krize dönüşür. Bu katmanların hazır bir panelde nasıl göründüğünü görmek istiyorsan canlı demo üzerinden tedarikçi ekranlarını gezebilir, özellik listesiyle kendi kurgunu satır satır karşılaştırabilirsin.