API-integraties: hoe verschillende bedrijfssystemen kunnen samenwerken

Een API, application programming interface, is gewoon een gedocumenteerde manier waarop het ene stuk software het andere om gegevens kan vragen, of iets kan laten gebeuren. Wanneer een CRM een nieuw contact naar een e-mailplatform stuurt, of een webshop een bestelling naar een boekhoudsysteem plaatst, gebruiken ze API's.

Drie veelvoorkomende patronen

Verzoek / antwoord

Het ene systeem vraagt, het andere antwoordt: "geef me deze klant", "maak deze bestelling aan". Eenvoudig en voorspelbaar, maar vereist dat de ene kant weet wanneer het moet vragen.

Webhooks

In plaats van herhaaldelijk te vragen, duwt het bronsysteem een gebeurtenis naar een URL wanneer er iets gebeurt: "er is een nieuwe factuur aangemaakt", "een betaling is geslaagd". Lagere latentie en efficiënter voor event-gedreven flows.

Geplande synchronisatie

Periodieke taken verplaatsen gegevens in batches, elk uur, elke nacht, elke week. Nuttig wanneer versheid niet kritiek is en een push onpraktisch is.

De meeste integraties in de praktijk combineren minstens twee hiervan.

Wat een integratie betrouwbaar maakt

• Duidelijk gegevenseigenaarschap. Eén systeem is de bron van waarheid voor elk stukje gegevens. Andere ontvangen kopieën.
• Idempotente operaties. Dezelfde aanroep twee keer opnieuw uitvoeren levert hetzelfde resultaat op, essentieel voor webhooks en instabiele netwerken.
• Foutafhandeling die zichtbaar is. Fouten gaan ergens naartoe waar een mens ze kan zien, niet in een stil logboek dat niemand leest.
• Rate limits gerespecteerd. Goede integraties trekken zich terug wanneer de andere kant traag of beperkt is.
• Bewustzijn van versies. API's veranderen. Behandel de integratie als code die updates nodig heeft, niet als eenmalig bekabelingswerk.

Wat een integratie kwetsbaar maakt

• CSV-exports die binnen het bedrijf worden rondgemaild en handmatig opnieuw geïmporteerd.
• Hardgecodeerde inloggegevens op plekken die niemand zich herinnert.
• Eén lang script dat alles doet zonder retry-logica.
• Stille fouten, gegevens stoppen met stromen en niemand merkt het wekenlang.
• Tweerichtingssynchronisatie zonder duidelijke conflictregels: welke kant wint wanneer beide zijn gewijzigd?

Middleware of directe integratie?

Er zijn drie hoofdbenaderingen:

• Directe integratie: systeem A praat rechtstreeks met systeem B. Het eenvoudigst voor één verbinding, wordt rommelig wanneer er veel zijn.
• Integratieplatform (iPaaS): een speciale tool zoals een workflowplatform handelt de connectoren af. Goed voor eenvoudige, veelvoorkomende flows; kan duur en ondoorzichtig zijn voor complexe logica.
• Maatwerk-middleware: een kleine interne service die de integratielogica, vertalingen en foutafhandeling bezit. Vaak de juiste keuze wanneer de logica specifiek is voor het bedrijf.

Het beste antwoord hangt af van hoeveel systemen met elkaar moeten praten, hoeveel maatwerklogica erbij komt kijken en of je de bedrijfsregels in de UI van een leverancier wilt of in code die je zelf bezit.

Een concreet webhook-voorbeeld

Stel dat een e-commerceplatform je boekhoudsysteem moet waarschuwen telkens wanneer een bestelling is betaald. In plaats van elke minuut te pollen, roept de shop je endpoint aan met een kleine JSON-payload:

{
  "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"
  }
}

De ontvangende service moet het verzoek accepteren, een signature-header verifiëren, de event_id opslaan en snel 200 teruggeven. Het eigenlijke werk, zoals het aanmaken van een factuur, gebeurt in een achtergrondtaak. Als dezelfde gebeurtenis twee keer aankomt, voorkomt de opgeslagen event_id een dubbele factuur.

Retries afhandelen zonder duplicaten

Elke betrouwbare integratie heeft een idempotency-sleutel nodig. Een minimaal patroon in pseudocode:

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);
}

Veelgemaakte fouten

• Te vroeg integreren. Als het proces niet stabiel is, codeert de integratie de rommel en wordt het moeilijker om te veranderen.
• Tweerichtingssynchronisatie als standaard. Eenrichting is eenvoudiger en vaak voldoende, ga alleen naar tweerichting als het bedrijf dat echt nodig heeft.
• Geen monitoring. Een integratie zonder waarschuwingen is een stille storing die staat te wachten om te gebeuren.
• Strakke koppeling. Wijzigingen in één systeem mogen niet alle andere breken. Behoud een vertaallaag.

Een realistische aanpak

1. Teken de gegevensstroom: welk systeem bezit welk veld en wie heeft kopieën nodig.
2. Begin met de pijnlijkste enkele flow en bouw die eerst eenrichtings.
3. Gebruik webhooks waar lage latentie ertoe doet, geplande synchronisatie waar dat niet zo is.
4. Voeg monitoring toe vanaf dag één, niet na de eerste storing.
5. Documenteer inloggegevens, endpoints en eigenaarschap, zodat de integratie personeelswisselingen overleeft.