Predprodukčný testovací plán pre účtovné API

Odpoveď 201 Created z účtovného API vám nehovorí takmer nič. Potvrdzuje len to, že server odpovedal. Nepotvrdzuje však, že existuje presne jedna faktúra, že má dal rovné má dať, že číslo dokladu bolo pridelené iba raz, ani to, že opakovaný pokus po prerušení spojenia nezaznamená druhú kópiu. Väčšina produkčných účtovných duplicit vzniká práve v tejto medzere: mutácia sa potvrdila na serveri, zatiaľ čo klient ostal visieť s neznámym výsledkom a potichu to skúšal znova s novým kľúčom.

Tento plán je určený pre tímy, ktoré hodnotia účtovné API predtým, než ho prepoja so skutočnými účtovnými knihami. Zameriava sa na správanie pri zlyhaniach, nie na ideálne scenáre (happy paths). Každá nasledujúca oblasť uvádza, čo treba testovať, čo overovať a čo sa považuje za úspech. Kontextom implementácie je tu Nordlet, ktorého API používa tokeny typu bearer s obmedzeným rozsahom (scoped bearer keys), desatinné reťazce pre peňažné sumy, identifikačné kľúče idempotencie (idempotency keys) a podpísané webhooky. Presnú syntax koncových bodov (endpoints) a štruktúru odpovedí nájdete v dokumentoch Konvencie API a Začíname, nespoliehajte sa na domnienky.

Čo vlastne znamená „úspešne prejsť“

Test dokazuje, že účtovná integrácia je bezpečná, iba vtedy, keď overuje sémantiku, nie stavové kódy. Pri každom scenári by mal testovací balík potvrdiť:

• Obchodný vedľajší účinok: existuje presne jeden zákazník, faktúra, zápis v denníku, pridelené číslo alebo platobný prechod.
• Účtovná integrita: má dať sa rovná dal a peňažná presnosť prežije serializáciu.
• Správanie pri opakovaní: opakovaný pokus vráti pôvodný výsledok namiesto nového záznamu.
• Trvácnosť: audítorské záznamy a udalosti webhookov existujú po potvrdení (commit) operácie.
• Zlyhania bez vedľajších účinkov: odmietnuté požiadavky nespotrebujú žiadne čísla dokladov ani nezapíšu žiadne čiastočné riadky hlavnej knihy.
• Obnova: prechodná chyba sa dá zopakovať bez duplikácie alebo trvalej straty.

Smernica Google pre API stanovuje jasnú hranicu: bezpečné na zlyhanie a opakovanie sú len tie operácie, ktorých opakované vykonanie zanechá rovnaký konečný stav, pričom API by malo identifikovať, ktoré operácie sú idempotentné, namiesto toho, aby slepé opakovalo každé zlyhanie.

Nastavenie jednorazového a pozorovateľného prostredia

Použite testovaciu (sandbox) spoločnosť, nie produkčné účtovníctvo. Sandboxová spoločnosť v systéme Nordlet používa rovnaké moduly a správanie API ako skutočná spoločnosť a je označená ako testovacie dáta, vďaka čomu je bezpečná pre vysokofrekvenčné testy duplicít a zlyhaní. Tento príznak je po vytvorení nemenný, takže skutočné účtovníctvo sa neskôr nedá preklasifikovať na testovacie dáta. Upozorňujeme, že používanie sandboxu sa meria a fakturuje rovnako ako používanie v skutočnej spoločnosti, takže veľkosť záťažových testov prispôsobte cenníku, na ktorom sa nachádzate.

Pred napísaním akéhokoľvek testu si pripravte:

• Vyhradenú sandboxovú spoločnosť s nastavením isSandbox: true.
• Testovací API kľúč obmedzený iba na testované moduly.
• Koncový bod webhooku alebo lokálny tunel, ktorý zachováva surové telo požiadavky (raw body).
• Predpripravených zákazníkov, dodávateľov a známu účtovnú osnovu.
• Minimálne dve účtovné obdobia: jedno otvorené, druhé uzamknuté.
• Testovacie hodiny alebo dátumový fix, ak ho implementácia podporuje.
• Lokálne úložisko, ktoré zaznamenáva každý pokus o požiadavku, kľúč idempotencie, hash odpovede, doručenie webhooku a výsledok odsúhlasenia (reconciliation).

Nespúšťajte testy duplicít nad zdieľanými staging údajmi. Zblúdilý zákazník alebo faktúra z predchádzajúceho behu robí neskoršie overenia nejednoznačnými.

Vaša testovacia vzorka (fixture) pre každú mutáciu by mala zachytávať metódu, koncový bod, celé telo, kľúč idempotencie, rozsah kľúča (key scope), klientske ID korelácie, časové značky začiatku a konca, stav odpovede, hlavičky, telo, ID požiadavky a informáciu o tom, či spojenie spadlo skôr, ako dorazila odpoveď. Na peniaze používajte pevné desatinné reťazce, napríklad "75.0000". Nordlet reprezentuje peňažné hodnoty ako desatinné reťazce s až štyrmi desatinnými miestami a jeho vzorová faktúra tento formát využíva.

Druhou polovicou prípravy je injektáž chýb. Váš testovací nástroj by mal dokázať oneskoriť odpoveď, zhodiť TCP spojenie po tom, čo server prijal požiadavku, vracať syntetické odpovede 429/500/502/503/504, vrátiť kód iný ako 2xx z prijímača webhooku, doručiť rovnaký webhook dvakrát, zmeniť poradie udalostí, poškodiť jeden bajt tela webhooku, zmeniť užitočné zaťaženie (payload) kľúča idempotencie pri zachovaní kľúča, spustiť dve identické požiadavky súčasne a uzamknúť obdobie medzi nastavením a zaúčtovaním. Tieto scenáre majú väčšiu hodnotu než sto príkladov ideálnych stavov.

Zablokovanie kontraktu pred napísaním logiky opakovaní

Vygenerujte alebo načítajte schému OpenAPI a porovnajte ju so svojím klientom. Nordlet zverejňuje svoju špecifikáciu OpenAPI v referencii API a z tej istej špecifikácie generuje svoje typové sady SDK, takže testy riadené schémou prekonávajú ručne písané domnienky.

Overte povinné polia a typy, polia s desatinnými reťazcami, formáty dátumov a časových značiek, povolené akcie a rozsahy, tvar obálky chýb, schémy udalostí webhookov, ktoré mutácie akceptujú kľúč idempotencie a ktoré polia odpovede identifikujú vytvorený objekt.

Kritériá úspechu. Klient lokálne odmieta neplatné užitočné zaťaženia všade tam, kde to schéma umožňuje. Odpovede servera zodpovedajú dokumentovanej schéme. Neplatné desatinné čísla, zlé dátumy a chýbajúce povinné polia produkujú štruktúrované chyby overenia. Pri deterministickom zlyhaní overenia sa nepokúšate o žiadne opakovanie.

Režim zlyhania, ktorý treba zachytiť. Klient parsuje "121.0000" na binárne desatinné číslo s plávacou rádovou čiarkou (float) a neskôr serializuje mierne odlišnú sumu. Celé čísla prejdú, ale riadky DPH a čiastkové množstvá zlyhajú. Testujte peniaze ako reťazce od začiatku do konca.

Autorizácia a izolácia nájomníkov (tenants)

Používajte samostatné kľúče na čítanie a zápis. Potom otestujte celú maticu: chýbajúci kľúč, neplatný kľúč, platný kľúč s nedostatočným rozsahom modulu, platný kľúč so správnym rozsahom, kľúč patriaci inej spoločnosti a pokus o prečítanie objektu z inej spoločnosti.

Overenia:

• Chýbajúce alebo neplatné poverenia vrátia 401.
• Platný kľúč bez požadovaného oprávnenia vráti 403.
• Pri žiadnom z týchto zlyhaní nevznikne účtovný vedľajší účinok.
• Úspešná požiadavka nemôže čítať ani meniť záznamy inej spoločnosti.
• Bezpečnostné zlyhania sa nikdy neopakujú automaticky.

Kritérium úspechu. Správnosť autorizácie aj izoláciu nájomníkov môžete dokázať následným čítaním po teste, nielen stavovými kódmi.

Preukázanie jednej čistej transakcie

Spustite malý, deterministický tok: vytvorte alebo nájdite testovacieho zákazníka, vytvorte faktúru s desatinnými reťazcovými sumami, vystavte ju, prečítajte faktúru a jej účtovný dopad, prečítajte záznam auditu a prijmite webhook. Príklad Začíname v systéme Nordlet ukazuje, že vystavenie faktúry priradí číslo bez medzier, skontroluje, či je obdobie otvorené, and zaúčtuje vyrovnaný denný záznam v tej istej transakcii.

Overte, či faktúra dosiahne očakávaný stav, číslo dokladu je pridelené presne raz, má dať sa rovná dal, DPH a súčty riadkov zodpovedajú očakávanému zaokrúhleniu nahor, auditný záznam uvádza aktéra a zmenu, webhook je nakoniec doručený a odpoveď API spolu s následným čítaním sa zhodujú na ID a stave faktúry.

Jedno rozlíšenie, ktoré sa oplatí dodržiavať: doručenie webhooku nie je dôkazom toho, že mutácia sa potvrdila. Odpoveď API plus opätovné prečítanie sú vaše primárne transakčné overenia. Webhook dokazuje následnú notifikáciu a testuje sa osobitne.

Idempotencia: rovnaký kľúč, rovnaké telo

Vygenerujte jeden kľúč na jednu logickú obchodnú operáciu, nie jeden kľúč na jeden sieťový pokus. Odošlite mutáciu s kľúčom K a telom B, uložte vytvorené ID a potom odošlite presne tú istú požiadavku znova.

Overte, či druhá odpoveď reprezentuje tú istú operáciu, ID objektu je identické a existuje presne jeden obchodný objekt, jeden zápis, jedno číslo dokladu a jeden finančný dopad. Opätovne prehratá odpoveď by mala niesť dokumentovanú hlavičku opakovania – v prípade Nordletu x-idempotent-replay: true – a auditná stopa by nemala vykazovať žiadnu druhú mutáciu.

Dve pravidlá úložiska menia to, čo by mala vaša slučka opakovania očakávať, takže ich otestujte priamo: uložená chyba 4xx sa prehráva rovnako ako akákoľvek iná odpoveď, zatiaľ čo chyba 5xx sa neuloží vôbec, takže opakovaný pokus po chybe servera operáciu znova nevykoná, ale opätovne spustí. Kľúče tiež vypršiavajú, v systéme Nordlet po 24 hodinách, čím sa obmedzuje čas, počas ktorého je opätovné prehratie k dispozícii.

Dokumentácia Nordletu sľubuje, že pridanie hlavičky Idempotency-Key zabráni tomu, aby opakovaná požiadavka vytvorila duplicitu, a jeho konvencie API definujú presnú hlavičku opakovania a požiadavku na zhodu odpovede bajt po bajte. Tento princíp sa zhoduje so zverejneným modelom spoločnosti Stripe: kľúč identifikuje logickú operáciu, opakovania vracajú uložený výsledok a kľúč opätovne použitý s inými parametrami je odmietnutý namiesto tichej zmeny.

Kritérium úspechu. Bez ohľadu na to, koľkokrát klient odošle rovnakú požiadavku v rámci okna opätovného prehratia, existuje presne jeden prechod finančného stavu.

Idempotencia: rovnaký kľúč, zmenené telo

Odošlite pôvodnú požiadavku s kľúčom K a telom B1, potom druhú požiadavku s kľúčom K a telom B2, kde sa líši aspoň jedna suma, zákazník, dátum alebo riadok.

Očakávaný výsledok: požiadavka je odmietnutá s dokumentovanou chybou opätovného použitia kľúča – Nordlet vracia 422 idempotency_key_reuse –, pôvodný záznam zostáva nedotknutý, nevzniká žiadny druhý záznam, číslo ani auditná mutácia a klient situáciu „nevyrieši“ vygenerovaním nového kľúča. Tiché akceptovanie B2 by spravilo kľúče pre opakovanie nebezpečnými.

Súbežné duplicitné požiadavky

Odošlite dve identické požiadavky s rovnakým kľúčom v presne tom istom okamihu. V závislosti od dokumentovaného správania jedna prebehne, zatiaľ čo druhá dostane prebiehajúci konflikt – Nordlet vracia 409 idempotency_in_progress –, alebo nakoniec obe zaznamenajú rovnaký výsledok.

Overte, či oba príkazy nemôžu vytvoriť nezávislé finančné dopady, či sa pridelí najviac jedno číslo dokladu, či sa dočasný konflikt opakuje s rovnakým kľúčom namiesto nového, či je výsledný zdroj kompletný a čitateľný a či záznam idempotencia nezostane trvalo zablokovaný.

Režim zlyhania. Knižnica pre opakované pokusy, ktorá pri každom pokuse vytvorí nové UUID, premení jednu logickú operáciu na niekoľko nezávislých zápisov a úplne zneguje idempotenciu.

Neistý výsledok po prerušenom spojení

Toto je vôbec najdôležitejšia simulácia pre prevádzku. Odošlite mutáciu s kľúčom K, nechajte server ju potvrdiť, prerušte spojenie skôr, ako dorazí odpoveď, zaznamenajte výsledok ako neznámy, potom to zopakujte s rovnakým kľúčom K a preverte stav prečítaním zdroja a údajov auditu.

Overte, či opakovaný pokus vráti pôvodnú alebo dokumentovanú odpoveď opätovného prehratia, či existuje presne jeden finančný vedľajší účinok, či klient označí operáciu ako dokončenú až po úspešnom opätovnom prehratí alebo prečítaní pre účely odsúhlasenia a či sa nevygeneroval žiadny nový kľúč. Časový limit (timeout) neznamená „nič sa nestalo“. Spoločnosť Stripe opisuje idempotenciu presne ako ochranu pred chybami spojenia, kedy server mohol spracovať mutáciu predtým, než klient stihol prijať odpoveď.

Konzervatívna politika opakovaní

Rozhodnutia o opakovaní závisia od chyby aj od toho, či je operácia idempotentná, a nie iba od HTTP metódy.

Zvyčajne opakovateľné pri zachovaní rovnakého kľúča: resetovanie spojenia alebo vypršanie časového limitu po idempotentnej mutácii, 408, 429 po rešpektovaní hlavičky retry-after a 502/503/504. Dokumentovanú odpoveď o prebiehajúcej idempotencii možno zopakovať po krátkom oneskorení.

Neopakovateľné bez odsúhlasenia: chyby overenia 400/422, zlyhania overenia totožnosti 401/403, 404 pre chýbajúci zdroj, obchodné konflikty 409 nesúvisiace s prebiehajúcim kľúčom, zmenené užitočné zaťaženie pri existujúcom kľúči a odmietnutie kvôli uzamknutiu obdobia.

Overte ohraničený exponenciálny rast oneskorenia (exponential backoff) s náhodnou odchýlkou (jitter), explicitný maximálny počet pokusov a uplynutý čas, rešpektovanie hlavičky retry-after pre obmedzenia rýchlosti (rate limits), zachovanie rovnakého kľúča naprieč opakovaniami jednej operácie, nový kľúč pre každú novú operáciu a záznamy (logs), ktoré oddeľujú pôvodný pokus od opakovaní.

Otestujte obmedzovanie rýchlosti samostatne. Prekročte dokumentovanú hranicu – Nordlet štandardne povoľuje 300 požiadaviek za minútu na jeden API kľúč, pričom niektoré neautentifikované koncové body nesú vlastné nižšie limity na adresu – a potom potvrďte, že server vráti odpoveď o obmedzení rýchlosti, klient spracuje retry-after ako oneskorenie namiesto chyby, pozastaví sa namiesto neustáleho opakovania a opakovaná obmedzená mutácia znova použije pôvodný kľúč. Hlavičky x-ratelimit-* informujú o zostávajúcom kredite, čo slúži ako dobré predbežné overenie. Testy obmedzenia rýchlosti držte ďalej od finančných overení, pokiaľ váš nástroj nedokáže odlíšiť obmedzený pokus od potvrdeného.

Overenie podpisu webhooku

Vytvorte prijímač, ktorý zachováva surové bajty. Pre každú udalosť: zachyťte surové telo, prečítajte hlavičku x-nordlet-signature, vypočítajte očakávaný HMAC-SHA256 pomocou tajného kľúča predplatného, porovnajte ho pomocou funkcie odolnej voči časovým útokom (constant-time function), parsujte JSON až po overení, zaznamenajte doručenie a po trvácnom prijatí vráťte rýchlu odpoveď 2xx. Nordlet podpisuje HMAC nad surovým telom, posiela ho ako sha256=<hex> a doručenia opakuje s exponenciálnym rastom oneskorenia. Pokyny pre webhooky od spoločnosti Stripe zdôrazňujú overovanie nezmeneného surového tela pomocou porovnania odolného voči časovým útokom.

Spustite negatívne testy: správne telo a tajný kľúč, správne telo so zlým tajným kľúčom, zmena jedného bajtu tela, re-serializovaný JSON so zmenenými bielymi znakmi, chýbajúca hlavička, chybný podpis, opätovne prehrané staré doručenie, ak schéma zahŕňa časovú značku, a platný podpis doručený na nesprávne predplatné.

Kritériá úspechu. Akceptované je iba správne surové telo a tajný kľúč. Neplatné podpisy získajú kód iný ako 2xx. Neplatné užitočné zaťaženia sa nikdy nedostanú do účtovnej fronty. Tajné kľúče zostávajú mimo bežných záznamov.

Duplicitné webhooky a webhooky mimo poradia

Spoľahlivosť doručenia je samostatný problém od idempotencie API a prijímač musí byť tiež idempotentný. Doručte tú istú udalosť dvakrát, doručte udalosť sale_invoice.paid pred udalosťou sale_invoice.issued, vráťte kód 500 po uperzistentnení, ale pred odoslaním odpovede, a prehrajte udalosť, ktorú odberateľ už spracoval.

Overte, či duplicitné doručenia neduplikujú platby, zmeny stavov ani akcie v denníku, či kľúč deduplikácie používa ID doručenia alebo udalosti poskytovateľa, ak existuje (alebo dokumentovaný zložitý kľúč, nikdy nie ľubovoľnú časovú značku), či udalosti mimo poradia nikdy neprepíšu novší stav starším, či spotrebiteľ môže načítavať aktuálny stav z API, keď poriadok nestačí, a či zlyhané pokusy spotrebiteľa prechádzajú cez frontu alebo cestu mŕtvych správ (dead-letter path). Stripe výslovne varuje, že poradie doručenia nie je zaručené, a odporúča ukladanie spracovaných ID udalostí.

Udržujte koncový bod tenký: overte tvar, overte podpis, uložte do úložiska alebo fronty, potvrďte príjem, vráťte 2xx. Odsúhlasenie a notifikácie patria do asynchrónneho spracovania. Otestujte to tak, že prinútite následnú prácu usnúť za časovým limitom doručenia; správny prijímač stále potvrdí príjem po trvácnom zaradení do fronty.

Otvorené a uzamknuté účtovné obdobia

Nordlet vynucuje zámky období v čase zaúčtovania naprieč manuálnymi denníkmi, tokmi dokumentov a importmi, takže kontrolu otestujte na viacerých miestach. Vytvorte ekvivalentné dokumenty s dátumom v otvorenom období, v uzamknutom období, na hranici tesne pred uzamknutím, v prvý deň nasledujúceho otvoreného obdobia a s platným dátumom dokumentu, ale neplatným dátumom zaúčtovania, ak API tieto dva údaje oddeluje.

V prípade uzamknutého obdobia overte, že požiadavka je odmietnutá s dokumentovanou chybou zámku obdobia – v Nordlete ide o konflikt 409 conflict – a že sa nezapísali žiadne riadky denníka, nespotrebovalo sa žiadne číslo dokladu, žiaden dokument neprešiel do stavu zaúčtovania a nespustil sa úspešný webhook. Verzia pre otvorené obdobie by mala byť úspešná s rovnakými finančnými hodnotami.

Súbežný test (Race test). Spustite zaúčtovanie do otvoreného obdobia, uzamknite obdobie uprostred požiadavky a potvrďte, že potvrdenie (commit) nemôže obísť zámok. Kritická podmienka úspechu: potvrdené zaúčtovanie sa nikdy nesmie ocitnúť v období, ktoré bolo uzamknuté skôr, než sa transakcia potvrdila.

Auditovateľnosť a odsúhlasenie

Pre každú úspešnú mutáciu potvrďte, že existuje obchodný objekt, existuje účtovný záznam s má dať sa rovnajúcim dal, existuje auditný záznam, udalosť webhooku existuje alebo je načítateľná a váš prevádzkový záznam smeruje na ID objektu poskytovateľa, pričom opakovania odkazujú na tú istú logickú operáciu.

Pre každú odmietnutú mutáciu potvrďte, že neexistuje žiadny čiastočný dokument, nespotrebovalo sa žiadne číslo, pokiaľ to kontrakt nepovoľuje rezervovať, neexistuje žiadny záznam hlavnej knihy, neexistuje žiadny úspešný webhook a chyba nese ID požiadavky pre diagnostiku. Konvencie Nordletu opisujú auditovateľnosť mutácií a vyrovnané zápisy ako garancie platformy, pričom vyrovnanie je vynútené odloženým databázovým spúšťačom (trigger) v čase potvrdenia, a nie iba aplikačným kódom. Premeňte tieto garancie na pretestovacie dopyty na odsúhlasenie namiesto dôvery v odpoveď HTTP.

Hlavná testovacia matica

Oblast	Testovacia akcia	Očakávané overenie	Kritérium úspechu
Autentifikácia	Bez kľúča, neplatný kľúč, nedostatočný rozsah	Štruktúrovaná chyba 401/403; žiadny vedľajší účinok	Všetky odmietnuté pokusy nevytvoria žiaden účtovný záznam
Schéma a peniaze	Neplatné desatinné číslo, dátum, povinné pole	Chyba overenia na úrovni poľa	Nedôjde k žiadnemu opakovaniu ani čiastočnému zápisu
Bežné zaúčtovanie	Vytvorenie a vystavenie faktúry v otvorenom období	Jeden dokument, jeden vyrovnaný denník, jeden auditný záznam	Stav pri spätnom čítaní a hlavná kniha sa zhodujú
Opätovné prehratie s rovnakým kľúčom	Zopakovaním identickej mutácie, rovnaký kľúč a telo	Pôvodný výsledok prehraný; žiadna duplicita	ID objektu, číslo, dopad na denník, audit zostávajú jednotné
Zmenené telo, rovnaký kľúč	Opätovné použitie kľúča s inou sumou	Dokumentované odmietnutie opätovného použitia kľúča	Pôvodný záznam nezmenený; nič nové sa nezapísalo
Prerušené spojenie	Potvrdenie, výpadok, opakovanie s rovnakým kľúčom	Prehraný výsledok	Presne jeden finančný vedľajší účinok
Uzamknuté obdobie	Zaúčtovanie dokumentu s dátumom v uzamknutom období	Odmietnutie kvôli zámku obdobia	Žiadny denník, žiadne číslo, žiaden úspešný webhook
Podpis webhooku	Nesprávny tajný kľúč, zmenené telo	Kód iný ako 2xx od prijímača	Akceptované iba správne surové telo a tajný kľúč

Čo by som urobil najskôr

Ak je málo času, spustite testy v poradí, ktoré zachytáva najdrahšie chyby. Začnite s opakovaním pri prerušenom spojení, pretože práve tento jeden scenár vytvára väčšinu reálnych duplicít. Potom nasleduje dvojica idempotencie pre rovnaký kľúč a zmenené telo. Ďalej uzamknuté obdobia, pretože zaúčtovanie v uzavretom mesiaci je problém auditu, ktorý sa prejaví neskôr. Overenie podpisu a webhooky mimo poradia nasledujú potom a celá matica schémy a autorizácie môže bežať nepretržite v CI hneď, ako sa klient ustáli.

Všetko ostatné v tomto pláne podporuje týchto päť bodov. Dosiahnite ich zelený stav (pass) voči sandboxovej spoločnosti, pričom čítania pre odsúhlasenie potvrdia vedľajšie účinky, a budete vedieť, že integrácia je bezpečná predtým, než sa dotkne čo i len jednej skutočnej účtovnej knihy. Sandboxovú spoločnosť a testovací kľúč s obmedzeným rozsahom si môžete vytvoriť za pár minút v časti Začať a požadované moduly si môžete skontrolovať v zozname funkcií.

FAQ

Je odpoveď 2xx dostatočná na potvrdenie, že zápis do účtovníctva prebehol úspešne?

Nie. Stavový kód potvrdzuje, že server odpovedal, nie to, že existuje presne jeden dokument, jedno pridelenie čísla a jeden vyrovnaný denný záznam. Každý test mutácie by mal po odpovedi nasledovať spätné čítanie objektu, jeho účtovného dopadu a auditného záznamu. Nebezpečný prípad je opačný smer: operácia, ktorá sa potvrdila, zatiaľ čo klient tú odpoveď vôbec neprijal.

Mám vygenerovať nový kľúč idempotencie, keď požiadavka vyprší na časovom limite (timeout)?

Nie, a toto je chyba, ktorá spôsobuje väčšinu produkčných duplicít. Kľúč identifikuje logickú obchodnú operáciu, nie sieťový pokus. Zopakujte rovnaký kľúč a potom urobte odsúhlasenie prečítaním zdroja. Knižnica opakovaní, ktorá pri každom pokuse vytvorí nové UUID, premení jednu zamýšľanú faktúru na niekoľko nezávislých zápisov.

Čo sa stane, ak opätovne použijem kľúč idempotencie s iným užitočným zaťažením (payload)?

Správne API ho odmietne namiesto tichého použitia nového tela. Nordlet vracia 422 idempotency_key_reuse a ponecháva pôvodný záznam nedotknutý. Váš klient by to mal považovať za programátorskú chybu, ktorú treba opraviť, a nie za stav, ktorý treba obísť vygenerovaním nového kľúča.

Sú webhooky náhradou za spätné prečítanie vytvoreného objektu?

Nie. Doručenie webhooku dokazuje následnú notifikáciu, nie to, že transakcia prebehla tak, ako očakávate, pričom poradie doručenia nie je zaručené. Overte podpis nad surovým telom, deduplikujte podľa ID doručenia alebo udalosti a načítajte aktuálny stav z API vždy, keď samotné poradie udalostí nestačí na rozhodnutie o tom, čo sa zmenilo.

Ako otestujem zaúčtovanie do uzamknutého účtovného obdobia?

Vytvorte ekvivalentné dokumenty v otvorenom období a v uzamknutom období a overte, že prípad v uzamknutom období je odmietnutý bez riadkov denníka, bez spotrebovaného čísla dokladu, bez prechodu stavu a bez úspešného webhooku. Potom spustite verziu so súbehom: začnite zaúčtovanie do otvoreného obdobia a uzamknite obdobie uprostred požiadavky. Potvrdené zaúčtovanie sa nesmie nikdy ocitnúť v období, ktoré bolo uzamknuté skôr, než sa transakcia potvrdila.

Môžem spustiť vysokofrekvenčné testy duplicít v sandboxovej spoločnosti?

Áno. Sandboxová spoločnosť sa správa ako skutočná, je označená ako testovacie dáta a maže sa okamžite namiesto čakania po období uchovávania, takže je to správne miesto na deštruktívne testovanie a testovanie duplicít. Používanie sandboxu sa však stále meria a fakturuje ako skutočné použitie, takže objem naplánujte namiesto nekonečného opakovania v cykle.