Pre-production tesztterv könyvelési API-khoz

Egy könyvelési API által visszaadott 201 Created válasz szinte semmit sem mond. Mindössze azt igazolja, hogy a szerver válaszolt. Nem erősíti meg, hogy pontosan egy számla létezik, hogy a tartozik és követel egyenlegek megegyeznek, hogy a bizonylatszámot egyszer osztották ki, vagy azt, hogy egy megszakadt kapcsolat utáni újrapróbálkozás nem könyvel le egy második példányt is. A legtöbb éles könyvelési duplikáció ebből a hiányosságból fakad: egy olyan módosításból, amely lefutott a szerveren, miközben az ügyféloldal bizonytalan kimenettel várt, és csendben, egy új kulccsal újrapróbálkozott.

Ez a tesztterv azoknak a csapatoknak szól, რომლებიც egy könyvelési API-t értékelnek, mielőtt azt valós könyvelési adatokra kötnék. A tervezett hibajelenségekre fókuszál, nem a sikeres útvonalakra. Az alábbi területek mindegyike bemutatja, mit kell tesztelni, milyen feltételeket kell ellenőrizni, és mi számít sikeres teljesítésnek. Az itteni implementációs környezet a Nordlet, amelynek API-ja hatókörhöz kötött bearer kulcsokat, decimális karakterláncként megadott összegeket, idempotencia-kulcsokat és aláírt webhookokat használ. A pontos végpontszintaxisért és a válaszok formátumáért olvassa el az API-konvenciók és az Első lépések oldalakat ahelyett, hogy feltételezésekre támaszkodna.

Mit jelent a gyakorlatban a „siker”?

Egy teszt csak akkor bizonyítja, hogy egy könyvelési integráció biztonságos, ha a szemantikát ellenőrzi, nem pedig a státuszkódokat. A tesztcsomagnak minden egyes forgatókönyv esetén meg kell erősítenie az alábbiakat:

• Üzleti mellékhatás: pontosan egy ügyfél, számla, főkönyvi tétel, sorszámkiosztás vagy fizetési státuszváltás létezik.
• Számviteli integritás: a tartozik egyenlő a követellel, és a monetáris pontosság fennmarad a szerializáció során.
• Újrajátszási (replay) viselkedés: egy újrapróbálkozás az eredeti eredményt adja vissza új rekord létrehozása helyett.
• Adattartósság (durability): a naplóbejegyzések és a webhook-események a művelet véglegesítése (commit) után léteznek.
• Mellékhatás-mentes hibák: a elutasított kérések nem használnak fel bizonylatszámot, és nem írnak részleges főkönyvi sorokat.
• Helyreállítás: egy átmeneti hiba duplikáció vagy adatvesztés nélkül újrapróbálható.

A Google API-útmutatója világosan meghúzza a határt: csak azok a műveletek biztonságosan próbálhatók újra, amelyek ismételt végrehajtása ugyanazt a végső állapotot eredményezi, és az API-nak azonosítania kell, hogy mely műveletek idempotensek ahelyett, hogy minden hibát vakon újrapróbálna.

Hozzon létre egy különálló, megfigyelhető környezetet

Használjon tesztcéget (sandbox company), ne az éles könyvelést. A Nordlet tesztcénge ugyanazokat a modulokat és API-viselkedést használja, mint egy valódi cég, de tesztadatként van megjelölve, ami biztonságossá teszi a nagy volumensű duplikációs és hibatesztekhez. Ez a jelölés a létrehozás után már nem módosítható, így az éles könyvelés később nem sorolható át tesztadatnak. Ne feledje, hogy a tesztkörnyezet használata mérésre kerül, és pontosan úgy számlázódik, mint a valódi cégben végzett tevékenység, ezért a terheléses teszteket az Ön árazási csomagjához igazítva méretezze.

Mielőtt bármilyen tesztszkriptet írna, készítse elő a következőket:

• Egy dedikált tesztcéget isSandbox: true beállítással.
• Egy teszt API-kulcsot, amely kizárólag a tesztelt modulokra érvényes.
• Egy webhook végpontot vagy helyi alagutat (tunnel), amely megőrzi a nyers kérés törzsét (body).
• Előre feltöltött ügyfeleket, beszállítókat és egy ismert számlatükröt.
• Legalább két könyvelési időszakot: egy nyitottat és egy lezártat.
• Egy tesztórát vagy dátum-fixture-t, ha az implementáció támogatja azt.
• Egy helyi adattárat, amely rögzíti az összes kísérletet, idempotencia-kulcsot, válaszhast, webhook-kézbesítést és egyeztetési (reconciliation) eredményt.

Ne futtasson duplikációs teszteket megosztott staging adatokon. Egy korábbi futásból visszamaradt kószáló ügyfél vagy számla kétértelművé teszi a későbbi ellenőrzéseket.

Minden egyes adatváltoztatási művelethez (mutation) tartozó fixture-nek rögzítenie kell a metódust, a végpontot, a teljes törzset, az idempotencia-kulcsot, a kulcs hatókörét, az ügyfél korrelációs azonosítóját, a kezdési és befejezési időbélyegeket, a válasz státuszát, a fejléceket, a törzset, a kérés azonosítóját (request ID), valamint azt, hogy a kapcsolat megszakadt-e a válasz megérkezése előtt. Pénzösszegekhez használjon fix decimális karakterláncokat, például "75.0000" formátumban. A Nordlet a pénzbeli értékeket legfeljebb négy tizedesjegyű decimális karakterláncként ábrázolja, és a példaszámlája is ezt a formátumot használja.

A beállítás másik fele a hibainjekció. A tesztkeretrendszernek képesnek kell lennie késleltetni egy választ, megszakítani a TCP-kapcsolatot a kérés szerver általi beérkezése után, szintetikus 429/500/502/503/504 válaszokat adni, nem 2xx választ küldeni a webhook-fogadótól, kétszer kézbesíteni ugyanazt a webhookot, átrendezni az eseményeket, egyetlen bájttal meghibásítani a webhook törzsét, megváltoztatni az idempotencia-kulcs payloadját a kulcs megtartása mellett, két azonos kérést párhuzamosan futtatni, valamint lezárni egy időszakot a beállítás és a könyvelés (posting) között. Ezek a forgatókönyvek többet érnek, mint száz sikeres útvonalon alapuló példa.

Rögzítse a szerződést az újrapróbálkozási logika megírása előtt

Generálja le vagy kérje le az OpenAPI sémát, és hasonlítsa össze a kliensével. A Nordlet az OpenAPI specifikációját az API-referenciában teszi közzé, és a gépelt SDK-kat ugyanebből a specifikációból generálja, így a sémaközpontú tesztek felülmúlják a kézzel írt feltételezéseket.

Ellenőrizze a kötelező mezőket és típusokat, a decimális karakterlánc mezőket, a dátum- és időbélyegformátumokat, az engedélyezett műveleteket és hatóköröket, a hibaesemény (error envelope) alakját, a webhook eseménysémáit, azt, hogy mely módosítások fogadnak el idempotencia-kulcsot, és mely válaszmezők azonosítják a létrehozott objektumot.

Sikerességi feltételek. A kliens helyben elutasítja az érvénytelen payloadokat, ahol a séma ezt engedi. A szerver válaszai illeszkednek a dokumentált sémához. Az érvénytelen tizedesjegyek, a rossz dátumok és a hiányzó kötelező mezők strukturált validációs hibákat eredményeznek. Determinisztikus validációs hiba esetén a rendszer nem kísérli meg az újrapróbálkozást.

Kiszűrendő hibaesemény. A kliens a "121.0000" értéket bináris lebegőpontos számmá (float) alakítja, és később egy kissé eltérő összeget szerializál. Az egész számok átmennek; az ÁFA-sorok és a törtrészes mennyiségek megbuknak. Tesztelje a pénzösszegeket karakterláncként az elejétől a végéig.

Jogosultságkezelés és bérlői (tenant) izoláció

Használjon külön kulcsokat az olvasáshoz és a íráshoz. Ezután tesztelje a teljes mátrixot: hiányzó kulcs, érvénytelen kulcs, érvénytelen modulhatókörrel rendelkező érvényes kulcs, helyes hatókörrel rendelkező érvényes kulcs, egy másik céghez tartozó kulcs, valamint kísérlet egy másik cég objektumának olvasására.

Feltételek:

• A hiányzó vagy érvénytelen hitelesítő adatok 401-es hibát adnak vissza.
• A szükséges engedély nélküli érvényes kulcs 403-as hibát ad vissza.
• Egyik hiba esetén sem jön létre számviteli mellékhatás.
• A sikeres kérés nem tudja olvasni vagy módosítani egy másik cég rekordjait.
• A biztonsági hibákat a rendszer soha nem próbálja meg automatikusan újraindítani.

Sikerességi feltétel. Tesztelés utáni olvasásokkal, nem csupán státuszkódok alapján bizonyítani tudja a jogosultságok helyességét és a bérlők izolációját.

Bizonyítson be egy tiszta tranzakciót

Futtasson le egy kis méretű, determinisztikus folyamatot: hozzon létre vagy keressen meg egy tesztügyfelet, hozzon létre egy számlát decimális karakterlánc összeggel, bocsássa ki, olvassa be a számlát és annak számviteli hatását, olvassa be a naplóbejegyzést, és fogadja a webhookot. A Nordlet Első lépések példája bemutatja, hogy a számlakibocsátás hézagmentes sorszámot oszt ki, ellenőrzi, hogy az időszak nyitva van-e, és egy tranzakción belül könyvel le egy egyensúlyban lévő főkönyvi tételt.

Győződjön meg arról, hogy a számla eléri a várt állapotot, a bizonylatszámot pontosan egyszer osztják ki, a tartozik és a követel egyenlegek megegyeznek, az ÁFA és a sorok végösszegei illeszkednek a várt félfelfelé kerekítési (half-up) számításhoz, a naplóbejegyzés megnevezi a cselekvőt és a változtatást, a webhook idővel megérkezik, valamint az API-válasz és a későbbi olvasás megegyezik a számla azonosítójában és állapotában.

Egy fontos megkülönböztetés: egy webhook megérkezése nem bizonyíték arra, hogy a módosítás véglegesítésre került. Az API-válasz plusz az olvasás az elsődleges tranzakciós ellenőrzés. A webhook az alsóbb rétegek értesítését bizonyítja, és azt külön kell tesztelni.

Idempotencia: azonos kulcs, azonos törzs

Logikai üzleti műveletenként generáljon egy kulcsot, ne pedig hálózati kísérletenként. Küldje el a módosítást a K kulccsal és a B törzzsel, mentse el a létrehozott azonosítót, majd küldje el pontosan ugyanezt a kérést újra.

Győződjön meg arról, hogy a második válasz ugyanazt a műveletet képviseli, az objektumazonosító azonos, és egyetlen üzleti objektum, egyetlen könyvelés, egyetlen bizonylatszám, valamint egyetlen pénzügyi hatás létezik. Az újrajátszott válasznak tartalmaznia kell a dokumentált újrajátszási fejlécet - a Nordlet esetében ez a x-idempotent-replay: true –, és a auditnaplónak nem szabad második módosítást mutatnia.

Két tárolási szabály határozza meg, mire számítson az újrapróbálkozási hurokban, ezért tesztelje ezeket közvetlenül: a tárolt 4xx válaszokat a rendszer bármely más válaszhoz hasonlóan játssza újra, míg az 5xx hibákat egyáltalán nem tárolja, így a szerverhiba utáni újrapróbálkozás nem újrajátssza, hanem újra végrehajtja a műveletet. A kulcsok ráadásul lejárnak, a Nordletben 24 óra után, ami korlátozza, hogy az újrajátszás mennyi ideig érhető el.

A Nordlet dokumentációja azt ígéri, hogy egy Idempotency-Key fejléc hozzáadása megakadályozza, hogy az újrapróbált kérés duplikációt hozzon létre, és az API-konvenciók meghatározzák a pontos újrajátszási fejlécet és a bájtra pontos válaszkövetelményt. Az elv megegyezik a Stripe közzétett modelljével: a kulcs azonosítja a logikai műveletet, az ismétlések a tárolt eredményt adják vissza, és a különböző paraméterekkel újra felhasznált kulcsot a rendszer a csendes módosítás helyett elutasítja.

Sikerességi feltétel. Pontosan egy pénzügyi státuszváltás létezik, függetlenül attól, hogy a kliens hányszor küldi el ugyanazt a kérést az újrajátszási ablakon belül.

Idempotencia: azonos kulcs, megváltozott törzs

Küldje el az eredeti kérést a K kulccsal és a B1 törzzsel, majd egy második kérést a K kulccsal és a B2 törzzsel, ahol legalább egy összeg, ügyfél, dátum vagy sor eltér.

Várható eredmény: a rendszer elutasítja a kérést a dokumentált kulcsújrafelhasználási hibával – a Nordlet a 422 idempotency_key_reuse választ adja –, az eredeti rekord változatlan marad, második rekord, sorszám vagy auditmódosítás nem jelenik meg, és a kliens nem „javítja ki” azzal, hogy új kulcsot generál. A B2 csendes elfogadása nem biztonságossá tenné az újrapróbálkozási kulcsokat.

Párhuzamos duplikált kérések

Indítson el két azonos kérést ugyanazzal a kulccsal pontosan egyszerre. A dokumentált viselkedéstől függően az egyik végrehajtódik, míg a másik folyamatban lévő ütközési választ kap – a Nordlet a 409 idempotency_in_progress választ adja –, vagy mindkettő végül ugyanazt az eredményt tapasztalja.

Győződjön meg arról, hogy a két hívás nem hozhat létre független pénzügyi hatásokat, legfeljebb egy bizonylatszámot osztanak ki, az átmeneti ütközést ugyanezzel a kulccsal próbálják újra, nem pedig újjal, a végső erőforrás teljes és olvasható, és az idempotencia-rekord nem marad véglegesen beragadva.

Hibaesemény. Az olyan újrapróbálkozási könyvtár, amely kísérletenként új UUID-t hoz létre, egy logikai műveletet több független írássá alakít, és teljesen meghiúsítja az idempotenciát.

Bizonytalan kimenet megszakadt kapcsolat után

Ez a legfontosabb éles szimuláció. Küldjön egy módosítást a K kulccsal, hagyja, hogy a szerver véglegesítse, szakítsa meg a kapcsolatot a válasz megérkezése előtt, rögzítse az eredményt ismeretlenként, majd próbálja újra a K kulccsal, és egyeztesse az állapotot az erőforrás és az audit adatok beolvasásával.

Győződjön meg arról, hogy az újrapróbálkozás az eredeti vagy a dokumentált újrajátszási választ adja vissza, pontosan egy pénzügyi mellékhatás létezik, a kliens csak a sikeres újrajátszás vagy egyeztető olvasás után jelöli készre a műveletet, és nem generál új kulcsot. Az időtúllúpés (timeout) nem azt jelenti, hogy „semmi sem történt”. A Stripe az idempotenciát pontosan úgy határozza meg, mint védelmet a kapcsolati hibák ellen, amelyek során a szerver feldolgozhatta a módosítást, mielőtt a kliens megkaphatta volna a választ.

Konzervatív újrapróbálkozási politika

Az újrapróbálkozási döntések mind a hibától, mind attól függenek, hogy a művelet idempotens-e, nem pedig önmagában a HTTP-metódustól.

Általában újrapróbálható, az eredeti kulcs megtartásával: kapcsolat megszakadása vagy időtúllépés egy idempotens módosítás után, 408, 429 a retry-after betartása után, valamint 502/503/504. A dokumentált folyamatban lévő idempotencia-válasz rövid késleltetés után újrapróbálható.

Egyeztetés nélkül nem újrapróbálható: 400/422 validációs hibák, 401/403 hitelesítési hibák, 404 hiányzó erőforrás esetén, a folyamatban lévő kulcshoz nem kapcsolódó üzleti 409 ütközések, módosított payload egy létező kulcson, valamint a lezárt időszaki elutasítás.

Határolt exponenciális visszalépést alkalmazzon jitterrel, explicit maximális kísérletszámmal és eltelt idővel, tartsa be a retry-after értéket a sebességkorlátokhoz, tartsa meg ugyanazt a kulcsot egy művelet újrapróbálásakor, használjon új kulcsot minden új művelethez, és különítse el a naplókban az eredeti kísérletet az újrapróbálásoktól.

Tesztelje a sebességkorlátozást (rate limiting) külön is. Lépje át a dokumentált küszöbértéket – a Nordlet alapértelmezés szerint percenként 300 kérést engedélyez API-kulcsonként, és egyes hitelesítés nélküli végpontok saját alacsonyabb címenkénti korlátokkal rendelkeznek –, majd erősítse meg, hogy a szerver sebességkorlátozási választ ad vissza, a kliens késleltetésként és nem hibaként dolgozza fel a retry-after értéket, ahelyett, hogy árasztaná a szervert, várakozik, és egy korlátozott módosítás újrapróbálásakor az eredeti kulcsot használja fel. Az x-ratelimit-* fejrészek jelzik a fennmaradó keretet, ami kiváló előzetes ellenőrzést biztosít. A sebességkorlátozási teszteket tartsa távol a pénzügyi ellenőrzésektől, kivéve, ha a fixture képes megkülönböztetni a korlátozott kísérletet a véglegesítetttől.

Webhook-aláírás ellenőrzése

Hozzon létre egy olyan fogadót, amely megőrzi a nyers bájtokat. Minden egyes eseménynél: rögzítse a nyers törzset, olvassa be az x-nordlet-signature fejlécet, számítsa ki a várt HMAC-SHA256-ot a titkos előfizetési kulccsal (secret), hajtson végre időzítésbiztos (constant-time) összehasonlítást, csak az ellenőrzés után elemezze a JSON-t, rögzítse a kézbesítést, és az adattartó elfogadás után adjon vissza egy gyors 2xx választ. A Nordlet HMAC-aláírást készít a nyers törzsön, sha256=<hex> formátumban küldi el, és exponenciális visszalépéssel próbálja meg újra a kézbesítést. A Stripe webhook-útmutatója megerősíti a módosítatlan nyers törzs ellenőrzését időzítésbiztos összehasonlítással.

Futtasson negatív teszteket: helyes törzs és titok, helyes törzs rossz titokkal, egybájtos törzsváltozás, újra szerializált JSON megváltozott szóközökkel, hiányzó fejléc, hibás formátumú aláírás, régóta rejtőző újrajátszott kézbesítés, ha a séma tartalmaz időbélyeget, valamint rossz előfizetésre kézbesített érvényes aláírás.

Sikerességi feltételek. A rendszer csak a helyes nyers törzset és titkot fogadja el. Az érvénytelen aláírások nem 2xx választ kapnak. Az érvénytelen payloadok soha nem kerülnek be a könyvelési sorba. A titkos kulcsok nem kerülnek bele a szokásos naplókba. A kezelő csak az esemény tartós rögzítése után küld vissza nyugtázást.

Duplikált és sorrenden kívüli webhookok

A kézbesítés megbízhatósága különálló probléma az API idempotenciájától, és a fogadónak is idempotensnek kell lennie. Kézbesítse ugyanazt az eseményt kétszer, kézbesítsen egy sale_invoice.paid eseményt a sale_invoice.issued esemény előtt, adjon vissza egy 500-as hibát a perzisztálás után, de még a válaszadás előtt, és játsszon újra egy olyan eseményt, amelyet a fogyasztó már feldolgozott.

Győződjön meg arról, hogy a duplikált kézbesítések nem duplázzák meg a kifizetéseket, a státuszváltozásokat vagy a főkönyvi műveleteket, hogy a deduplikációs kulcs a szolgáltató kézbesítési vagy eseményazonosítóját használja, ha létezik ilyen (vagy egy dokumentált összetett kulcsot, soha nem tetszőleges időbélyeget), hogy a sorrenden kívüli események soha nem írják felül a régebbi állapottal az újabbat, hogy a fogyasztó le tudja kérni az aktuális állapotot az API-ból, ha a sorrend nem elegendő, és hogy a sikertelen fogyasztói kísérletek egy üzenetsoron vagy halottüzenet-útvonalon (dead-letter path) keresztül futnak. A Stripe kifejezetten arra figyelmeztet, hogy a kézbesítési sorrend nem garantált, és a feldolgozott eseményazonosítók tárolását javasolja.

Tartsa a végpontot egyszerűen: érvényesítse az alakot, ellenőrizze az aláírást, mentse vagy tegye sorba, nyugtázza, és adjon vissza 2xx választ. Az egyeztetés és az értesítések az aszinkron feldolgozáshoz tartoznak. Tesztelje úgy, hogy az alsóbb rétegbeli munkát a kézbesítési időtúllépésen túlra várakoztatja; a helyes fogadó a tartós sorba állítás után továbbra is nyugtázza a kérést.

Nyitott és lezárt könyvelési időszakok

A Nordlet a könyvelési időszakok lezárását a könyvelés pillanatában kényszeríti ki a kézi naplók, a bizonylatfolyamatok és az importálások során, ezért ezt az ellenőrzést egynél több helyen tesztelje. Hozzon létre egyenértékű bizonylatokat nyitott időszakra, lezárt időszakra, közvetlenül a lezárás előtti határra, a következő nyitott időszak első napjára datálva, valamint érvényes bizonylatdátummal, de érvénytelen könyvelési dátummal, ha az API különválasztja a kettőt.

Lezárt időszaki esetben győződjön meg arról, hogy a kérést elutasítják a dokumentált időszaklezárási hibával – a Nordletben ez egy 409 conflict –, és nem íródnak főkönyvi sorok, nem fogy el bizonylatszám, egyetlen bizonylat sem vált át könyvelt állapotra, és nem fut le a sikeres webhook sem. A nyitott időszaki verziónak meg kell felelnie ugyanezekkel a pénzügyi értékekkel.

Versenytárs-teszt (race test). Indítson el egy könyvelést egy nyitott időszakra, zárja le az időszakot a kérés közepén, és győződjön meg arról, hogy a véglegesítés nem tudja megkerülni a lezárást. A kritikus sikerességi feltétel: a véglegesített könyvelés soha nem kerülhet olyan időszakba, amely a tranzakció lezárása előtt le volt zárva.

Auditálhatóság és egyeztetés

Minden sikeres módosítás esetén győződjön meg arról, hogy a az üzleti objektum létezik, a számviteli tétel létezik a tartozik és követel egyenlőségével, az auditbejegyzés létezik, a webhook esemény létezik vagy lekérhető, és a műveleti rekordja a szolgáltatói objektumazonosítóra mutat, miközben az újrapróbálkozások ugyanarra a logikai műveletre hivatkoznak.

Minden elutasított módosítás esetén győződjön meg arról, hogy nincs részleges bizonylat, nem fogyott el sorszám (hacsak a szerződés nem engedi meg a lefoglalást), nincs főkönyvi tétel, nincs sikeres webhook, és a hiba hivatkozási kérérazonosítót (request ID) hordoz a diagnosztikához. A Nordlet konvenciói a módosítások auditálhatóságát és az egyensúlyban lévő könyveléseket platformgaranciaként írják le, ahol az egyensúlyt a véglegesítés pillanatában egy halasztott adatbázis-trigger kényszeríti ki, nem csupán az alkalmazáskód. Alakítsa át ezeket a garanciákat teszt utáni egyeztetési lekérdezésekké ahelyett, hogy megbízna a HTTP-válaszban.

Alapvető tesztmátrix

Terület	Tesztművelet	Várható ellenőrzés	Sikerességi feltétel
Hitelesítés	Nincs kulcs, érvénytelen kulcs, elégtelen hatókör	Strukturált 401/403; nincs mellékhatás	Egyetlen elutasított kísérlet sem hoz létre könyvelési rekordot
Séma és pénzösszegek	Érvénytelen tizedesjegy, dátum, hiányzó kötelező mező	Mezõszintű validációs hiba	Nincs újrapróbálkozás vagy részleges írás
Normál könyvelés	Számla létrehozása és kibocsátása nyitott időszakban	Egy bizonylat, egy egyensúlyban lévő főkönyv, egy auditbejegyzés	Az olvasott állapot és a főkönyv megegyezik
Azonos kulcsú újrajátszás	Azonos módosítás megismétlése, azonos kulcs és törzs	Eredeti eredmény újrajátszása; nincs duplikáció	Az objektumazonosító, a szám, a főkönyvi hatás és az audit egyedi marad
Megváltozott törzs, azonos kulcs	Kulcs újrahasznosítása eltérő összeggel	Dokumentált kulcsújrafelhasználási elutasítás	Az eredeti rekord változatlan; semmit sem írtak újat
Megszakadt kapcsolat	Véglegesítés, kapcsolat megszakítása, újrapróbálkozás azonos kulccsal	Újrajátszott eredmény	Pontosan egy pénzügyi mellékhatás létezik
Lezárt időszak	Bizonylat könyvelése lezárt időszaki dátummal	Időszaklezárási elutasítás	Nincs főkönyv, nincs sorszám, nincs sikeres webhook
Webhook-aláírás	Rossz titok, módosított törzs	Nem 2xx válasz a fogadótól	Csak a helyes nyers törzs és titok elfogadva

Mit tennék először?

Ha sedikit az idő, a teszteket abban a sorrendben futtassa, amely a legtöbb drága hibát szűri ki. Kezdje a megszakadt kapcsolat utáni újrapróbálkozással, mivel ez az egyetlen forgatókönyv hozza létre a legtöbb valós duplikációt. Ezt követően az azonos kulcsú és megváltozott törzsű idempotencia-párt. Majd a lezárt időszakokat, mivel egy lezárt hónapba történő könyvelés olyan auditprobléma, amely későn felszínre. Az aláírás-ellenőrzés és a sorrenden kívüli webhookok következnek ezután, a teljes séma és jogosultsági mátrix pedig folyamatosan futtatható a CI-ban, amint a kliens stabilizálódik.

A tervben szereplő minden más ezt az ötöt támogatja. Hozza őket zöld állapotba egy tesztcég ellen, az egyeztető olvasásokkal megerősítve a mellékhatásokat, és tudni fogja, hogy az integráció biztonságos, mielőtt az egyetlen éles főkönyvhöz érne. Létrehozhat egy tesztcéget és egy hatókörhöz kötött tesztkulcsot néhány perc alatt az Első lépések oldalon, és ellenőrizheti a szükséges modulokat a funkciók listájában.

FAQ

Elég egy 2xx válasz annak megerősítéséhez, hogy egy könyvelési írás sikeres volt?

Nem. A státuszkód azt igazolja, hogy a szerver válaszolt, nem azt, hogy pontosan egy bizonylat, egy sorszámkiosztás és egy egyensúlyban lévő főkönyvi tétel létezik. Minden egyes módosítási tesztnek követnie kell a választ az objektum, a számviteli hatás és az auditbejegyzés visszolvasásával. A veszélyes eset az ellenkező irányú: egy olyan művelet, amely lefutott, miközben a kliens egyáltalán nem kapta meg a választ.

Generálnom kell új idempotencia-kulcsot, ha egy kérés időtúllépést szenved?

Nem, és ez az a hiba, amely a legtöbb éles duplikációt okozza. A kulcs a logikai üzleti műveletet azonosítja, nem a hálózati kísérletet. Próbálja újra ugyanazzal a kulccsal, majd egyeztesse az erőforrás beolvasásával. Az olyan újrapróbálkozási könyvtár, amely kísérletenként új UUID-t hoz létre, egy szánt számlából több független írást csinál.

Mi történik, ha újrahasznosítok egy idempotencia-kulcsot egy eltérő payloaddal?

A helyes API elutasítja azt ahelyett, hogy csendesen alkalmazná az új törzset. A Nordlet a 422 idempotency_key_reuse választ adja, és változatlanul hagyja az eredeti rekordot. A kliensnek ezt programozási hibaként kell kezelnie, amit ki kell javítani, nem pedig új kulcs generálásával áthidalandó állapotként.

A webhookok helyettesítik a létrehozott objektum visszolvasását?

Nem. A webhook kézbesítése az alsóbb rétegek értesítését bizonyítja, nem pedig azt, hogy a tranzakció a várt módon véglegesült, és a kézbesítési sorrend sem garantált. Ellenőrizze az aláírást a nyers törzsön, deduplikáljon a kézbesítési vagy eseményazonosító alapján, és kérje le az aktuális állapotot az API-ból, amikor az események sorrendje önmagában nem elegendő annak eldöntéséhez, hogy mi változott.

Hogyan tesztelhetem a könyvelést egy lezárt könyvelési időszakba?

Hozzon létre egyenértékű bizonylatokat egy nyitott és egy lezárt időszakban, és győződjön meg arról, hogy a lezárt esetet elutasítják főkönyvi sorok,felhasznált bizonylatszám, státuszváltás és sikeres webhook nélkül. Ezután futtassa a versenyhelyzetes verziót: indítson el egy könyvelést egy nyitott időszakra, és zárja le az időszakot a kérés közepén. A véglegesített könyvelés soha nem landolhat olyan időszakban, amely a tranzakció véglegesítése előtt le volt zárva.

Futtathatok nagy volumensű duplikációs teszteket egy tesztcégben?

Igen. Egy tesztcég úgy viselkedik, mint egy valódi, tesztadatként van megjelölve, és a megőrzési ablak helyett azonnal törlődik, így ez a megfelelő hely a romboló és duplikációs tesztekhez. A tesztkörnyezet használata ettől függetlenül mérésre és számlázásra kerül, mint a valós használat, ezért tervezze meg a mennyiséget a végtelen ciklusok helyett.