API integrace: Jak mohou různé firemní systémy spolupracovat

API, aplikační programové rozhraní, je jen zdokumentovaný způsob, jak může jeden kus softwaru požádat jiný kus softwaru o data nebo o to, aby se něco stalo. Když CRM odešle nový kontakt na e-mailovou platformu nebo e-shop pošle objednávku do účetního systému, používají API.

Tři běžné vzory

Požadavek / odpověď

Jeden systém se ptá, druhý odpovídá: "dej mi tohoto zákazníka", "vytvoř tuto objednávku". Jednoduché a předvídatelné, ale vyžaduje, aby jedna strana věděla, kdy se ptát.

Webhooky

Místo opakovaného dotazování zdrojový systém odešle událost na URL, když se něco stane: "byla vytvořena nová faktura", "platba proběhla". Nižší latence a efektivnější pro toky řízené událostmi.

Naplánovaná synchronizace

Periodické úlohy přesouvají data v dávkách, každou hodinu, každou noc, každý týden. Užitečné, když aktuálnost není kritická a push je nepraktický.

Většina reálných integrací kombinuje alespoň dva z těchto vzorů.

Co dělá integraci spolehlivou

• Jasné vlastnictví dat. Jeden systém je zdrojem pravdy pro každý kus dat. Ostatní dostávají kopie.
• Idempotentní operace. Opakování stejného volání dvakrát přinese stejný výsledek, což je zásadní pro webhooky a nestabilní sítě.
• Viditelné ošetření chyb. Selhání jdou někam, kde je člověk vidí, ne do tichého logu, který nikdo nečte.
• Respektování rate limitů. Dobré integrace zpomalí, když je druhá strana pomalá nebo přetížená.
• Povědomí o verzování. API se mění. Berte integraci jako kód, který potřebuje aktualizace, ne jako jednorázové zapojení.

Co dělá integraci křehkou

• CSV exporty rozesílané po firmě e-mailem a ručně znovu importované.
• Napevno zadané přihlašovací údaje na místech, na která si nikdo nepamatuje.
• Jeden dlouhý skript, který dělá všechno bez logiky opakování.
• Tichá selhání, data přestanou téct a nikdo si toho týdny nevšimne.
• Obousměrná synchronizace bez jasných pravidel pro konflikty: která strana vyhraje, když se změnily obě?

Middleware, nebo přímá integrace?

Existují tři hlavní přístupy:

• Přímá integrace: systém A komunikuje přímo se systémem B. Nejjednodušší pro jedno propojení, zamotané, když jich je mnoho.
• Integrační platforma (iPaaS): vyhrazený nástroj, například workflow platforma, obsluhuje konektory. Dobré pro jednoduché, běžné toky, může být nákladné a neprůhledné pro složitou logiku.
• Vlastní middleware: malá interní služba, která vlastní integrační logiku, překlady a ošetření chyb. Často správná volba, když je logika specifická pro firmu.

Nejlepší odpověď závisí na tom, kolik systémů spolu musí komunikovat, kolik vlastní logiky je v tom zapojeno a zda chcete mít obchodní pravidla v rozhraní dodavatele, nebo v kódu, který vlastníte.

Konkrétní příklad webhooku

Řekněme, že e-commerce platforma by měla upozornit váš účetní systém pokaždé, když je objednávka zaplacena. Místo dotazování každou minutu shop zavolá váš endpoint s malou JSON datovou částí:

{
  "event": "order.paid",
  "event_id": "evt_8f3c21a9",
  "occurred_at": "2024-11-12T09:41:07Z",
  "order": {
    "id": "ORD-10427",
    "total": 1499.00,
    "currency": "PLN",
    "customer_email": "k.nowak@example.com"
  }
}

Přijímající služba by měla požadavek přijmout, ověřit hlavičku s podpisem, uložit event_id a rychle vrátit 200. Skutečná práce, jako vytvoření faktury, probíhá v úloze na pozadí. Pokud stejná událost dorazí dvakrát, uložené event_id zabrání duplicitní faktuře.

Zpracování opakování bez duplikátů

Každá spolehlivá integrace potřebuje idempotentní klíč. Minimální vzor v pseudokódu:

async function handleOrderPaid(event) {
  if (await seen(event.event_id)) return; // already processed
  await markSeen(event.event_id);
  await queue.enqueue('create-invoice', event.order);
}

Běžné chyby

• Integrace příliš brzy. Pokud proces není stabilní, integrace zakóduje ten chaos a ztíží jeho změnu.
• Obousměrná synchronizace ve výchozím stavu. Jednosměrná je jednodušší a často dostačující, na obousměrnou přejděte, jen pokud to firma skutečně potřebuje.
• Žádný monitoring. Integrace bez upozornění je tiché selhání čekající na svou chvíli.
• Těsné provázání. Změny v jednom systému by neměly rozbít všechny ostatní. Udržujte překladovou vrstvu.

Realistický přístup

1. Nakreslete tok dat: který systém vlastní které pole a kdo potřebuje kopie.
2. Začněte nejbolestivějším jednotlivým tokem a postavte ho nejprve jednosměrně.
3. Používejte webhooky tam, kde záleží na nízké latenci, naplánovanou synchronizaci tam, kde ne.
4. Přidejte monitoring od prvního dne, ne až po prvním výpadku.
5. Zdokumentujte přihlašovací údaje, endpointy a vlastnictví, aby integrace přežila personální změny.