Duplicitné objednávky a leady pri integráciách: návrh idempotentného spracovania medzi systémami

Duplicitné objednávky pri integrácii nevznikajú len preto, že zákazník dvakrát odoslal formulár. Často ich spôsobí správne fungujúci retry mechanizmus, opakovane doručený webhook alebo neistota po časovom limite: odosielajúci systém nedostal odpoveď, preto tú istú požiadavku pošle znovu. Ak cieľový systém pri každom prijatí vykoná iba príkaz „vytvor“, vzniknú dva záznamy napriek tomu, že obchodná udalosť bola len jedna.

Tento návrhový rámec je určený pre firmy prepájajúce e-shop, formuláre, CRM, ERP, fakturáciu alebo vlastnú databázu. Rieši prevenciu duplicít priamo v integračnom toku, nie iba následné čistenie databázy. Rovnaké pravidlá platia pre objednávky, leady, kontakty, firmy aj obchodné prípady, no každá entita potrebuje vlastný identifikátor a vlastné pravidlá aktualizácie.

Najprv pomenujte, čo je vlastne duplicita

Technická duplicita a obchodná duplicita nie sú to isté. Jedna objednávka môže vyvolať viac udalostí: vytvorenie, úhradu, zmenu adresy, expedíciu a storno. Každá z nich je samostatná udalosť, ale odkazuje na tú istú objednávku. Naopak, dve objednávky od toho istého zákazníka s rovnakým košíkom môžu byť úplne legitímne, napríklad ak druhú vytvoril po zrušení platby.

Pri leadoch je hranica ešte citlivejšia. Jeden človek môže vyplniť formulár dvakrát, pretože nedostal odpoveď, ale môže sa ozvať znovu o pol roka s novým záujmom. Pravidlo „rovnaký e-mail = nezakladať lead“ môže obchodníkom skryť relevantný nový dopyt. Zvyčajne je vhodné odlišovať kontakt ako trvalú entitu od konkrétneho dopytu alebo obchodného prípadu.

Pred technickou implementáciou preto definujte jednotku jedinečnosti: je ňou objednávka, platba, doručenie, kontakt, formulárové odoslanie alebo obchodný prípad? Bez tejto definície bude deduplikácia dát medzi systémami len séria výnimiek.

Určite vlastníka dát a povolené operácie

Integrácia sa stáva nepredvídateľnou, keď dva systémy považujú rovnaké pole za svoje. E-shop napríklad vytvorí objednávku, ERP pridelí interné číslo a stav účtovania, CRM drží obchodnú komunikáciu. Ak CRM pošle svoju verziu stavu späť do e-shopu bez jasného pravidla, môže prepísať stav, ktorý zmenil sklad alebo účtovníctvo.

Pri každej entite si zapíšte vlastníka a smer toku. Vlastník nemusí byť systém, kde sa údaje najčastejšie zobrazujú. Je to systém, ktorého zápis rozhoduje o platnosti konkrétneho údaja.

• Objednávka: zdrojový e-shop alebo objednávkový systém ju vytvára; ostatné systémy ju identifikujú cez externé ID.
• Kontakt: CRM môže byť vlastníkom obchodných poznámok, segmentácie a stavu komunikácie; web však môže vlastniť súhlas získaný vo formulári, ak je jeho evidencia autoritatívna.
• Firma: názov a IČO môžu prísť z formulára, ale ručne overené údaje v ERP nemá aizácia bez pravidiel prepisovať.
• Stav spracovania integrácie: patrí integračnej vrstve alebo evidencii, ktorá dokáže povedať, čo bolo prijaté, zapísané, odmietnuté a čo čaká na riešenie.

Dobré rozhodnutie je aj explicitné „neprenášať“. Nie každá poznámka, interný tag či marketingové pole má zmysel synchronizovať obojsmerne. Čím viac polí môže meniť viac zdrojov, tým väčšia je plocha pre konflikty.

Externé ID, ID udalosti a prečo e-mail nestačí

Bez stabilného identifikátora nevie cieľový systém bezpečne rozpoznať, že už konkrétnu vec pozná. Pre objednávku použite externé ID zo zdrojového systému, ktoré sa po vytvorení objednávky nemení. Do cieľového systému ho ukladajte ako samostatné pole, nie iba do voľnej poznámky. Ideálne má byť na kombináciu zdroja a externého ID uplatnené unikátne obmedzenie.

Treba rozlišovať minimálne tri hodnoty:

• ID entity: napríklad shop:order:81452; identifikuje objednávku počas celej jej životnosti.
• ID udalosti: napríklad evt_...; identifikuje jedno konkrétne doručenie alebo zmenu.
• Idempotency key: kľúč priradený k zápisovej požiadavke; umožňuje bezpečne zopakovať tú istú operáciu pri technickom zlyhaní.

E-mail je užitočný pomocný údaj na hľadanie kontaktu, ale nie je spoľahlivým identifikátorom leadu. Môže byť zdieľaný, zmenený, obsahovať preklep alebo patriť agentúre, ktorá zastupuje viac firiem. Názov firmy je ešte slabší: líši sa právnou formou, diakritikou aj zápisom. Ak zdroj nemá vlastné ID, vytvorte ho pri prijatí a trvalo ho uchovajte spolu s označením zdroja.

Idempotentné spracovanie API: viac než „nájdi alebo vytvor“

Idempotentné spracovanie API znamená, že opakované vykonanie rovnakej operácie vedie k rovnakému výsledku ako prvé vykonanie. Pri vytvorení objednávky to neznamená, že systém ignoruje všetky ďalšie požiadavky. Znamená to, že pri rovnakej požiadavke s rovnakým kľúčom vráti výsledok pôvodného zápisu namiesto založenia ďalšieho záznamu.

Najjednoduchší postup „vyhľadaj podľa externého ID, ak nič nenájdeš, vytvor“ má slabinu. Dva paralelné workery môžu v rovnakom okamihu nič nenájsť a oba vytvoriť záznam. Kontrolu v aplikácii preto musí doplniť ochrana v úložisku: unikátny index, transakčný zápis alebo iný mechanizmus, ktorý vie atomicky odmietnuť druhý pokus.

1. Prijmi udalosť a over jej pôvod.2. Zisti, či bolo event_id už spracované.3. Rezervuj idempotency key v transakcii alebo cez unikátne obmedzenie.4. Nájdeš cieľový záznam podľa source + external_entity_id.5. Vytvor ho alebo aktualizuj iba povolené polia.6. Ulož výsledné cieľové ID a stav spracovania.7. Pri opakovaní vráť pôvodný výsledok, nie nový zápis.

Evidencia spracovaných udalostí chráni pred rovnakým webhookom. Unikátna väzba zdroja a externého ID chráni pred vytvorením druhej entity aj vtedy, ak príde iná udalosť k tej istej objednávke. Idempotency key rieši neistý stav jednej zápisovej požiadavky. Tieto vrstvy sa nenahrádzajú; riešia odlišné zlyhania.

Retry, timeout a súbežné workflow sú normálny prevádzkový stav

Najzradnejší scenár vyzerá jednoducho: integračný proces odošle požiadavku na vytvorenie objednávky, cieľ ju uloží, ale odpoveď sa cestou stratí alebo príde neskoro. Odosielateľ vidí timeout a pokus zopakuje. Bez idempotency key sa vytvorí ďalšia objednávka. Bez kvalitného logu navyše nikto rýchlo nezistí, či prvý zápis prebehol.

Retry plán musí rozlišovať chyby. Dočasná nedostupnosť, prekročený limit alebo sieťová chyba môžu byť dôvodom na opakovanie. Chyba validácie dát, chýbajúce povinné pole či zamietnuté oprávnenie sa opakovaním nevyriešia. Taký prípad patrí do frontu výnimiek s jasnou príčinou a zodpovednou osobou.

• Opakujte iba operácie, pri ktorých je identita požiadavky stabilná.
• Pri retry používajte rovnaký idempotency key, nie nový náhodný kľúč.
• Obmedzte počet aických pokusov a evidujte čas poslednej chyby.
• Pred opakovaním, ak to rozhranie umožňuje, overte stav podľa externého ID alebo kľúča.
• Neodpovedaný webhook nepovažujte aicky za nespracovaný webhook.

Webhook duplicity treba očakávať aj bez chyby. Niektorí poskytovatelia doručujú udalosti spôsobom „aspoň raz“, nie „presne raz“. Presne raz sa v distribuovaných systémoch nedá spoľahlivo sľúbiť len konfiguráciou workflow; dosahuje sa kombináciou opakovaného doručenia a idempotentného príjemcu.

Konflikty aktualizácií: určite pravidlá po poliach

Keď existujúci záznam nájdete, ešte neviete, či ho smiete prepísať. Pravidlo „posledná zmena vyhráva“ je lákavé, ale často poškodí dáta. Časové pečiatky môžu používať iné časové pásma, byť nepresné alebo opisovať čas exportu namiesto času zmeny. A manuálna úprava obchodníka môže byť významnejšia než neskoršia technická synchronizácia.

Praktickejší model je vlastníctvo po poliach. Zdroj objednávky smie meniť položky, cenu a dodaciu adresu do určitého stavu. ERP smie meniť fakturačné a logistické údaje. CRM smie meniť obchodnú kvalifikáciu, poznámky a zodpovednú osobu. Ak dva zdroje chcú zmeniť rovnaké citlivé pole, proces nevyrieši konflikt aicky, ale vytvorí záznam na posúdenie.

Pri systémoch, ktoré podporujú verzie alebo čas poslednej zmeny, prenášajte aj tieto údaje. Aktualizácia môže potom kontrolovať, či nepracuje so starým stavom. Pri úplných exportoch si dávajte pozor, aby prázdna hodnota neprepísala údaj, ktorý zdroj len neposlal. Rozlišujte „pole je prázdne“ od „pole nie je súčasťou udalosti“.

Audit integračného toku: otázky, ktoré odhalia slabé miesta

Audit integračného toku začnite konkrétnou cestou jednej objednávky alebo jedného leadu. Sledujte ju od vzniku až po všetky ciele, vrátane importov a manuálnych zásahov. Diagram bez reálnych identifikátorov je málo: potrebujete vedieť, ktoré ID sa kde ukladajú a podľa čoho sa rozhoduje o vytvorení či aktualizácii.

Log bez kontextu nepomôže. Pri každej udalosti potrebujete aspoň zdroj, externé ID entity, ID udalosti, idempotency key, čas prijatia, výsledok, cieľové ID a chybové hlásenie. Citlivé údaje do logov nepatria bez dôvodu; identifikátory a bezpečne obmedzené diagnostické dáta však musia zostať použiteľné pre dohľadanie problému.

Kedy workflow nestačí a treba integračnú vrstvu

Jednoduchý workflow môže byť vhodný pri jednom formulári a jednom cieli, ak cieľové API podporuje bezpečné vyhľadanie a aktualizáciu záznamu. Riziko rastie, keď sa pridávajú obojsmerné synchronizácie, viac zdrojov tej istej entity, vlastné pravidlá konfliktov, vysoký počet výnimiek alebo potreba spoľahlivej auditnej stopy.

Signálom na samostatnú integračnú vrstvu je najmä situácia, keď logika deduplikácie žije rozdelená vo viacerých aizačných scenároch. Jeden scenár vytvára lead, druhý dopĺňa firmu, tretí importuje dáta a každý používa inú definíciu zhody. Vtedy je rozumnejšie centralizovať mapovanie identifikátorov, evidenciu udalostí, retry front a pravidlá zápisu do databázy alebo aplikácie určenej pre tento proces.

Nie každá integrácia potrebuje vlastný systém. Rozhodnutie závisí od počtu tokov, kritickosti procesu, možností existujúcich rozhraní, objemu dát, požiadaviek na audit a od toho, či sa pravidlá budú meniť. Dôležité je, aby rozhodovanie o tom, či vytvoriť, aktualizovať, ignorovať alebo zastaviť záznam, nebolo skryté v neprehľadnej zostave podmienok bez dohľadateľného výsledku.