API testy

Testování integrací mezi e-shopem, skladem a účetnictvím

Objednávka může v e-shopu svítit jako zaplacená, i když ji sklad nepřijal a účetnictví o ní neví. Každý systém přitom úspěšně odpověděl na své API volání. Testování této integrace proto nekončí u HTTP 200: musí prokázat, že jedna obchodní událost vytvořila správné a navzájem slučitelné výsledky ve všech zapojených systémech a že se tok dokáže zotavit ze zpoždění, duplicity či částečného výpadku.

Jedna objednávka není jedna technická transakce

V monolitu může vytvoření objednávky vypadat jako jeden zápis do databáze. V propojeném e-shopu jde spíše o sérii kroků, které se dokončí v různou dobu:

1. E-shop přijme objednávku. Přidělí jí interní ID a uloží položky, množství, ceny, měnu, slevy, daňové údaje a zvolenou dopravu.
2. Sklad rezervuje zásobu. Skladový nebo podnikový informační systém (ERP) přidělí vlastní ID, potvrdí dostupné množství, případně objednávku rozdělí nebo odmítne.
3. Platební služba potvrdí výsledek. Okamžitá odpověď po přesměrování zákazníka nemusí být konečným důkazem; rozhodující serverová událost může přijít později.
4. Sklad expeduje zboží. Vznikne výdej, zásilka, sledovací číslo a jedna nebo více událostí o odeslání.
5. Účetnictví vytvoří doklad. Faktura, storno, opravný doklad nebo dobropis musí odpovídat skutečnému obchodnímu výsledku a používaným účetním pravidlům.

Přesné pořadí se mezi firmami liší. Někde se platba zachytí před rezervací, jinde až při expedici; faktura může vzniknout po platbě nebo odeslání. Test nesmí prosazovat obecné schéma proti skutečnému procesu. Tým si musí schválený tok nakreslit včetně vlastníka každého stavu a poté ověřovat právě tento kontrakt.

Nejprve rozlište způsob komunikace

Synchronní API vrátí odpověď během jednoho volání. Stav 200 může podle kontraktu znamenat dokončenou operaci, pouze přijatý příkaz nebo technicky úspěšnou odpověď s obchodním odmítnutím v těle. Test proto kontroluje stavový kód, tělo i následný stav zdroje, ne jen zelený požadavek v nástroji.

Asynchronní zprávy a webhooky oddělují přijetí od zpracování. Zpráva může čekat ve frontě, přijít opakovaně nebo v jiném pořadí, pokud to konkrétní kontrakt připouští. Test čeká s pevným časovým limitem na pozorovatelný obchodní výsledek a ukládá mezistavy pro diagnostiku. Náhodná pauza na deset sekund pouze maskuje rozdíly v rychlosti.

Dávkové soubory a plánované synchronizace přidávají okno zpracování, souborové formáty, pojmenování, kontrolní součty a pravidla opětovného importu. U nočního exportu faktur je třeba ověřit hranici dne, časové pásmo, prázdnou dávku, částečně chybný soubor i bezpečné zopakování stejné dávky.

Jeden tok může používat všechny tři mechanismy: e-shop rezervuje zboží přes API, platbu přijme webhookem a faktury odešle do účetnictví v noční dávce. Scénář se považuje za dokončený až podle obchodní definice, ne podle prvního úspěšného přenosu.

Vytvořte mapu dat a kontraktů

Pro každou hranici sepište, která pole se přenášejí, kdo je jejich zdrojem pravdy a jak se mapují. Minimum pro objednávkový tok obvykle zahrnuje:

• interní a externí ID objednávky, platby, rezervace, zásilky a dokladu;
• SKU (identifikátor skladové položky) nebo jiný identifikátor varianty, množství a měrnou jednotku;
• jednotkovou a celkovou cenu, slevu, dopravu, měnu, sazbu daně a zaokrouhlení;
• stav a povolené přechody, čas události, čas přijetí a časové pásmo;
• identitu zákazníka a adresy pouze v rozsahu potřebném pro cílový systém;
• verzi zprávy nebo schématu a pravidlo pro neznámé pole či hodnotu.

Nejasnost typu „číslo objednávky“ často vytvoří drahou chybu. E-shop může používat dlouhý neměnný technický identifikátor, zákazník vidí krátké pořadové číslo a účetnictví má vlastní řadu dokladů. Pokud sklad vrátí pouze jedno z nich, reklamaci nelze bezpečně spojit se zdrojovým záznamem.

Kontrakt má pokrývat také význam, nejen datový typ. Pole total bez definice měny, daně, slevy a pravidla zaokrouhlení je technicky platné, ale obchodně nejednoznačné. Automatizované kontraktní testování dokáže upozornit na změnu pokrytého formátu nebo očekávání, ale nenahrazuje end-to-end kontrolu výpočtu a výsledných dokladů.

Idempotence a deduplikace chrání před dvojím účinkem

Idempotentní zpracování znamená, že bezpečné zopakování stejného obchodního příkazu nevytvoří druhou rezervaci, platbu ani fakturu. Odesílatel přiřadí operaci stabilní klíč a použije ho při všech jejích pokusech; příjemce pod ním uloží výsledek nebo vynutí jedinečnost v databázi. Souběžné kopie musí narazit na stejnou ochranu; kontrola „nejprve vyhledej, potom vlož“ bez atomické podmínky může při souběhu selhat.

Deduplikace příchozích událostí zpravidla používá ID události od poskytovatele a evidenci stavu zpracování. Dvě různé události pro jednu objednávku však nejsou duplicitou jen proto, že nesou stejné ID objednávky. Částečná refundace 10 eur a pozdější refundace dalších 5 eur jsou samostatné obchodní operace.

Konkrétní API má vlastní kontrakt. Například Stripe popisuje idempotency key pro bezpečné opakování podporovaných požadavků a v dokumentaci webhooků upozorňuje na možné opakované doručení a negarantované pořadí událostí. Tyto vlastnosti nelze automaticky připsat každému poskytovateli; testy odvoďte z jeho dokumentace a ze své implementace. Praktické scénáře rozšiřuje článek jak testovat webhooky.

Pořadí, zpoždění a přechod obchodního stavu

Pokud může událost o expedici přijít před zpožděným potvrzením rezervace, systém nesmí vrátit objednávku ze stavu „odeslána“ zpět na „rezervována“. Ochranu může tvořit stavový automat, verze agregátu, pořadové číslo události nebo ověření aktuálního stavu u zdroje. Čas přijetí zprávy není spolehlivou náhradou obchodního pořadí.

Testujte také hranice: platbu potvrzenou po vypršení rezervace, storno přijaté během balení, refundaci před potvrzením předchozího kroku a událost starší verze schématu. U každé varianty určete, zda se má zpráva odmítnout, odložit, zpracovat beze změny nebo spustit kompenzační krok. „Ignorovat“ bez evidence vytváří nevysvětlitelné rozdíly mezi systémy.

Retry, dead-letter fronta a sladění stavu

Dočasná chyba, například timeout, může vést k omezenému opakování s rozestupy. Trvalá chyba, například neznámé SKU nebo neplatná měna, se opakováním sama neopraví. Integrace by měla tyto kategorie rozlišit, zaznamenat počet pokusů a po vyčerpání limitu přesunout zprávu do dead-letter fronty nebo jiného řízeného chybového stavu.

Dead-letter fronta není archiv, na který se zapomene. Potřebuje upozornění, vlastníka, diagnostiku, bezpečný způsob opětovného zpracování a pravidlo, co se stane s mezitím změněnou objednávkou. Opětovné přehrání musí projít stejnou idempotentní ochranou jako první pokus.

Sladění, často označované jako reconciliation, pravidelně porovnává zdroje pravdy. Může najít platbu bez objednávky, expedovanou zásilku bez faktury nebo rezervaci, která po zrušení zůstala viset. Test má dočasně vynechat událost, spustit sladění a prokázat, zda systém rozdíl automaticky opraví, označí k ručnímu rozhodnutí nebo vytvoří bezpečný kompenzační krok.

Částečné selhání potřebuje pojmenovaný stav

Nejrizikovější okamžik nastane, když jeden systém operaci dokončí a další ne. Platební brána autorizuje částku, ale sklad při rezervaci timeoutuje. Pokud e-shop označí objednávku za neúspěšnou a bez kontroly zopakuje platbu, může zákazníka zatížit dvakrát. Pokud ji označí za úspěšnou, může prodat nedostupné zboží.

Proces proto potřebuje mezistav, například „platba potvrzena, rezervace čeká“, vlastníka dalšího rozhodnutí a povolenou kompenzaci. Tou může být opětovné ověření skladu, uvolnění autorizace, refundace nebo ruční zpracování. Ne každou distribuovanou operaci lze vrátit zpět jako databázovou transakci; testuje se dosažení konzistentního obchodního výsledku a dohledatelnost zbývající výjimky.

Skladová množství, ceny, DPH a měny

U skladu nestačí zkontrolovat, že se množství snížilo. Dvě souběžné objednávky posledního kusu musí mít podle pravidla nejvýše jednu úspěšnou rezervaci. Testujte rezervaci, její expiraci, částečnou dostupnost, rozdělenou expedici, náhradu položky, storno a příjem vráceného zboží. Rozlište fyzický stav, dostupné množství a rezervované množství; nemusí se měnit ve stejný okamžik.

Peněžní hodnoty porovnávejte v přesně definované měně a přesnosti. Uložte cenový a daňový snapshot přijaté objednávky, aby pozdější změna ceníku nepřepsala historický doklad. Smlouva musí říct, zda se zaokrouhluje položka nebo celková částka, kdo určuje kurz a jak se rozdělí sleva při částečném vrácení. Scénáře DPH, datum vzniku dokladu a typ opravného dokladu musí pro konkrétní zemi a proces potvrdit účetní nebo daňový odborník; technický test právní správnost neurčuje.

Testovací data a prostředí musí pokrýt celý tok

Připravte malý katalog záměrných případů: SKU s jedním kusem, vyprodanou položku, kombinaci dostupných a nedostupných položek, produkt s konkrétním daňovým profilem, objednávku v podporované cizí měně a zákazníka s bezpečnou testovací adresou. Každý běh používá vlastní ID a zná výchozí stav skladu, platebního sandboxu i testovací účetní jednotky.

Mocky se hodí pro timeouty a poškozené odpovědi, sandboxy pro skutečný formát a autentizaci a společné integrační prostředí pro ověření toku mezi reálnými komponentami. Malý počet kontrol v produkci může potvrdit živou konfiguraci, ale potřebuje označené účty, omezené vedlejší účinky a dohodnutý úklid. Jak vrstvy rozdělit, vysvětluje přehled testovacích prostředí a hranice platební části rozebírá testování platební brány.

Korelační ID propojí důkazy od objednávky po doklad

Jedno korelační ID přenášejte přes synchronní volání, zprávy a dávkové záznamy. Vedle něj evidujte ID konkrétní zprávy, původní událost a číslo pokusu. Tým pak dokáže zrekonstruovat, že požadavek vytvořil objednávku, ta vyvolala rezervaci a po platbě vznikla expedice i faktura.

Logy nemají automaticky obsahovat celé adresy, platební údaje ani těla zpráv. Pro diagnostiku často stačí technické identifikátory, stav, verze kontraktu, čas a důvod odmítnutí. Korelace je důkazem průběhu, ne důvodem kopírovat osobní údaje do každého systému.

Scénářová matice, která ověří více než šťastnou cestu

Matici doplňte o konkrétní hodnoty a povolené časové limity. „Objednávka se synchronizovala“ není očekávání; „do dvou minut vznikla jedna rezervace na SKU A, platba P zůstala jedna a doklad obsahuje odsouhlasenou částku“ lze ověřit.

Důkazy připravenosti na release

Rychlé kontraktní a komponentové testy mají pokrývat mapování, validaci a chybové větve každé hranice. Integrační testy prověří databázi, frontu, retry a sandbox. Menší počet end-to-end scénářů potvrdí nejdůležitější obchodní toky napříč skutečnými komponentami. Selhání je třeba vyvolat záměrně; čekání na náhodný výpadek není testovací strategie.

Podklady pro release obsahují verze aplikací a schémat, konfiguraci prostředí, použitý datový balík, výsledky scénářové matice a korelační ID. U asynchronního toku zahrnují mezistavy, počet pokusů, dead-letter frontu a výsledek sladění. U peněz a skladu obsahují konkrétní výpočet, zůstatek a vzorek výsledného dokladu. Současně pojmenují neprovedené scénáře, rozdíly od produkce a vlastníka zbývajícího rizika.

HTTP 200 je v tomto balíku pouze jedním důkazem o jedné hranici. Připravenost znamená, že tým umí prokázat konečný obchodní výsledek, absenci dvojích účinků a funkční cestu obnovy u pokrytých selhání.

Co tím získáte

Takto navržené testy odhalí rozdíly dříve, než se promění v ruční dohledávání objednávek, záporný sklad, dvojí zaúčtování nebo faktury bez zásilky. Korelační stopa zkracuje diagnostiku a scénářová matice dává provozu, vývoji i účetnictví společný obraz o tom, co release skutečně prokázal a co zůstává otevřené.

Další krok

Vyberte jeden reálný typ objednávky a během 90minutového auditu nakreslete jeho události od přijetí po fakturu nebo dobropis. Ke každému kroku doplňte zdroj pravdy, ID, kontrakt, povolený čas, retry, kompenzaci a důkaz konečného výsledku. Poté z matice spusťte tři scénáře: standardní tok, duplicitní doručení a částečné selhání po platbě. Všechny tři musíte umět zrekonstruovat pomocí jednoho korelačního ID bez ručního porovnávání neoznačených záznamů.