API sözleşme testleri: yükseltmeden önce şema değişikliklerini doğrulamak

Bir entegrasyon HTTP 200 alırken siparişe yanlış durum yazabilir. Erişilebilirlik, hizmetin isteği işlediğini gösterir; yanıtın uygulamanıza uygun olması ayrı bir kontrol gerektirir. API yükseltmesinden önce yeni SDK sürümünden fazlasını konuşun. Veri sözleşmesini tanımlayın: uygulama ne gönderiyor, ne alıyor ve sonraki işlemi yapmak için neyi izin sayıyor?

Bir Stripe güncellemesi ve n8n makalesi bu sorunun farklı iki yönünü gösteriyor. İlki duyurulmuş bir parametre değişikliğini, ikincisi çalışan iş akışında yanıt doğrulamayı ele alıyor. Birlikte, sorun bir iş kaydını değiştirmeden önce onu yakalayan bir yükseltme sürecine işaret ediyorlar.

Alan adı uyumluluğu garanti etmez

Stripe'ın 2026-09-30.endive değişiklik günlüğü, listelenen Payment Intent ve Setup Intent işlemlerinde payment_method_types parametresinin yazılabilir olmaktan çıkarılmasını anlatıyor. Etkilenen sürümde gönderilmesi, payment_method_types_no_longer_supported koduyla HTTP 400 döndürüyor. Aynı adlı özellik nesnelerde okunabilir kalıyor.

Bu ayrım önemlidir: bir alan yanıtta bulunabilir ama istekte kabul edilmeyebilir. Stripe dinamik ödeme yöntemlerini, excluded_payment_method_types ile dışlamaları ve allowed_payment_method_types ile izin listesini anlatıyor. Son seçenekte uyumsuz türler elenir. Bu nedenle geçiş hem istek geçerliliğini hem müşteriye gerçekten gösterilen ödeme seçeneklerini kontrol etmelidir.

Bu, belirli bir API sürümüne özgü değişikliktir; mevcut her Stripe entegrasyonunun bozulduğuna kanıt değildir. İstek, SDK ve webhook uç noktası sürümlerini ayrı kontrol edin. Kaydedilen yayın bir önizleme sürümünden de söz ediyor; geçiş kararı vermeden hemen önce seçtiğiniz hedef sürümün belgelerini doğrulayın.

Tüketicinin sözleşmesini tanımlayın

Tek senaryoyla başlayın: uygulama ödeme oluşturur, yanıtı okur ve kullanılabilir sonraki işlemleri sunar. Gerekli alanları, türleri ve anlamlarını kaydedin. Ardından belge örneklerinde sık eksik kalan durumları ekleyin: bulunmayan değer, açık null, boş liste ve bilinmeyen durum.

Bunları tek bir “yok” durumunda birleştirmeyin. Bulunmayan alan eski yanıt sürümüne işaret edebilir. null, açıkça bilinmeyen bir değeri temsil edebilir. Boş liste seçenek olmadığını gösterebilir. Doğru yorum API'ye bağlıdır. Uygulama sözleşmeniz her durumda ne olacağını belirtmelidir.

Pratik bir çalışma tablosunda alan adı, yön, kabul edilen değerler, iş bağımlılığı ve ihlal davranışı bulunur. Örneğin: “Tutar mutabakat için zorunludur; geçersiz tür otomatik onayı durdurur.” Bu, API entegrasyonu planlamasında anlatıldığı gibi teknik şemayı operasyonel sürece bağlar.

Bilinmeyen enum değerini sessizce en yakın bilinen durum saymak yerine açık bir işleme yönlendirin. Yeni “inceleme bekliyor” durumu varsayılan dal yüzünden “ödendi” olmamalıdır. Öte yandan kullanılmayan ek alanlar iş akışını durdurmayı her zaman gerektirmez. Her eklemeyi reddetmek de önlenebilir arızalar yaratabilir.

Yükseltme öncesi doğrulamanın üç düzeyi

n8n, sözleşme testi, entegrasyon testi ve şema doğrulamasını ayırıyor. Bunlar ilişkili soruları yanıtlar, birbirlerinin yerini almaz. Şema mesajın yapısını kontrol eder. Sözleşme tüketicinin beklentilerini kaydeder. Uçtan uca senaryo, etkileşen sistemlerin istenen sonucu üretip üretmediğini kontrol eder.

Yararlı bir yükseltme kontrol seti şunları içerir:

• Giden istek kontrolleri: kaldırılan parametreler artık gönderilmez, zorunlu değerler doğrudur.

• Gelen yanıt kontrolleri: türler, kabul edilen durumlar ve null kabul eden alanlar açıkça işlenir.

• Müşteri sonucu kontrolleri: ödeme seçeneği kullanılabilir, hatalar açıklanır ve sipariş erken onaylanmaz.

Kaydedilmiş anonim örnekler eski ve yeni davranışı karşılaştırmaya yardımcı olur. Eski yanıtı yeniden oynatmak, yeni API'nin onu üreteceğini kanıtlamaz. Önemli senaryolar uygun test ortamında seçilen sürüme karşı kontrol edilmelidir. Kabul koşullarını çalıştırmadan önce yazın; yoksa ekip her farkı kabul edilebilir yükseltme diye gerekçelendirebilir.

Geçersiz veriyi süreci değiştirmeden durdurun

n8n makalesi, HTTP Request düğümünden sonra yanıtların doğrulanmasını ve ihlallerin ayrı yönlendirilmesini öneriyor. Ayrıca bunun yapılandırma gerektirdiğini ve yerleşik düğümlerde otomatik olmadığını belirtiyor. Otomasyon platformu kullanmak tek başına sözleşmeyi uygulatmaz.

Doğrulama sınırını önemli veya geri alınamaz işlemden önce koyun. Tutarın türü geçersizse sırf akışı sürdürmek için sıfır tutarlı mali kayıt oluşturmayın. İşlem referansını, ret nedenini, sözleşme sürümünü ve inceleme sorumlusunu saklayın. Teknik günlükler teşhis için gerekli bilgiyi içermelidir; özel ihtiyaç olmadan tüm ödeme yükünü kopyalamayın.

Bir API'yi birkaç uygulama paylaşıyorsa her tüketicinin beklentilerini kontrol edin. Özel API mimarisi açıklaması, ortak kaynakları, belgeleri ve farklı istemcileri kapsar. Sözleşmeleri tartışmak için bağlam sunar, ancak projede bu yeni Stripe veya n8n sürümlerinin kullanıldığını göstermez.

İş kurallarını sessizce değiştirmeden yükseltmeyi kabul edin

Bir yükseltme sorumlusu atayın ve bağımlı süreçleri listeleyin. Mevcut ve hedef sürümleri, beklenen farkları, test senaryolarını ve geri dönüş koşullarını kaydedin. Uygulamanın geri alınmasını, değişmiş veriler ve sağlayıcı ayarlarıyla birlikte değerlendirin. Kodu geri almak işlemin önceki anlamını mutlaka geri getirmez.

Yayından sonra hem şema ihlallerini hem iş sonucu tutarsızlıklarını izleyin. Belgeleri, CRM'yi ve görevleri bağlamak, her değerin kime ait olduğunda anlaşmayı gerektirir. API sürümleme bir soru daha ekler: bu kayıt hangi kurallarla alındı?

Doğrulama da istek tüketir. Toplu geçişte ortak API istek bütçesini hesaba katın; kontroller ve idari okumalar canlı işlemleri dışarı itmesin. Ödeme entegrasyonunda sonraki adım ödeme denemeleriyle kayıtları mutabık hale getirmektir. Yapısal olarak doğru yanıt, doğru mali anlamı da taşımalıdır.

Kaynaklar

• n8n: API sözleşme testleri.

• Stripe: payment_method_types değişikliği.