Muhasebe API'si İçin Üretim Öncesi Test Planı

Bir muhasebe API'sinden dönen 201 Created yanıtı size neredeyse hiçbir şey söylemez. Yalnızca sunucunun yanıt verdiğini doğrular; ortada tam olarak tek bir fatura olduğunu, borç ve alacakların eşit olduğunu, belge numarasının bir kez tahsis edildiğini veya kopan bir bağlantı sonrası yapılacak yeniden denemenin ikinci bir kopya oluşturmayacağını garanti etmez. Üretim ortamındaki muhasebe mükerrerliklerinin çoğu bu boşluktan kaynaklanır: Sunucuda başarıyla işlenen (commit) ancak istemcinin sonucu bilmeden sessizce yeni bir anahtarla yeniden denediği bir mutasyon.

Bu plan, bir muhasebe API'sini gerçek defterlere entegre etmeden önce değerlendiren ekipler için hazırlanmıştır. Mutlu son senaryoları (happy path) değil, hata davranışlarını ele alır. Aşağıdaki her bölümde neyin test edileceği, neyin doğrulanacağı (assert) ve neyin başarılı sayılacağı belirtilmiştir. Buradaki uygulama bağlamı, API'sinde kapsamlı (scoped) bearer anahtarları, ondalık dize (decimal-string) tutarları, idempotency anahtarları ve imzalı webhook'lar kullanan Nordlet'tir. Tam uç nokta (endpoint) sözdizimi ve yanıt kontratları için varsayımlara güvenmek yerine API kuralları ve Başlangıç sayfalarını okuyun.

"Başarılı" Olmak Aslında Ne Anlama Gelir

Bir test, yalnızca durum kodlarını değil, anlambilimi (semantics) doğruladığı zaman muhasebe entegrasyonunun güvenli olduğunu kanıtlar. Her senaryo için test paketi şunları doğrulamalıdır:

• İş tarafı etkisi (Business side effect): Tam olarak bir müşteri, fatura, yevmiye kaydı, numara tahsisi veya ödeme geçişi mevcuttur.
• Muhasebe bütünlüğü: Borçlar alacaklara eşittir ve serileştirme sırasında parasal hassasiyet kaybolmaz.
• Yeniden oynatma (replay) davranışı: Bir yeniden deneme, yeni bir kayıt oluşturmak yerine orijinal sonucu döndürür.
• Dayanıklılık (Durability): İşlem onaylandığında denetim (audit) kayıtları ve webhook olayları mevcuttur.
• Yan etkisiz hatalar: Reddedilen istekler hiçbir belge numarası tüketmez ve eksik defter satırı yazmaz.
• Kurtarma (Recovery): Geçici bir hata, mükerrerliğe veya kalıcı veri kaybına yol açmadan yeniden denenebilir.

Google'ın API rehberliği bu çizgiyi net bir şekilde çizer: Yalnızca yinelenen yürütülmesi aynı nihai durumu bırakan işlemlerin yeniden denenmesi güvenlidir ve bir API, her hatayı körü körüne yeniden denemek yerine hangi işlemlerin idempotent olduğunu belirtmelidir.

İzlenebilir ve Atılabilir Bir Ortam Kurun

Üretim defterlerini değil, bir korumalı alan (sandbox) şirketi kullanın. Nordlet korumalı alan şirketi, gerçek bir şirketle aynı modülleri ve API davranışını kullanır ve test verisi olarak etiketlenir; bu da onu yüksek hacimli mükerrerlik ve hata testleri için güvenli kılar. Bu bayrak oluşturulduktan sonra değiştirilemez, böylece gerçek defterler daha sonra test verisi olarak yeniden sınıflandırılamaz. Korumalı alan kullanımının gerçek bir şirketteki kullanım gibi ölçümlendirildiğini ve faturalandırıldığını unutmayın, bu nedenle hacim testlerinizi dahil olduğunuz fiyatlandırmaya göre boyutlandırın.

Herhangi bir test yazmadan önce aşağıdakileri hazırlayın:

• isSandbox: true değerine sahip özel bir korumalı alan şirketi.
• Yalnızca test edilen modülleri kapsayan bir test API anahtarı.
• Ham istek gövdesini (body) koruyan bir webhook uç noktası veya yerel tünel.
• Veri olarak eklenmiş (seeded) müşteriler, tedarikçiler ve bilinen bir hesap planı.
• En az iki muhasebe dönemi:biri açık, biri kilitli.
• Uygulama destekliyorsa bir test saati veya tarih sabiti (fixture).
• Her istek denemesini, idempotency anahtarını, yanıt karmasını (hash), webhook teslimini ve mutabakat sonucunu kaydeden yerel bir depo.

Paylaşılan hazırlık (staging) verileri üzerinde mükerrerlik testleri çalıştırmayın. Önceki bir çalışmadan kalan kaçak bir müşteri veya fatura, sonraki doğrulamaları belirsiz hale getirir.

Her mutasyon için hazırlayacağınız veri sabiti; yöntemi (method), uç noktayı, tam gövdeyi, idempotency anahtarını, anahtar kapsamını, istemci korelasyon kimliğini, başlangıç ve bitiş zaman damgalarını, yanıt durumunu, başlıkları (headers), gövdeyi, istek kimliğini ve yanıt gelmeden önce bağlantının kopup kopmadığını kaydetmelidir. Para birimleri için "75.0000" gibi sabit ondalık dizeler kullanın. Nordlet, parasal değerleri dört basamağa kadar ondalık dizeler olarak temsil eder ve örnek faturası bu biçimi kullanır.

Kurulumun diğer kısmı hata enjeksiyonudur. Test düzeniniz (harness); bir yanıtı geciktirebilmeli, sunucu isteği aldıktan sonra TCP bağlantısını kesebilmeli, yapay 429/500/502/503/504 yanıtları döndürebilmeli, webhook alıcısından 2xx dışı bir yanıt döndürebilmeli, aynı webhook'u iki kez teslim edebilmeli, olayların sırasını değiştirebilmeli, bir webhook gövdesinin tek bir baytını bozabilmeli, anahtarı aynı tutarken idempotency anahtarı yükünü (payload) değiştirebilmeli, eşzamanlı olarak iki özdeş istek çalıştırabilmeli ve kurulum ile deftere kaydetme arasında bir dönemi kilitleyebilmelidir. Bu senaryolar, yüzlerce mutlu son örneğinden daha değerlidir.

Yeniden Deneme Mantığı Yazmadan Önce Kontratı Kilitleyin

OpenAPI şemasını oluşturun veya çekin ve bunu istemcinizle karşılaştırın. Nordlet, OpenAPI şartnamesini API referansında yayınlar ve yazılmış (typed) SDK'larını aynı şartnameden üretir, bu nedenle şema odaklı testler el yazısı varsayımlardan daha üstündür.

Zorunlu alanları ve türleri, ondalık dize alanlarını, tarih ve zaman damgası biçimlerini, izin verilen eylemleri ve kapsamları (scopes), hata zarfı (error envelope) şeklini, webhook olay şemalarını, hangi mutasyonların idempotency anahtarı kabul ettiğini ve hangi yanıt alanlarının oluşturulan nesneyi tanımladığını doğrulayın.

Başarı ölçütleri. İstemci, şemanın izin verdiği geçersiz yükleri yerelde reddeder. Sunucunun yanıtları belgelenen şemayla eşleşir. Geçersiz ondalık sayılar, hatalı tarihler ve eksik zorunlu alanlar yapılandırılmış doğrulama hataları üretir. Deterministik bir doğrulama hatası için hiçbir yeniden deneme denenmez.

Yakalanacak hata modu. İstemci "121.0000" değerini ikili kayan noktalı sayıya (binary float) ayrıştırır ve daha sonra biraz farklı bir tutarı serileştirir. Tam sayılar geçer; KDV satırları ve kesirli miktarlar başarısız olur. Para birimini uçtan uca dizeler olarak test edin.

Yetkilendirme ve Kiracı İzolasyonu (Tenant Isolation)

Okuma ve yazma için ayrı anahtarlar kullanın. Ardından tüm matrisi test edin: eksik anahtar, geçersiz anahtar, yetersiz modül kapsamına sahip geçerli anahtar, doğru kapsamlı geçerli anahtar, başka bir şirkete ait bir anahtar ve farklı bir şirketten bir nesneyi okuma girişimi.

Doğrulamalar:

• Eksik veya geçersiz kimlik bilgileri 401 döndürür.
• Gerekli izne sahip olmayan geçerli bir anahtar 403 döndürür.
• Her iki hata için de hiçbir muhasebe yan etkisi oluşturulmaz.
• Başarılı bir istek, başka bir şirketin kayıtlarını okuyamaz veya değiştiremez.
• Güvenlik hataları hiçbir zaman otomatik olarak yeniden denenmez.

Başarı ölçütü. Yalnızca durum kodlarıyla değil, test sonrası okumalarla hem yetkilendirme doğruluğunu hem de kiracı izolasyonunu kanıtlayabilirsiniz.

Temiz Bir İşlemi Kanıtlayın

Küçük, deterministik bir akış çalıştırın: bir test müşterisi oluşturun veya bulun, ondalık dize tutarlarıyla bir fatura oluşturun, faturayı kesin, faturayı ve muhasebe etkisini okuyun, denetim kaydını okuyun ve webhook'u alın. Nordlet'in Başlangıç örneği, fatura kesiminin boşluksuz bir numara tahsis ettiğini, dönemin açık olduğunu kontrol ettiğini ve aynı işlemde dengeli bir yevmiye kaydı girdiğini gösterir.

Faturanın beklenen duruma ulaştığını, belge numarasının tam olarak bir kez tahsis edildiğini, borçların alacaklara eşit olduğunu, KDV ve satır toplamlarının beklenen yarı yukarı yuvarlama (half-up calculation) ile eşleştiğini, denetim kaydının aktörü ve değişikliği adlandırdığını, webhook'un nihayetinde teslim edildiğini ve API yanıtı ile takip eden okumanın fatura kimliği ve durumu konusunda hemfikir olduğunu doğrulayın.

Üzerinde durulmaya değer bir ayrım şudur: Bir webhook'un gelmesi, mutasyonun işlendiğinin kanıtı değildir. API yanıtı ve ardından yapılan bir okuma, birincil işlem doğrulamalarınızdır. Webhook ise aşağı akış (downstream) bildirimini kanıtlar ve ayrı olarak test edilir.

Idempotency: Aynı Anahtar, Aynı Gövde

Ağ denemesi başına bir anahtar değil, mantıksal iş işlemi başına bir anahtar oluşturun. Mutasyonu K anahtarı ve B gövdesiyle gönderin, oluşturulan kimliği kaydedin, ardından aynı isteği tekrar tam olarak gönderin.

İkinci yanıtın aynı işlemi temsil ettiğini, nesne kimliğinin aynı olduğunu ve bir iş nesnesi, bir deftere kayıt (posting), bir belge numarası ve bir finansal etki bulunduğunu doğrulayın. Yeniden oynatılan yanıt, belgelenmiş yeniden oynatma başlığını taşımalıdır (Nordlet durumunda x-idempotent-replay: true) ve denetim izi ikinci bir mutasyon göstermemelidir.

İki depolama kuralı, yeniden deneme döngünüzün ne beklemesi gerektiğini değiştirir, bu nedenle bunları doğrudan test edin: saklanan bir 4xx diğer herhangi bir yanıt gibi yeniden oynatılır, buna karşılık bir 5xx hiç saklanmaz, bu nedenle bir sunucu hatasından sonraki yeniden deneme yeniden oynatmak yerine işlemi yeniden yürütür. Anahtarlar ayrıca Nordlet'te 24 saat sonra süresi dolacak şekilde zaman aşımına uğrar, bu da bir yeniden oynatmanın ne kadar süreyle kullanılabilir olacağını sınırlandırır.

Nordlet belgeleri, bir Idempotency-Key başlığı eklemenin yeniden denenen bir isteğin mükerrer kayıt oluşturmasını engellediğini vadeder ve API kuralları tam yeniden oynatma başlığını ve bayt bayt yanıt gereksinimini tanımlar. Bu ilke, Stripe'ın yayınlanan modeliyle eşleşir: Bir anahtar mantıksal işlemi tanımlar, tekrarlar saklanan sonucu döndürür ve farklı parametrelerle yeniden kullanılan bir anahtar sessizce değiştirilmek yerine reddedilir.

Başarı ölçütü. İstemci aynı isteği yeniden oynatma penceresi içinde kaç kez gönderirse göndersin, tam olarak bir finansal durum geçişi bulunur.

Idempotency: Aynı Anahtar, Değiştirilmiş Gövde

Orijinal isteği K anahtarı ve B1 gövdesiyle, ardından en az bir tutarın, müşterinin, tarihin veya satırın farklı olduğu K anahtarı ve B2 gövdesiyle ikinci bir istek gönderin.

Beklenen sonuç: İstek belgelenmiş anahtar yeniden kullanım hatasıyla reddedilir (Nordlet 422 idempotency_key_reuse döndürür), orijinal kayıt değiştirilmez, ikinci bir kayıt, numara veya denetim mutasyonu görünmez ve istemci yeni bir anahtar üreterek bunu "düzeltmez". B2'yi sessizce kabul etmek, yeniden deneme anahtarlarını güvensiz hale getirirdi.

Eşzamanlı Mükerrer İstekler (Concurrent Duplicate Requests)

Aynı anahtara sahip iki özdeş isteği aynı anda tetikleyin. Belgelenen davranışa bağlı olarak, biri yürütülürken diğeri devam eden bir çakışma alır (Nordlet 409 idempotency_in_progress döndürür) veya her ikisi de nihayetinde aynı sonucu gözlemler.

Her iki çağrının da bağımsız finansal etki yaratamayacağını, en fazla bir belge numarasının tahsis edileceğini, geçici bir çakışmanın yeni bir anahtar yerine aynı anahtarla yeniden deneneceğini, nihai kaynağın eksiksiz ve okunabilir olacağını ve idempotency kaydının kalıcı olarak kilitli kalmayacağını doğrulayın.

Hata modu. Deneme başına yeni bir UUID üreten bir yeniden deneme kütüphanesi, tek bir mantıksal işlemi birkaç bağımsız yazmaya dönüştürür ve idempotency'yi tamamen ortadan kaldırır.

Kopan Bir Bağlantı Sonrasında Belirsiz Sonuç

Bu, üretim ortamındaki tek en önemli simülasyondur. K anahtarıyla bir mutasyon gönderin, sunucunun bunu işlemesine izin verin, yanıt gelmeden önce bağlantıyı kesin, sonucu bilinmeyen olarak kaydedin, ardından aynı K anahtarıyla yeniden deneyin ve kaynağı ile denetim verilerini okuyarak mutabakat sağlayın.

Yeniden denemenin orijinal veya belgelenmiş yeniden oynatma yanıtını döndürdüğünü, tam olarak bir finansal yan etkinin mevcut olduğunu, istemcinin işlemi yalnızca başarılı bir yeniden oynatma veya mutabakat okumasından sonra tamamlandı olarak işaretlediğini ve yeni bir anahtar oluşturulmadığını doğrulayın. Zaman aşımı "hiçbir şey olmadı" anlamına gelmez. Stripe idempotency'yi, istemci yanıtı almadan önce sunucunun bir mutasyonu işlemiş olabileceği bağlantı hatalarına karşı koruma olarak açıklar.

Muhafazakar Bir Yeniden Deneme Politikası

Yeniden deneme kararları yalnızca HTTP yöntemine değil, hem hataya hem de işlemin idempotent olup olmadığına bağlıdır.

Genellikle yeniden denenebilir, aynı anahtar korunur: İdempotent bir mutasyondan sonra bağlantı sıfırlanması veya zaman aşımı, 408, retry-after değerine uyulduktan sonra 429 ve 502/503/504. Devam eden belgelenmiş bir idempotency yanıtı kısa bir gecikmeden sonra yeniden denenebilir.

Mutabakat olmaksızın yeniden denenemez: 400/422 doğrulama hataları, 401/403 yetkilendirme hataları, eksik bir kaynak için 404, uçuş halindeki bir anahtarla ilişkili olmayan iş 409 çakışmaları, mevcut bir anahtarda değiştirilmiş yük ve dönem kilit reddi.

Titremeli (jitter) sınırlı üstel geri çekilmeyi (exponential backoff), açık maksimum denemeleri ve geçen süreyi, oran sınırları için dikkate alınan retry-after değerini, bir işlemin yeniden denemelerinde aynı anahtarın korunmasını, her yeni işlem için yeni bir anahtar kullanılmasını ve orijinal denemeyi yeniden denemelerden ayıran günlükleri doğrulayın.

Oran sınırlamasını (rate limiting) kendi başına test edin. Belgelenen eşiği aştıktan sonra (Nordlet, API anahtarı başına varsayılan olarak dakikada 300 isteğe izin verir ve kimlik doğrulaması yapılmayan bazı uç noktalar kendi daha düşük adres başı sınırlarını taşır) sunucunun oran sınırı yanıtı döndürdüğünü, istemcinin retry-after değerini bir hata yerine gecikme olarak ayrıştırdığını, istek yağmuruna tutmak yerine durakladığını ve kısıtlanan bir mutasyon yeniden denemesinin orijinal anahtarı yeniden kullandığını onaylayın. x-ratelimit-* başlıkları kalan bütçeyi bildirir, bu da iyi bir ön doğrulama sağlar. Kısıtlanmış bir denemeyi işlenmiş bir denemeden ayırt edebilecek bir veri sabitiniz yoksa, oran sınırı testlerini finansal doğrulamalardan uzak tutun.

Webhook İmza Doğrulaması

Ham baytları koruyan bir alıcı oluşturun. Her olay için: ham gövdeyi yakalayın, x-nordlet-signature başlığını okuyun, abonelik sırrı (secret) ile beklenen HMAC-SHA256'yı hesaplayın, sabit zamanlı (constant-time) bir işlev kullanarak karşılaştırın, yalnızca doğrulamadan sonra JSON'ı ayrıştırın, teslimatı kaydedin ve dayanıklı kabulden sonra hızlı bir 2xx döndürün. Nordlet, ham gövde üzerinde bir HMAC imzalar, bunu sha256=<hex> olarak gönderir ve teslimatları üstel geri çekilme ile yeniden dener. Stripe'ın webhook rehberliği, değiştirilmemiş ham gövdenin sabit zamanlı karşılaştırma ile doğrulanmasını vurgular.

Olumsuz testler çalıştırın: doğru gövde ve sır, yanlış sır içeren doğru gövde, tek baytlık gövde değişikliği, değiştirilmiş boşluk bırakma ile yeniden serileştirilmiş JSON, eksik başlık, biçimlendirilmiş imza, şema zaman damgası içeriyorsa yeniden oynatılmış eski bir teslimat ve yanlış aboneliğe iletilen geçerli bir imza.

Başarı ölçütleri. Yalnızca doğru ham gövde ve sır kabul edilir. Geçersiz imzalara 2xx dışı yanıt verilir. Geçersiz yükler hiçbir zaman muhasebe kuyruğuna girmez. Sırlar sıradan günlüklerin dışında tutulur. İşleyici, yalnızca olay dayanıklı bir şekilde kaydedildikten sonra onay gönderir.

Mükerrer ve Sıra Dışı (Out-of-Order) Webhook'lar

Teslimat güvenilirliği, API idempotency'sinden ayrı bir sorundur ve alıcı da idempotent olmalıdır. Aynı olayı iki kez teslim edin, bir sale_invoice.issued olayından önce bir sale_invoice.paid olayını teslim edin, kalıcı hale getirdikten ancak yanıt vermeden önce 500 döndürün ve tüketicinin zaten işlediği bir olayı yeniden oynatın.

Mükerrer teslimatların ödemeleri, durum değişikliklerini veya yevmiye eylemlerini mükerrer hale getirmediğini, tekilleştirme anahtarının mevcut olduğunda sağlayıcının teslimat veya olay kimliğini (veya rastgele bir zaman damgası değil, belgelenmiş bir bileşik anahtar) kullandığını, sıra dışı olayların hiçbir zaman eski durumun üzerine yeni durumu yazmadığını, sıranın yetersiz olduğu durumlarda tüketicinin API'den mevcut durumu çekebileceğini ve başarısız tüketici denemelerinin bir kuyruk veya ölü mektup (dead-letter) yoluyla yönlendirildiğini doğrulayın. Stripe, teslimat sırasının garanti edilmediğini açıkça uyarır ve işlenen olay kimliklerinin saklanmasını önerir.

Uç noktayı ince tutun: biçimi doğrulayın, imzayı doğrulayın, kalıcı hale getirin veya kuyruğa ekleyin, onaylayın, 2xx döndürün. Mutabakat ve bildirimler asenkron işlemlere aittir. Aşağı akış çalışmasını teslim zaman aşımını aşacak şekilde uyutarak test edin; doğru bir alıcı, dayanıklı kuyruğa almadan sonra bile onay vermeye devam eder.

Açık ve Kilitli Muhasebe Dönemleri

Nordlet, manuel yevmiyeler, belge akışları ve içe aktarmalar genelinde deftere kaydetme anında dönem kilitlerini uygular, bu nedenle kontrolü birden fazla yerde test edin. Açık bir dönemde, kilitli bir dönemde, kilidin hemen öncesindeki sınırda, sonraki açık dönemin ilk gününde ve API ikisini ayırıyorsa geçerli bir belge tarihi ancak geçersiz bir deftere kaydetme tarihiyle tarih aralığı belirlenmiş eşdeğer belgeler oluşturun.

Kilitli dönem durumu için, isteğin belgelenmiş dönem kilidi hatasıyla reddedildiğini (Nordlet'te 409 conflict), hiçbir yevmiye satırının yazılmadığını, hiçbir belge numarasının tüketilmediğini, hiçbir belgenin deftere nakledildi durumuna geçmediğini ve hiçbir başarı webhook'unun tetiklenmediğini doğrulayın. Açık dönem sürümü aynı finansal değerlerle başarılı olmalıdır.

Yarış (Race) testi. Açık bir döneme karşı deftere kaydetme başlatın, isteğin ortasında dönemi kilitleyin ve işlemin (commit) kilidi atlayamayacağını onaylayın. Kritik başarı koşulu: Onaylanan bir deftere kaydetme işlemi, işlem onaylanmadan önce kilitlenmiş bir döneme asla düşmemelidir.

Denetlenebilirlik ve Mutabakat

Her başarılı mutasyon için iş nesnesinin mevcut olduğunu, borçların alacaklara eşit olduğu muhasebe kaydının mevcut olduğunu, denetim kaydının mevcut olduğunu, webhook olayının mevcut olduğunu veya alınabilir olduğunu ve işlem kaydınızın aynı mantıksal işleme atıfta bulunan yeniden denemelerle birlikte sağlayıcı nesne kimliğine işaret ettiğini doğrulayın.

Reddedilen her mutasyon için kısmi bir belgenin mevcut olmadığını, kontrat rezervasyona izin vermediği sürece hiçbir numaranın tüketilmediğini, hiçbir defter girdisinin olmadığını, hiçbir başarı webhook'unun olmadığını ve hatanın tanılama için bir istek kimliği taşıdığını doğrulayın. Nordlet'in kuralları, mutasyon denetlenebilirliğini ve dengeli deftere kayıtları platform garantileri olarak tanımlar; denge, uygulama kodundan ziyade işleme anında ertelenmiş bir veritabanı tetikleyicisi tarafından zorunlu kılınır. HTTP yanıtına güvenmek yerine bu garantileri test sonrası mutabakat sorgularına dönüştürün.

Temel Test Matrisi

Alan	Test Eylemi	Beklenen Doğrulama	Başarı Ölçütü
Kimlik Doğrulama	Anahtar yok, geçersiz anahtar, yetersiz kapsam	Yapılandırılmış 401/403; yan etki yok	Reddedilen tüm denemeler muhasebe kaydı oluşturmaz
Şema ve Para Birimi	Geçersiz ondalık, tarih, zorunlu alan	Alan düzeyinde doğrulama hatası	Yeniden deneme veya kısmi yazma gerçekleşmez
Normal Deftere Kayıt	Açık bir dönemde fatura oluşturma ve kesme	Bir belge, bir dengeli yevmiye, bir denetim kaydı	Okunan durum ve defter uyuşuyor
Aynı Anahtar Yeniden Oynatma	Aynı anahtar ve gövde ile özdeş mutasyonu yineleme	Orijinal sonuç yeniden oynatılır; mükerrer yok	Nesne kimliği, numara, yevmiye etkisi, denetim tek kalır
Değişen Gövde, Aynı Anahtar	Farklı tutarla anahtarı yeniden kullanma	Belgelenmiş anahtar yeniden kullanım reddi	Orijinal kayıt değişmez; yeni bir şey yazılmaz
Kopan Bağlantı	İşlemi onayla, bağlantıyı kes, aynı anahtarla yeniden dene	Yeniden oynatılmış sonuç	Tam olarak bir finansal yan etki
Kilitli Dönem	Kilitli bir dönemde tarihli bir belgeyi kaydetme	Dönem kilidi reddi	Yevmiye yok, numara yok, başarı webhook'u yok
Webhook İmzası	Yanlış sır, değiştirilmiş gövde	Alıcıdan 2xx dışı yanıt	Yalnızca doğru ham gövde ve sır kabul edilir

İlk Olarak Ne Yapardım

Zamanınız kısıtlıysa, testleri en maliyetli hataları yakalayan sırayla çalıştırın. Kopan bağlantı yeniden denemesiyle başlayın, çünkü bu tek senaryo gerçek mükerrerliklerin çoğunu üretir. Ardından aynı anahtar ve değişen gövde idempotency çiftini çalıştırın. Ardından kilitli dönemleri test edin, çünkü kapalı bir ayda yapılan deftere kayıt, geç ortaya çıkan bir denetim sorunudur. İmza doğrulaması ve sıra dışı webhook'lar sıradakilerdir; tam şema ve yetkilendirme matrisi ise istemci stabil hale geldikten sonra CI ortamında sürekli olarak çalıştırılabilir.

Bu plandaki diğer her şey bu beşini destekler. Bunları mutabakat okumaları yan etkileri teyit edecek şekilde bir korumalı alan şirketinde yeşile döndürün ve entegrasyonun tek bir gerçek deftere dokunmadan önce güvenli olduğunu bileceksiniz. Başlayın sayfasından birkaç dakika içinde bir korumalı alan şirketi ve kapsamlı test anahtarı oluşturabilir ve özellikler listesinden ihtiyacınız olan modülleri kontrol edebilirsiniz.

FAQ

Bir muhasebe yazma işleminin başarılı olduğunu doğrulamak için 2xx yanıtı yeterli midir?

Hayır. Bir durum kodu, sunucunun yanıt verdiğini doğrular; ortada tam olarak bir belge, bir numara tahsisi ve bir dengeli yevmiye kaydı bulunduğunu doğrulamaz. Her mutasyon testi, yanıttan sonra nesnenin, muhasebe etkisinin ve denetim kaydının bir okunmasıyla takip edilmelidir. Tehlikeli durum ise tam tersi yöndedir: istemci yanıtı hiç almazken sunucuda işlenmiş bir işlem.

Bir istek zaman aşımına uğradığında yeni bir idempotency anahtarı oluşturmalı mıyım?

Hayır, üretimdeki mükerrerliklerin çoğuna neden olan hata tam olarak budur. Anahtar, ağ denemesini değil, mantıksal iş işlemini tanımlar. Aynı anahtarla yeniden deneyin, ardından kaynağı okuyarak mutabakat sağlayın. Deneme başına yeni bir UUID üreten bir yeniden deneme kütüphanesi, amaçlanan tek bir faturayı birkaç bağımsız yazmaya dönüştürür.

Farklı bir yük ile bir idempotency anahtarını yeniden kullanırsam ne olur?

Doğru bir API, yeni gövdeyi sessizce uygulamak yerine bunu reddeder. Nordlet 422 idempotency_key_reuse döndürür ve orijinal kaydı değiştirilmemiş olarak bırakır. İstemciniz bunu yeni bir anahtar üreterek çözülecek bir durum olarak değil, düzeltilmesi gereken bir programlama hatası olarak ele almalıdır.

Webhook'lar oluşturulan nesneyi okumanın yerini tutabilir mi?

Hayır. Webhook teslimi, işlemin beklediğiniz gibi onaylandığını değil, aşağı akış bildirimini kanıtlar ve teslimat sırası garanti edilmez. Ham gövde üzerindeki imzayı doğrulayın, teslimat veya olay kimliğine göre tekilleştirin ve yalnızca olay sırasının neyin değiştiğine karar vermek için yeterli olmadığı durumlarda API'den mevcut durumu çekin.

Kilitli bir muhasebe dönemine deftere kaydetme yapmayı nasıl test ederim?

Açık bir dönemde ve kilitli bir dönemde eşdeğer belgeler oluşturun ve kilitli durumun yevmiye satırı, tüketilen belge numarası, durum geçişi ve başarı webhook'u olmaksızın reddedildiğini doğrulayın. Ardından yarış sürümünü çalıştırın: açık bir döneme karşı deftere kaydetme başlatın ve isteğin ortasında dönemi kilitleyin. Onaylanan bir deftere kaydetme, işlem onaylanmadan önce kilitlenmiş bir döneme asla düşmemelidir.

Korumalı alan şirketinde yüksek hacimli mükerrerlik testleri çalıştırabilir miyim?

Evet. Bir korumalı alan şirketi gerçek bir şirket gibi davranır, test verisi olarak etiketlenir ve saklama penceresinden sonra değil hemen silinir, bu nedenle yıkıcı ve mükerrer testler için doğru yerdir. Korumalı alan kullanımı yine de gerçek kullanım gibi ölçümlendirilir ve faturalandırılır, bu nedenle süresiz döngüye girmek yerine hacmi planlayın.