Wat is een API-koppeling? Uitleg zonder vakjargon

Je typt gegevens over van het ene programma naar het andere, en iemand zegt: “Daar kun je een API-koppeling voor maken.” Hieronder staat wat dat is, hoe het werkt en wat je regelt voordat je er een laat maken of zelf bouwt. De voorbeelden komen uit de openbare documentatie van Moneybird, Exact Online, Mollie en n8n.

Wat is een API?

Een API is een vaste ingang die een programma openzet voor andere software. Via die ingang kan een ander programma gegevens opvragen, aanmaken of wijzigen, volgens regels die de leverancier vastlegt.

Een voorbeeld is Moneybird. Volgens de API-documentatie van Moneybird is de API RESTful en gebruikt hij JSON en XML om gegevens te versturen. Moneybird noemt als toepassingen onder meer facturen automatisch versturen vanuit je webshop, contactgegevens synchroniseren en producten importeren.

Wat is dan een API-koppeling?

Een API-koppeling is de software die twee API’s met elkaar verbindt. Hij haalt gegevens op uit het ene programma, zet ze om naar wat het andere programma verwacht en stuurt ze door. Een nieuwe verkoopfactuur in je CRM wordt zo een factuur in je boekhouding, zonder dat iemand iets overtypt.

Wat een koppeling kan, hangt af van wat beide API’s toestaan. De API-referentie van Exact Online laat per onderdeel zien welke handelingen er zijn: bij verkoopfacturen bijvoorbeeld opvragen, aanmaken, wijzigen en verwijderen, bij andere onderdelen alleen opvragen. Staat iets niet in de API, dan kan een koppeling het ook niet.

Hoe weet een koppeling dat er iets veranderd is?

Op twee manieren:

• Op vaste momenten kijken. De koppeling vraagt bijvoorbeeld elk uur op wat er nieuw is. Dat werkt bij elke API, maar je ziet een wijziging pas bij de volgende ronde.
• Een seintje via een webhook. Het programma roept zelf een adres van jouw koppeling aan zodra er iets verandert. Mollie doet dat bijvoorbeeld als een betaling betaald is. Volgens de webhookdocumentatie van Mollie stuurt Mollie alleen het ID van de betaling mee. De koppeling vraagt daarna zelf de status op, zodat een nep-melding geen onbetaalde order laat verwerken.

Exact Online heeft in zijn API-referentie ook een onderdeel voor webhookabonnementen. Welke gebeurtenissen een webhook hebben, verschilt per programma.

Waar moet een koppeling rekening mee houden?

Een paar dingen die in bijna elke API-documentatie terugkomen:

• Inloggen. Een koppeling moet zich aanmelden. Bij Moneybird kan dat volgens de documentatie met OAuth of met een persoonlijk API-token.
• Limieten. Een API laat maar een bepaald aantal verzoeken toe. Moneybird noemt in dezelfde documentatie 150 verzoeken per 5 minuten per IP-adres, met een strengere grens voor rapportages.
• Pagina’s. Lange lijsten komen in delen terug. Een koppeling moet alle delen ophalen, anders mist hij gegevens.
• Testen. Moneybird biedt sandbox-administraties om een koppeling te testen zonder abonnement. Kijk in de documentatie van jouw programma of er een testomgeving is.
• Fouten opvangen. Mollie probeert een mislukte webhook later opnieuw. Volgens de documentatie van Mollie stopt dat na 10 pogingen, ongeveer 26 uur na de wijziging. Een koppeling die zo lang plat ligt, mist dus meldingen.

Daarom is een koppeling nooit helemaal af. Verandert een programma zijn API, dan moet de koppeling mee.

Moet je zelf kunnen programmeren?

Niet altijd. Er zijn drie routes:

1. Een bestaande koppeling. Soms heeft een programma er al een voor jouw combinatie. Kijk eerst op de pagina van je app, zoals Moneybird, Exact Online of Mollie.
2. Een tool als n8n, Make of Zapier. Die hebben kant-en-klare blokken voor veel apps. Heeft een app geen blok, dan kun je in n8n de API rechtstreeks aanroepen met de HTTP Request-node. Daarvoor heb je volgens n8n wel basiskennis van API’s nodig. Welke tool wat heeft, staat op de pagina over zelf bouwen.
3. Maatwerk. Een ontwikkelaar bouwt de koppeling met eigen code, of in een van die tools. Dat past als geen bestaande koppeling doet wat je nodig hebt.

Wat regel je voordat je een koppeling laat bouwen?

Zet op papier:

• welke programma’s het zijn, en welk programma leidend is als gegevens verschillen;
• welke gegevens erheen moeten, en wanneer;
• wat er moet gebeuren als iets misgaat, en wie daar een melding van krijgt;
• of er persoonsgegevens meegaan.

Dat laatste telt voor de AVG. Verwerkt een andere partij in jouw opdracht persoonsgegevens, dan is die partij volgens de Autoriteit Persoonsgegevens een verwerker, en moet je met die verwerker een verwerkersovereenkomst sluiten. Dat kan gelden voor de tool waarin de koppeling draait en voor wie hem bouwt of beheert.

Wil je de koppeling laten bouwen, dan kan dat via laat het bouwen. In de intake kijken we eerst of er al een bestaande koppeling is die goed genoeg is.