Integrace odeslala objednávku do externího systému, ale nedostala odpověď. Automatické opakování vytvořilo druhou objednávku s novým číslem. Zákazníkovi může vzniknout dvojí zpracování a sklad rezervuje zboží navíc. Problém není jen v rychlosti sítě: jeden obchodní úkon nebyl rozpoznán při opakovaném přenosu. Je třeba stabilní identifikátor operace, evidence výsledku a možnost párování.
Idempotence objednávky není totéž jako unikátní SKU, aktualizační klíč při importu či prevence dvojkliku. Dvě síťová volání mohou patřit jedné operaci, zatímco dva samostatné nákupy stejné osoby mohou být legitimní.
Příčiny a rozsah diagnostiky
Nejprve zaznamenejte reprodukovatelný požadavek, výchozí stav a očekávaný výsledek. Oddělte chybu rozhraní, přenosu a obchodního pravidla. Ověřujte i stornování, neplatná oprávnění, opakování a výpadek externí služby.
- Každý nový pokus dostane nový klíč místo trvalého ID původní operace.
- Timeout se považuje za neúspěch, i když přijímající server objednávku již uložil.
- Webhook je doručen znovu a zpracovatel nekontroluje historii ID událostí.
- Externí systém vrátil ID objednávky, ale mezi odpovědí a místním uložením nastala chyba.
- Pracovník klikne na opakování a nevědomky spustí stejný úkon pod novým identifikátorem.
- Opakovaný požadavek obsahuje jiné produkty či částku, ale používá starý klíč bez kontroly parametrů.
Varianty řešení
Idempotentní klíč v podporovaném API
Ověřte, zda konkrétní metoda bezpečně rozpoznává opakovaná volání, jaký klíč vyžaduje a jak dlouho jej uchovává. Funkce jednoho endpointu automaticky neplatí pro celé API. Zapište verzi, oprávnění a postup po výpadku.
Vlastní evidence operací
Propojte ID místní objednávky, typ úkonu, kontrolní otisk parametrů, externí ID a stav zpracování. Při opakování nejprve vyhledejte původní výsledek. Paralelní pracovníci nesmějí provést jednu operaci dvakrát.
Fronta a ruční párování
Při nestabilní komunikaci použijte omezená opakování, rozlišení dočasných a trvalých chyb a záznam nejasných výsledků k ruční kontrole. Chybné obchodní údaje nelze napravit nekonečným opakováním.
Integrace se oceňují individuálně, pro Shopify, Shoptet a WooCommerce agentura využívá odborné partnery. Hotový doplněk nemusí vyřešit všechny výjimky.
Bezpečný postup implementace
- Přiřaďte každé logické obchodní operaci jedno trvalé ID bez ohledu na počet HTTP pokusů.
- Zaznamenejte původní obsah a otisk objednávky; změna zboží nebo částky nesmí nepozorovaně projít pod starým klíčem.
- Před odesláním uložte do evidence čekající operaci s vazbou na místní objednávku.
- Po úspěchu uložte externí ID atomicky nebo zajistěte ověřitelný postup jeho obnovy.
- Po timeoutu nejprve zjistěte výsledek podle klíče či hledání externí objednávky.
- Omezte opakování a rozlišujte přechodný výpadek sítě od trvalé chyby validace.
- Připravte přehled nejasných operací a řízenou možnost ruční nápravy.
Osm modelových testů
Následující scénáře jsou vymyšlené, nikoliv skutečné provozní záznamy či záruka fungování každého API. Výsledek se vždy musí ověřit na konkrétní metodě.
- Komunikace se přeruší ještě před odesláním: opakování se stejným klíčem má při podpoře API vytvořit právě jednu externí objednávku.
- Server objednávku uloží, ale odpověď se ztratí: opakování vrátí nebo najde původní výsledek místo další objednávky.
- Odpověď s externím ID přijde, místní uložení selže: před dalším vytvořením je nutné párování podle klíče.
- Dva pracovní procesy převezmou stejnou událost: atomická podmínka nebo unikátnost zabrání dvojímu zápisu.
- První požadavek obsahuje dvě položky, druhý jednu: jde o změněný obsah a musí se prošetřit.
- Externí API nepodporuje idempotenci: použije se vlastní mapa, kontrola existujícího výsledku a schválený způsob obnovy.
- Pracovník spustí opakování ručně: rozhraní ukáže dřívější externí číslo a aktuální log.
- Stejný webhook přijde za hodinu: zpracovatel pozná event ID a neprovede druhý skladový či finanční úkon.
Ke každému testu zaznamenejte vstupní ID, krok obsluhy, odpověď serveru, protokol, rozhodnutí a odpovědnou osobu. Původní důkaz chyby zachovejte před opakováním.
Kritéria přijetí
- Jedna logická operace vytváří jedinou externí objednávku při postupném i souběžném opakování.
- Po ztrátě odpovědi lze z logu získat obsah požadavku a externí ID.
- Změněný obsah pod původním klíčem vyvolá kontrolu, ne tiché přijetí.
- Neznámý výsledek přejde k párování místo bezhlavého založení nové objednávky.
- Opakované webhooky ani ruční pokusy netvoří další platby, doklady či skladové pohyby.
Otestujte i chybějící identifikátory, přerušení sítě, nesprávná práva a neplatné vstupy. Účetní a smluvní pravidla potvrzují odpovědní odborníci.
Podklady a dokumentace
Potřebujete schéma obou systémů, anonymizované události, dokumentaci API, logy, čísla duplicit, časové limity, autentizační model a testovací přístup. Tajné údaje nesdílejte veřejně. Dokumentace Shopify k idempotentním požadavkům poskytuje výchozí informace, ale záruky se vztahují na konkrétní metody a verze.
Technická podpora stojí 30 €/hod. Vývoj a integrace se oceňují individuálně. Pošlete odkaz na e-shop a popis chyby pro nabídku podle skutečného rozsahu.
Stabilní identifikátor a životní cyklus operace
Klíč se váže ke konkrétnímu záměru vytvořit objednávku, nikoliv jen k datu či zákazníkovi. Nové UUID při každém síťovém pokusu problém neřeší. Evidence může obsahovat místní ID objednávky, typ úkonu, otisk parametrů, čas, stav a externí číslo. Pokud externí systém uchovává klíč jen omezenou dobu, pozdější opakování vyžaduje jiné ověření.
Neznámý výsledek není neúspěch
„Nedostali jsme odpověď“ nedokazuje, že nedošlo k uložení objednávky. Spojení se mohlo přerušit po rezervaci zboží či dokončení transakce. Bezpečný postup nejprve hledá původní výsledek. Naopak trvalou validační chybu nelze opravit odesláním stejných chybných dat. Personál musí rozlišovat stavy čeká, výsledek neznámý, potvrzeno a vyžaduje ruční prověření.
Současné opakování vyžaduje atomickou ochranu
Dvě fronty mohou zpracovat stejnou událost zároveň. Pouhé „vyhledej a potom vytvoř“ nepostačuje, pokud oba procesy uvidí prázdný výsledek. Systém odpovědný za operaci potřebuje sjednané záruky unikátnosti a atomické aktualizace. Testujte paralelní volání, rozdílné parametry při jednom klíči, opakování další den a nedostupné vyhledávání. Kontrolujte počet skutečných externích objednávek a vedlejších dokladů, nikoliv jen HTTP odpovědi.