API testy

Testovanie integrácií medzi e-shopom, skladom a účtovníctvom

Objednávka môže v e-shope svietiť ako zaplatená, hoci sklad ju neprijal a účtovníctvo o nej nevie. Každý systém pritom odpovedal úspešne na svoje API volanie. Testovanie tejto integrácie preto nekončí pri HTTP 200: musí preukázať, že jedna obchodná udalosť vytvorila správne a navzájom zlučiteľné výsledky vo všetkých zapojených systémoch, a že sa tok vie zotaviť z oneskorenia, duplicity či čiastočného výpadku.

Jedna objednávka nie je jedna technická transakcia

V monolite môže vytvorenie objednávky vyzerať ako jeden zápis do databázy. V prepojenom e-shope ide skôr o sériu krokov, ktoré sa dokončia v rôznom čase:

1. E-shop prijme objednávku. Pridelí jej interné ID a uloží položky, množstvá, ceny, menu, zľavy, daňové údaje a zvolenú dopravu.
2. Sklad rezervuje zásobu. Skladový alebo podnikový informačný systém (ERP) priradí vlastné ID, potvrdí dostupné množstvo, prípadne objednávku rozdelí alebo odmietne.
3. Platobná služba potvrdí výsledok. Okamžitá odpoveď po presmerovaní zákazníka nemusí byť konečný dôkaz; rozhodujúca serverová udalosť môže prísť neskôr.
4. Sklad expeduje tovar. Vznikne výdaj, zásielka, sledovacie číslo a jedna alebo viac udalostí o odoslaní.
5. Účtovníctvo vytvorí doklad. Faktúra, storno, opravný doklad alebo dobropis musí zodpovedať skutočnému obchodnému výsledku a používaným účtovným pravidlám.

Presné poradie sa medzi firmami líši. Niekde sa platba zachytí pred rezerváciou, inde až pri expedícii; faktúra môže vzniknúť po platbe alebo odoslaní. Test nesmie presadzovať všeobecnú schému proti reálnemu procesu. Tím si musí schválený tok nakresliť vrátane vlastníka každého stavu a potom overovať práve tento kontrakt.

Najprv rozlíšte spôsob komunikácie

Synchrónne API vráti odpoveď počas jedného volania. Stav 200 môže podľa kontraktu znamenať dokončenú operáciu, iba prijatý príkaz alebo technicky úspešnú odpoveď s obchodným odmietnutím v tele. Test preto kontroluje stavový kód, telo aj následný stav zdroja, nie iba zelenú požiadavku v nástroji.

Asynchrónne správy a webhooky oddeľujú prijatie od spracovania. Správa môže čakať vo fronte, prísť opakovane alebo v inom poradí, ak to konkrétny kontrakt pripúšťa. Test čaká s pevným časovým limitom na pozorovateľný obchodný výsledok a ukladá medzistavy na diagnostiku. Náhodná pauza na desať sekúnd iba maskuje rozdiely v rýchlosti.

Dávkové súbory a plánované synchronizácie pridávajú okno spracovania, súborové formáty, pomenovanie, kontrolné súčty a pravidlá opätovného importu. Pri nočnom exporte faktúr treba overiť hranicu dňa, časové pásmo, prázdnu dávku, čiastočne chybný súbor aj bezpečné zopakovanie tej istej dávky.

Jeden tok môže používať všetky tri mechanizmy: e-shop rezervuje tovar cez API, platbu prijme webhookom a faktúry odošle účtovníctvu v nočnej dávke. Scenár sa považuje za dokončený až podľa obchodnej definície, nie podľa prvého úspešného transportu.

Vytvorte mapu dát a kontraktov

Pre každú hranicu spíšte, ktoré polia sa prenášajú, kto je ich zdrojom pravdy a ako sa mapujú. Minimum pre objednávkový tok zvyčajne zahŕňa:

• interné a externé ID objednávky, platby, rezervácie, zásielky a dokladu;
• SKU (identifikátor skladovej položky) alebo iný identifikátor variantu, množstvo a mernú jednotku;
• jednotkovú a celkovú cenu, zľavu, dopravu, menu, sadzbu dane a zaokrúhlenie;
• stav a povolené prechody, čas udalosti, čas prijatia a časové pásmo;
• identitu zákazníka a adresy iba v rozsahu potrebnom pre cieľový systém;
• verziu správy alebo schémy a pravidlo pre neznáme pole či hodnotu.

Nejasnosť typu „číslo objednávky“ často vytvorí drahú chybu. E-shop môže používať dlhý nemenný technický identifikátor, zákazník vidí krátke poradové číslo a účtovníctvo má vlastný rad dokladov. Ak sklad vráti iba jedno z nich, reklamáciu nemožno bezpečne spojiť so zdrojovým záznamom.

Kontrakt má pokrývať aj význam, nielen dátový typ. Pole total bez definície meny, dane, zľavy a pravidla zaokrúhlenia je technicky platné, no obchodne nejednoznačné. Automatizované kontraktné testovanie dokáže upozorniť na zmenu pokrytého formátu alebo očakávania, ale nenahrádza end-to-end kontrolu výpočtu a výsledných dokladov.

Idempotencia a deduplikácia chránia pred dvojitým účinkom

Idempotentné spracovanie znamená, že bezpečné zopakovanie toho istého obchodného príkazu nevytvorí druhú rezerváciu, platbu ani faktúru. Odosielateľ priradí operácii stabilný kľúč a použije ho pri všetkých jej pokusoch; príjemca si pod ním uloží výsledok alebo vynúti jedinečnosť v databáze. Súbežné kópie musia naraziť na rovnakú ochranu; kontrola „najprv vyhľadaj, potom vlož“ bez atómovej podmienky môže pri pretekoch zlyhať.

Deduplikácia prichádzajúcich udalostí spravidla používa ID udalosti od poskytovateľa a evidenciu stavu spracovania. Dve rôzne udalosti pre jednu objednávku však nie sú duplicitou len preto, že nesú rovnaké ID objednávky. Čiastočná refundácia 10 eur a neskoršia refundácia ďalších 5 eur sú samostatné obchodné operácie.

Konkrétne API má vlastný kontrakt. Napríklad Stripe opisuje idempotency key pre bezpečné opakovanie podporovaných požiadaviek a v dokumentácii webhookov upozorňuje na možné opakované doručenie a negarantované poradie udalostí. Tieto vlastnosti netreba automaticky pripísať každému poskytovateľovi; testy odvoďte z jeho dokumentácie a zo svojej implementácie. Praktické scenáre rozširuje článok ako testovať webhooky.

Poradie, oneskorenie a prechod obchodného stavu

Ak môže udalosť o expedícii prísť pred oneskoreným potvrdením rezervácie, systém nesmie vrátiť objednávku zo stavu „odoslaná“ späť na „rezervovaná“. Ochranu môže tvoriť stavový automat, verzia agregátu, poradové číslo udalosti alebo overenie aktuálneho stavu u zdroja. Čas prijatia správy nie je spoľahlivou náhradou obchodného poradia.

Testujte aj hranice: platba potvrdená po vypršaní rezervácie, storno prijaté počas balenia, refundácia pred potvrdením predchádzajúceho kroku a udalosť staršej verzie schémy. Pri každom variante určte, či sa má správa odmietnuť, odložiť, spracovať bez zmeny alebo spustiť kompenzačný krok. „Ignorovať“ bez evidencie vytvára nevysvetliteľné rozdiely medzi systémami.

Retry, dead-letter front a zosúladenie stavu

Dočasná chyba, napríklad timeout, môže viesť k obmedzenému opakovaniu s rozostupmi. Trvalá chyba, napríklad neznáme SKU alebo neplatná mena, sa opakovaním sama neopraví. Integrácia by mala tieto kategórie rozlíšiť, zaznamenať počet pokusov a po vyčerpaní limitu presunúť správu do dead-letter frontu alebo iného riadeného chybového stavu.

Dead-letter front nie je archív, na ktorý sa zabudne. Potrebuje upozornenie, vlastníka, diagnostiku, bezpečný spôsob opätovného spracovania a pravidlo, čo sa stane s medzičasom zmenenou objednávkou. Opätovné prehranie musí prejsť rovnakou idempotentnou ochranou ako prvý pokus.

Zosúladenie, často označované ako reconciliation, pravidelne porovnáva zdroje pravdy. Môže nájsť platbu bez objednávky, expedovanú zásielku bez faktúry alebo rezerváciu, ktorá po zrušení zostala visieť. Test má dočasne vynechať udalosť, spustiť zosúladenie a preukázať, či systém rozdiel automaticky opraví, označí na manuálne rozhodnutie alebo vytvorí bezpečný kompenzačný krok.

Čiastočné zlyhanie potrebuje pomenovaný stav

Najrizikovejší moment nastane, keď jeden systém operáciu dokončí a ďalší nie. Platobná brána autorizuje sumu, ale sklad pri rezervácii timeoutuje. Ak e-shop označí objednávku za neúspešnú a bez kontroly zopakuje platbu, môže zákazníka zaťažiť dvakrát. Ak ju označí za úspešnú, môže predať nedostupný tovar.

Proces preto potrebuje medzistav, napríklad „platba potvrdená, rezervácia čaká“, vlastníka ďalšieho rozhodnutia a povolenú kompenzáciu. Tou môže byť opätovné overenie skladu, uvoľnenie autorizácie, refundácia alebo manuálne spracovanie. Nie každú distribuovanú operáciu možno vrátiť späť ako databázovú transakciu; testuje sa dosiahnutie konzistentného obchodného výsledku a dohľadateľnosť zostávajúcej výnimky.

Skladové množstvá, ceny, DPH a meny

Pri sklade nestačí skontrolovať, že sa množstvo znížilo. Dve súbežné objednávky posledného kusu musia mať podľa pravidla najviac jednu úspešnú rezerváciu. Testujte rezerváciu, jej expiráciu, čiastočnú dostupnosť, rozdelenú expedíciu, náhradu položky, storno a príjem vráteného tovaru. Rozlíšte fyzický stav, dostupné množstvo a rezervované množstvo; nemusia sa meniť v rovnakom okamihu.

Peňažné hodnoty porovnávajte v presne definovanej mene a presnosti. Uložte cenový a daňový snapshot prijatej objednávky, aby neskoršia zmena cenníka neprepísala historický doklad. Zmluva musí povedať, či sa zaokrúhľuje položka alebo celková suma, kto určuje kurz a ako sa rozdelí zľava pri čiastočnom vrátení. Scenáre DPH, dátum vzniku dokladu a typ opravného dokladu musí pre konkrétnu krajinu a proces potvrdiť účtovný alebo daňový odborník; technický test právnu správnosť neurčuje.

Testovacie dáta a prostredie musia pokryť celý tok

Pripravte malý katalóg zámerných prípadov: SKU s jedným kusom, vypredanú položku, kombináciu dostupných a nedostupných položiek, produkt s konkrétnym daňovým profilom, objednávku v podporovanej cudzej mene a zákazníka s bezpečnou testovacou adresou. Každý beh používa vlastné ID a pozná východiskový stav skladu, platobného sandboxu aj testovacej účtovnej jednotky.

Mocky sú vhodné na timeouty a poškodené odpovede, sandboxy na skutočný formát a autentifikáciu a spoločné integračné prostredie na overenie toku medzi reálnymi komponentmi. Malý počet kontrol v produkcii môže potvrdiť živú konfiguráciu, ale potrebuje označené účty, obmedzené vedľajšie účinky a dohodnuté upratanie. Ako vrstvy rozdeliť, vysvetľuje prehľad testovacích prostredí a hranice platobnej časti rozoberá testovanie platobnej brány.

Korelačné ID prepojí dôkazy od objednávky po doklad

Jedno korelačné ID prenášajte cez synchrónne volania, správy a dávkové záznamy. Popri ňom evidujte ID konkrétnej správy, pôvodnú udalosť a číslo pokusu. Tím potom dokáže zrekonštruovať, že požiadavka vytvorila objednávku, tá vyvolala rezerváciu a po platbe vznikla expedícia aj faktúra.

Logy nemajú automaticky obsahovať celé adresy, platobné údaje ani telá správ. Pre diagnostiku často stačia technické identifikátory, stav, verzia kontraktu, čas a dôvod odmietnutia. Korelácia je dôkazom priebehu, nie dôvodom kopírovať osobné údaje do každého systému.

Scenárová matica, ktorá overí viac než šťastnú cestu

Maticu doplňte o konkrétne hodnoty a povolené časové limity. „Objednávka sa synchronizovala“ nie je očakávanie; „do dvoch minút vznikla jedna rezervácia na SKU A, platba P zostala jedna a doklad obsahuje odsúhlasenú sumu“ sa dá overiť.

Dôkazy pripravenosti na release

Rýchle kontraktné a komponentové testy majú pokrývať mapovanie, validáciu a chybové vetvy každej hranice. Integračné testy preveria databázu, front, retry a sandbox. Menší počet end-to-end scenárov potvrdí najdôležitejšie obchodné toky naprieč skutočnými komponentmi. Zlyhania treba vyvolať zámerne; čakanie na náhodný výpadok nie je testovacia stratégia.

Podklad pre release obsahuje verzie aplikácií a schém, konfiguráciu prostredia, použitý dátový balík, výsledky scenárovej matice a korelačné ID. Pri asynchrónnom toku zahŕňa medzistavy, počet pokusov, dead-letter front a výsledok zosúladenia. Pri peniazoch a sklade obsahuje konkrétny výpočet, zostatok a vzorku výsledného dokladu. Zároveň pomenuje nevykonané scenáre, rozdiely od produkcie a vlastníka zostávajúceho rizika.

HTTP 200 je v tomto balíku iba jeden dôkaz o jednej hranici. Pripravenosť znamená, že tím vie preukázať konečný obchodný výsledok, absenciu dvojitých účinkov a fungujúcu cestu obnovy pri pokrytých zlyhaniach.

Čo tým získate

Takto navrhnuté testy odhalia rozdiely skôr, než sa premenia na ručné dohľadávanie objednávok, záporný sklad, dvojité zaúčtovanie alebo faktúry bez zásielky. Korelačná stopa skracuje diagnostiku a scenárová matica dáva prevádzke, vývoju aj účtovníctvu spoločný obraz o tom, čo release skutočne preukázal a čo zostáva otvorené.

Ďalší krok

Vyberte jeden reálny typ objednávky a počas 90-minútového auditu nakreslite jeho udalosti od prijatia po faktúru alebo dobropis. Ku každému kroku doplňte zdroj pravdy, ID, kontrakt, povolený čas, retry, kompenzáciu a dôkaz konečného výsledku. Potom z matice spustite tri scenáre: štandardný tok, duplicitné doručenie a čiastočné zlyhanie po platbe. Všetky tri musíte vedieť zrekonštruovať jedným korelačným ID bez ručného porovnávania neoznačených záznamov.