Pět otázek před prvním řádkem kódu může pomoci předejít ručnímu přepisování dat, duplicitním fakturám i hledání ztracených objednávek.
API integraci nezačínám otevřením editoru. Nejdřív vezmu tužku, několik ukázkových záznamů a položím si nepříjemné otázky. Editor umí vytvořit řešení i pro problém, kterému zatím nikdo přesně nerozumí.
Potřebuji vědět, co se má mezi systémy stát, kdo odpovídá za jednotlivá data a co se bude dít při chybě. Teprve potom řeším endpointy, autentizaci a kód.
Následujících pět otázek používám při propojení CRM, účetnictví, helpdesku i interních aplikací. Po každém kroku musí vzniknout výstup, který lze ověřit. Věta „nějak to propojíme“ za výsledek nepovažuji.
Tento postup používám, když si dva systémy mají pravidelně předávat strukturovaná data. Například když se má schválená objednávka propsat do účetnictví, nový zákazník založit v CRM nebo vyřešený požadavek uzavřít v interní evidenci.
Pokud si firma zatím není jistá, zda integraci vůbec potřebuje, je lepší nejdřív zjistit objem ruční práce a počet chyb. Rozhodování podrobněji rozebírám v článku o tom, co je API integrace a kdy ji firma opravdu potřebuje.
API nemusí být správná volba pro přenos pěti záznamů jednou za čtvrt roku. Levnější může být řízený export do CSV. Stejně tak nezačínám integrací procesu, který pokaždé probíhá jinak. Nejdřív jej potřebuji popsat a zjednodušit. Praktický základ nabízí první tři kroky před automatizací procesu.
Potřebuji dokumentaci obou API, přístup do testovacího prostředí a nejméně pět skutečných anonymizovaných záznamů. Jeden běžný, jeden neúplný, jeden s diakritikou, jeden s neobvykle dlouhou hodnotou a jeden, který byl po vytvoření změněn nebo zrušen.
Zjistím si také limity počtu požadavků, způsob autentizace, dostupné verze API a kontakt na člověka, který rozumí každému ze systémů. Nestačí kontakt na obchodníka dodavatele. Potřebuji někoho, kdo dokáže potvrdit význam stavu objednávky nebo vysvětlit, proč API vrací chybu 409.
Když testovací prostředí neexistuje, zapíšu si to jako riziko. První pokusy pak musí proběhnout nad oddělenými daty a s omezeným oprávněním. Produkční účet s právem mazat vše není zkratka. Zvyšuje riziko poškození dat.
U každého přenášeného údaje určím, kde vzniká a kde se smí měnit. Zákaznická adresa může pocházet z CRM, stav úhrady z účetnictví a stav reklamace z helpdesku. Celý záznam nemusí mít jediného vlastníka.
Současně popíšu směr a okamžik přenosu. Záleží na tom, zda účetnictví dostane objednávku ihned po schválení, každých pět minut nebo jednou denně. U malé firmy bývá lákavé synchronizovat všechno oběma směry. Často pak dva systémy přepisují poslední změnu jeden druhému.
Ověřitelným výsledkem je tabulka polí, ve které má každý údaj uvedený zdroj, cíl, směr přenosu a spouštěcí událost. Když u pole neumím tyto čtyři hodnoty doplnit, zatím jej neintegruji.
Stejně pojmenovaná pole nemusí znamenat totéž. „Cena“ může být s daní, bez daně, za kus nebo za celý řádek. „Aktivní zákazník“ může v jednom systému znamenat platnou smlouvu a ve druhém jediný nákup za poslední rok.
Sepíšu proto datové mapování. U každého pole určím formát, povinnost, maximální délku, povolené hodnoty a převodní pravidlo. Řeším také časové pásmo, desetinná čísla, prázdné hodnoty a identifikátory. Jméno firmy není identifikátor. Dvě firmy se mohou jmenovat stejně a jedna firma se může přejmenovat.
V jednom menším projektu vypadal přenos kontaktu jednoduše, dokud se neukázalo, že cílový systém vyžaduje příjmení. Zdroj přitom evidoval název kontaktní osoby pouze v jednom poli. Kdyby se to zjistilo až při ostrém spuštění, integrace by odmítla část zákazníků.
Výsledkem tohoto kroku je sada testovacích vstupů a očekávaných výstupů. Pět připravených záznamů pošlu převodní logikou a u každého ručně ověřím všechna cílová pole.
Integrace má mít vlastní technický účet. Nemá používat heslo zaměstnance, které přestane fungovat při jeho odchodu nebo změně hesla. Přidělím jen oprávnění potřebná pro konkrétní operace. Pokud má spojení číst zákazníky a vytvářet faktury, nepotřebuje mazat uživatele ani měnit nastavení systému.
Zjistím také, kde budou uložené přístupové údaje, kdo je může změnit a jak proběhne jejich obnova. Token nepatří do zdrojového kódu ani do sdílené tabulky. Do logů také neposílám celé požadavky bez kontroly. Mohou obsahovat osobní nebo obchodní údaje.
Ověřitelný výsledek je prostý: s technickým účtem úspěšně provedu povolené operace a nepovolená operace skončí odmítnutím. Současně dokážu přístupový údaj vyměnit bez úpravy a nového sestavení aplikace.
Síť může vypadnout. Cílové API může zpomalit. Požadavek může doběhnout, ale odpověď se cestou ztratí. Integrace pak neví, zda má operaci zopakovat. Pokud vytváří fakturu, může vzniknout kopie.
Proto každé operaci přidělím jednoznačný identifikátor a ověřím, zda jej cílové API umí použít k bezpečnému opakování, například jako idempotentní klíč nebo jedinečnou hodnotu uloženou spolu se záznamem. Nestačí před dalším pokusem jen ověřit existenci záznamu, mezi kontrolou a vytvořením může dorazit jiný požadavek. Automaticky opakuji jen chyby, u kterých to dává smysl, například dočasnou nedostupnost. Chybný formát telefonního čísla se opakováním nezmění.
Počet pokusů a odstupy určím podle typu operace, limitů API a dopadu zpoždění. Potom úloha skončí ve stavu vyžadujícím zásah. Musí u ní být uvedený důvod chyby a identifikátor záznamu.
Výsledkem je test, který simuluje dokončení operace v cílovém systému se ztracenou odpovědí. Po opakování požadavku ověřím, že v cílovém systému nevznikne druhý záznam. Podobný princip front, náhradní cesty a ochrany před dvojím spuštěním popisuji u přípravy procesu na výpadek služby.
Úspěšná odpověď API ještě neznamená správný obchodní výsledek. Server může vrátit stav 200, ale založit zákazníka bez adresy. Potřebuji proto sledovat technické chyby i věcné podmínky.
Určím, kdo dostane upozornění, po jaké době a s jakými údaji. Hláška „synchronizace selhala“ téměř k ničemu neslouží. Upozornění má obsahovat systém, operaci, čas, identifikátor záznamu, počet pokusů a stručnou příčinu. Nemá obsahovat přístupový token ani celý zákaznický profil.
Součástí provozu je také vlastník integrace, postup při změně API a termín kontroly nevyřízených chyb. Výsledkem kroku je zkušební incident. Vyvolám chybu a ověřím, že ji určený člověk najde, rozumí jí a dokáže záznam bezpečně zpracovat znovu.
Častým problémem nebývá HTTP ani JSON, ale nejasný význam dat. Dva lidé používají slovo „objednávka“, ale jeden myslí rozpracovaný košík a druhý závazně potvrzený nákup.
Dalším problémem jsou chybějící hraniční případy. Testuje se jeden bezchybný záznam, nikoli zákazník bez telefonu, dobropis nebo změna po synchronizaci. Častý je také provoz bez vlastníka. Integrace běží půl roku bez povšimnutí a první kontrola přijde ve chvíli, kdy někdo hledá třicet chybějících dokladů.
Pět konkrétních odpovědí a ověřitelné výstupy před programováním odhalí nejasnosti ve chvíli, kdy je lze ještě upravit v návrhu. Kód pak nemusí řešit spory o význam dat, chybějící oprávnění ani postup při selhání přenosu.
API integrace zní technicky, ale řeší obyčejný problém: dvě aplikace o sobě nevědí, tak mezi nimi data přenáší člověk ručně. Co propojení přes API je, jak poznáte, že vám chybí, kolik práce ušetří a kdy se firmě vyplatí.
Low-code a no-code slibují aplikace bez programátorů. Někdy to opravdu funguje, jindy si tím firma zadělá na problém. Vysvětlíme rozdíl mezi obojím, kde to dává smysl a kde radši ruce pryč. Bez frází, s konkrétními pravidly, podle kterých se rozhodnete.
Zjistěte, jak low-code a no-code platformy pomáhají firmám automatizovat procesy, šetřit náklady a minimalizovat chyby. V článku najdete konkrétní příklady využití nástrojů Make a Tabidoo, které ukazují, jak snadno lze propojit systémy, automatizovat rutinní úkoly a vytvořit vlastní aplikace bez…
Napište nám, co u vás řešíte. Ozveme se do jednoho pracovního dne.
