API-koppelingen bouwen.

Wat is een API-koppeling?

Een API-koppeling verbindt twee systemen zodat ze automatisch gegevens uitwisselen. In plaats van handmatig data overtikken van je webshop naar je boekhoudprogramma, laat je de systemen rechtstreeks met elkaar praten. Dat bespaart tijd, voorkomt fouten en maakt je bedrijfsprocessen schaalbaar.

API staat voor Application Programming Interface. Het is een set afspraken waarmee software met andere software communiceert. Denk aan een ober in een restaurant: jij (het ene systeem) geeft je bestelling door aan de ober (de API), die het doorgeeft aan de keuken (het andere systeem) en met je gerecht terugkomt.

REST vs GraphQL

De twee meest gebruikte API-stijlen zijn REST en GraphQL. Voor de meeste zakelijke integraties werk je met REST, simpelweg omdat bijna alle business-software REST-API's aanbiedt.

REST

REST-API's werken met vaste afspraken voor het uitwisselen van data. Je kunt gegevens ophalen, nieuwe records aanmaken, bestaande gegevens wijzigen of verwijderen. Elk type data heeft een eigen adres binnen de API. Zo kun je bijvoorbeeld alle facturen opvragen, of een specifieke factuur ophalen op basis van het factuurnummer.

REST is eenvoudig te begrijpen, breed ondersteund en goed genoeg voor 90% van de integraties die je tegenkomt.

GraphQL

GraphQL laat de client precies specificeren welke data hij nodig heeft. In plaats van een vast antwoord per endpoint, stuur je een query die beschrijft welke velden je wilt. Dit is handig als je te maken hebt met complexe, geneste data en je niet telkens meerdere endpoints wilt aanroepen.

In de praktijk bieden de meeste Nederlandse zakelijke applicaties (Exact Online, Moneybird, Mollie, Bol.com) REST-API's aan. GraphQL zie je vaker bij producten als Shopify en in moderne SaaS-platforms.

Handmatig data overtypen tussen systemen is niet alleen inefficiënt; het is een tikkende tijdbom van fouten die je bedrijf geld kost.

Authenticatie: wie mag wat?

Elke API moet weten wie er aanklopt. Er zijn drie veelgebruikte methoden:

API keys

De eenvoudigste vorm. Je krijgt een unieke sleutel die je meestuurt bij elk verzoek. Simpel en effectief voor directe communicatie tussen systemen. Nadeel: als de sleutel uitlekt, heeft iemand volledige toegang tot de koppeling.

OAuth 2.0

De standaard voor integraties waarbij een gebruiker toestemming geeft. De gebruiker logt in bij de externe dienst, geeft jouw applicatie toestemming, en je ontvangt een access token en een refresh token. Het access token verloopt na korte tijd; het refresh token gebruik je om een nieuw access token op te halen. Exact Online, Moneybird en de meeste grote platforms gebruiken OAuth 2.0.

OAuth is complexer om te implementeren, maar veiliger. De gebruiker kan altijd de toegang intrekken en je hoeft geen wachtwoorden op te slaan.

Tokens

Een veelgebruikte methode waarbij het systeem een beveiligd digitaal pasje uitgeeft. Dit pasje bevat informatie over wie de gebruiker is en welke rechten hij heeft. Het is beveiligd met een digitale handtekening, zodat de ontvanger kan controleren of het pasje echt en geldig is.

Rate limiting: slim omgaan met limieten

Elke API heeft limieten op het aantal verzoeken dat je per minuut mag versturen. Afhankelijk van de dienst en je abonnement mag je 60 tot 1000 verzoeken per minuut doen.

Als de limiet wordt overschreden, weigert het externe systeem tijdelijk verdere verzoeken. Een goed gebouwde koppeling handelt dit automatisch af: even wachten en het opnieuw proberen, zonder dat je er iets van merkt.

Bij grotere synchronisaties (bijvoorbeeld het importeren van alle klanten uit een CRM) houdt de koppeling hier automatisch rekening mee door de data in behapbare porties te verwerken.

Foutafhandeling: verwacht het onverwachte

Externe systemen gaan soms offline, verbindingen vallen weg of data wordt afgewezen. Een professionele koppeling houdt hier rekening mee en handelt problemen automatisch af.

Waar een goede koppeling aan voldoet:

• Volledige registratie; elke communicatie wordt vastgelegd, zodat je bij problemen snel kunt achterhalen wat er is misgegaan.
• Automatisch opnieuw proberen; bij tijdelijke storingen probeert de koppeling het automatisch opnieuw, met steeds iets langere wachttijden.
• Je systeem blijft werken; als de koppeling tijdelijk niet beschikbaar is, draait je applicatie gewoon door. Acties worden bewaard en later alsnog verwerkt.
• Actieve bewaking; je krijgt een melding als er structureel iets misgaat, zodat je snel kunt ingrijpen.

Webhooks vs polling

Er zijn twee manieren om te weten of er iets veranderd is in het externe systeem:

Polling

Je vraagt periodiek aan het andere systeem: "Is er iets nieuws?" Bijvoorbeeld elke 5 minuten alle nieuwe orders opvragen. Dit is eenvoudig op te zetten maar niet heel efficiënt. Je maakt veel onnodige verzoeken en er zit altijd een vertraging tussen het moment dat data verandert en het moment dat jij het oppikt.

Webhooks

Het externe systeem stuurt automatisch een bericht naar je applicatie zodra er iets verandert. Dit is sneller en efficienter dan periodiek controleren. Je systeem ontvangt de update direct en kan er meteen op reageren.

In de praktijk gebruiken we webhooks waar mogelijk. Als een systeem geen webhooks aanbiedt, of als extra vangnet voor gemiste berichten, combineren we het met periodieke controles.

Een koppeling die stilletjes faalt is erger dan eentje die luid klaagt. Bouw je integraties alsof ze morgen kapot gaan; want dat doen ze.

Data mapping: de verborgen complexiteit

De technische verbinding is vaak het makkelijke deel. De echte uitdaging zit in data mapping: hoe vertaal je gegevens van het ene systeem naar het andere?

Klant-ID's zijn anders, productcategorien komen niet overeen, datumformaten verschillen, en verplichte velden in het ene systeem bestaan niet in het andere. Dit vereist duidelijke afspraken en transformatieregels.

Dit vereist duidelijke afspraken die vooraf worden vastgelegd. Welk gegeven in het ene systeem komt overeen met welk gegeven in het andere? Wat gebeurt er als informatie ontbreekt? Hoe ga je om met waarden die niet bestaan in het doelsysteem? Wij leggen dit vast voordat we beginnen met bouwen.

Veelvoorkomende integraties voor bedrijven

• CRM; Salesforce, HubSpot, Pipedrive. Klantgegevens en deals synchroniseren.
• Boekhouding; Exact Online, Moneybird, Xero. Facturen en financiele data automatisch verwerken.
• E-commerce; Shopify, WooCommerce, Bol.com. Orders, voorraad en producten koppelen.
• Betalingen; Mollie, Stripe. Betaalstatussen synchroniseren met je ordersysteem.
• Logistiek; PostNL, DHL, SendCloud. Verzendlabels genereren en track & trace koppelen.
• Communicatie; Slack, Microsoft Teams, e-mail. Notificaties en updates automatiseren.

Hoe wij een API-koppeling aanpakken

Een succesvolle koppeling begint niet met bouwen. Dit zijn de stappen die wij doorlopen:

1. Doel bepalen; welk probleem lossen we op? Welke data moet waar naartoe?
2. Mogelijkheden inventariseren; wat biedt het externe systeem? Welke beperkingen gelden er?
3. Data-afspraken vastleggen; welke gegevens koppelen we? Hoe gaan we om met uitzonderingen?
4. Synchronisatiestrategie kiezen; real-time updates, periodieke controles of een combinatie?
5. Foutafhandeling inrichten; wat als het misgaat? Hoe herstelt het systeem automatisch? Wie wordt gewaarschuwd?
6. Bouwen en testen; eerst in een testomgeving, pas daarna live met echte data.
7. Bewaking opzetten; overzichtelijke dashboards en meldingen zodat je weet dat alles draait.

Sla geen stap over. De meeste mislukte koppelingen falen niet op de techniek maar op onduidelijke afspraken vooraf of ontbrekende foutafhandeling.

De meeste mislukte koppelingen falen niet op techniek; ze falen op slechte voorbereiding en ontbrekend foutbeheer.