API entegrasyon hatası nasıl önlenir? n8n ile contract testi

API entegrasyon hatası nasıl önlenir sorusuna n8n, 1 Ekim 2026 tarihli yazısında bir yöntemle yanıt verdi. n8n Blog (yeni sekmede açılır)'a göre bir dış API bir gün sorunsuz çalışıp ertesi gün bozulabilir; çünkü sağlayıcı bir yanıtı haber vermeden değiştirmiş olabilir. n8n'in önerdiği çözüm, API sözleşmesini (contract) test etmek ve bu kontrolü canlıdaki iş akışlarının içine yerleştirmektir. Ürün senkronu, ödeme ve stok güncellemesi gibi akışlara dayanan bir mağaza için bu konu doğrudan sipariş kaybıyla ilgilidir.

API contract testing nedir?

n8n Blog'un tanımına göre API contract testing, sağlayıcı ile onu kullanan sistem arasındaki arayüzün kararlaştırılan sözleşmeye hâlâ uyup uymadığını doğrular. Sözleşme; istek ve yanıtın yapısını, zorunlu alanları, veri türlerini ve durum kodlarını kapsar.

Bunu iki taraflı bir sipariş formuna benzetebilirsiniz. Tedarikçi her seferinde aynı alanları aynı sırayla doldurmayı söylemiştir. Formun biçimi değişirse siz farkı ilk teslimatta değil, formu okurken görmek istersiniz.

Kaynak iki yöntem sayıyor. Birincisi tüketici odaklı test: kullanan tarafın beklentilerinden yola çıkar ve sağlayıcının bunları hâlâ karşılayıp karşılamadığına bakar. İkincisi şema tabanlı doğrulama: istek ve yanıtları OpenAPI belgesi ya da JSON Schema gibi ortak bir şartnameyle karşılaştırır.

API yanıt verdiği hâlde entegrasyon neden bozulur?

Çünkü bağlantının çalışması, verinin doğru olması demek değildir. n8n Blog bir ödeme API'sini örnek veriyor: tutar alanı bir gün sayı yerine metin olarak dönmeye başlıyor. İstek başarılı görünür, ama sayı bekleyen bir iş akışı toplamı yanlış hesaplayabilir ya da işlemeyi tümden durdurabilir.

Kaynak, geçerli bir HTTP yanıtı döndüren ama iş mantığını bozan üç değişiklik türü sayıyor:

• Daha önce tek nesne olan veri, bir dizinin içine alınır.
• Sabit değer listesindeki (enum) seçenekler değişir ve akış yanlış dala gider.
• Tam ad tek alandayken iki ayrı alana bölünür ve eşleştirme zorlaşır.

n8n Blog'a göre test paketi yalnızca belirli bir andaki durumu gösterir. Sağlayıcı bir alanı yeniden adlandırabilir ya da isteğe bağlı bir değeri zorunlu yapabilir; bunu testlerin geçtiği günden haftalar sonra da yapabilir.

Kurgusal bir örnek: stok API'si miktarı önceden sayı olarak veriyor, sonra metin olarak vermeye başlıyor. Mağazanızdaki stok güncelleme akışı hata vermeden çalışmaya devam eder ama yanlış değer yazar. Fark, bir müşteri tükenmiş ürünü sipariş edince ortaya çıkar.

Mağaza sahibi olarak API entegrasyon hatası nasıl önlenir?

Kaynağa göre sözleşme testi genellikle CI/CD hattında, yani iş akışlarını canlıya almadan önceki otomatik kontrol adımında çalışır. Bu önemli bir güvencedir ama haftalar sonra gelen sağlayıcı değişikliğini yakalamaz. Bu yüzden n8n Blog, doğrulamayı canlı iş akışının içine koymayı öneriyor. n8n, kaynak kodu erişilebilir (source-available) bir yapay zekâ iş akışı otomasyon platformudur; her API çağrısında sözleşmeyi kontrol edebilirsiniz. Kaynak bir noktayı da açıkça belirtiyor: bu kontrol otomatik gelmez ve yerleşik düğümlerle çalışmaz, siz kurarsınız.

Tipik akış dört adımdan oluşur:

1. API'yi çağırın: HTTP Request düğümüyle sağlayıcıdan veriyi alın.
2. Yanıtı doğrulayın: Code düğümünde yazacağınız özel JavaScript ya da Python koduyla yanıtı beklenen şemayla karşılaştırın; iş akışı bundan sonra devam etsin.
3. İhlalleri ayırın: If düğümüyle geçerli yanıtları sözleşme ihlallerinden ayırın.
4. Doğru kişiye haber verin: Başarısız doğrulamaları Slack'e, e-postaya ya da talep sistemine yönlendirin; bozuk veriyle devam etmeyin.

Her doğrulama çalışması n8n'in yürütme geçmişine kaydedilir. Bu sayede hata sonrasında günlük karıştırmak yerine sağlayıcının tam olarak ne döndürdüğüne ve sözleşmenin ne zaman değiştiğine bakabilirsiniz. Ödeme gibi hassas akışlarda, sonraki işlemler başlamadan önce bir insan onayı da ekleyebilirsiniz.

Bir e-ticaret operasyon otomasyonu kuruyorsanız bu kontrolü, akışın ilk tasarımında en kritik API çağrılarının hemen arkasına koymak, sonradan eklemekten daha kolaydır.

Sözleşme testi, entegrasyon testi ve şema doğrulaması nasıl ayrılır?

n8n Blog'un anlatımına göre bu üç terim birbirine benzer ama farklı sorulara yanıt verir.

Hangi entegrasyonları önce korumalısınız?

Kaynak bir öncelik sıralaması vermiyor; aşağıdaki sıralama bizim yorumumuzdur. Bir akış bozulduğunda parayı, stoğu ya da müşteri bilgisini ne kadar çabuk etkiliyorsa o akışı öne alın.

Kaynak da bu ayrımı yapıyor: bazı API'ler her istekte doğrulanmalı, bazıları ise sürümler arasındaki şema kaymasını arayan zamanlanmış sağlık kontrollerine daha uygundur.

Canlıya almadan önce hangi kontrol listesini uygulamalısınız?

n8n Blog, iyi yazılmış testlerin bile çevresindeki sürece bağlı olduğunu söylüyor ve şu maddeleri sıralıyor:

• Tüm sözleşmeyi doğrulayın: Yalnızca bugün kullandığınız alanlara bakmayın; isteğe bağlı ya da kullanılmayan alanlardaki değişiklik de bozucu olabilir.
• Yanıtı kullanıldığı yerde kontrol edin: Doğrulamayı HTTP isteğine mümkün olduğunca yakın yapın ki sonraki adımlar bozuk veri işlemesin.
• Sözleşme sürümlerini bilinçli yönetin: Beklenen değişiklikle beklenmeyeni ayırt edebilmek için sürümleri izleyin.
• İhlalde hemen uyarın: Sorunun sonraki bir akışta ortaya çıkmasını beklemeyin.
• Yürütme geçmişini kanıt sayın: Neyin, ne zaman değiştiğini ve hangi akışların etkilendiğini hızlıca bulabilmek için her doğrulamayı saklayın.
• Üretimde nasıl izleyeceğinize karar verin: Hangi API'nin her istekte, hangisinin zamanlanmış kontrolle izleneceğini baştan belirleyin.

Bu listeyi kendi mağazanıza uyarlarken ilk adım, hangi API'lerin para ve stok akışına dokunduğunu yazıp çıkarmak olabilir. Böylece doğrulamayı nereye koyacağınız netleşir.

Hangi akışlarınızın bu tür bir kontrole ihtiyaç duyduğunu görmek ve kurulumun adımlarını öğrenmek için ücretsiz sistem analizi formunu doldurabilirsiniz.

Sık sorulan sorular