API-koppeling: wat het is en hoe het werkt.

Een API-koppeling is een verbinding waarmee twee softwaresystemen automatisch gegevens uitwisselen. Een API (application programming interface) is de set verzoeken die een systeem van andere software accepteert, zoals "maak deze factuur aan" of "stuur me de betaalde orders van vandaag". De koppeling doet die verzoeken, zodat een betaalde webshoporder een verkoopfactuur wordt zonder dat iemand iets overtypt.

Zegt een leverancier dat zijn product "een API heeft", dan is een koppeling mogelijk. Iemand moet die koppeling nog wel bouwen. Zegt hij dat het product "koppelt met" je boekhoudpakket of ERP, vraag dan welke records er overgaan, in welke richting, hoe vaak, en wie een melding krijgt als een record niet overkomt. Een nachtelijke kopie van nieuwe klanten in één richting en een synchronisatie van orders in twee richtingen zijn allebei koppelingen, met heel verschillende hoeveelheden werk.

Is de koppeling één stap in een groter proces dat je wilt automatiseren, dan helpt onze gids over bedrijfsprocessen automatiseren je om eerst dat proces te kiezen.

Elke uitwisseling via een API bestaat uit een verzoek en een antwoord. Het ene systeem stuurt een verzoek naar een adres dat het andere systeem publiceert, een endpoint, met een token dat laat zien wie het vraagt. Het ontvangende systeem controleert het token, voert het verzoek uit en antwoordt met de gegevens, een bevestiging of een foutcode.

Zo verloopt één uitwisseling tussen twee voorbeeldsystemen, een webshop en een online boekhoudpakket:

1. 01Een klant betaalt order 10482. De webshop stuurt de koppeling meteen een kort bericht dat de order betaald is. Zo'n bericht dat een systeem uit zichzelf stuurt, heet een webhook.
2. 02De koppeling vraagt de API van de webshop om de volledige order: klant, orderregels, btw en verzending.
3. 03Ze vertaalt de order naar de termen van het boekhoudpakket: productcode naar artikelcode, btw-tarief naar btw-code en het e-mailadres van de klant naar de bijbehorende debiteur.
4. 04Ze vraagt de API van het boekhoudpakket om een verkoopfactuur aan te maken en stuurt het toegangstoken mee met het verzoek.
5. 05Het boekhoudpakket controleert het token en de gegevens, maakt de factuur aan en antwoordt met een succescode en het factuurnummer.
6. 06De koppeling slaat het factuurnummer op bij de order en logt de uitwisseling, of die nu gelukt is of niet.

Stap 4 en 5 zien er ongeveer zo uit in JSON via HTTPS, het formaat dat de meeste moderne API's gebruiken. Het adres, de velden en de waarden zijn verzonnen voor dit voorbeeld.

POST https://accounting.example.com/api/v1/sales-invoices
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: webshop-order-10482

{
  "customer_id": "C-2291",
  "invoice_date": "2026-09-15",
  "reference": "webshop-order-10482",
  "lines": [
    { "item_code": "MUG-BLUE", "quantity": 2, "unit_price": 12.50, "vat_code": "HIGH" }
  ]
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "invoice_number": "2026-00731",
  "status": "open"
}

201 Created betekent dat het gelukt is. Fouten hebben andere codes, zoals 401 voor een verkeerd token, 400 of 422 voor een veld dat de validatie niet doorstaat en 429 voor te veel verzoeken. De header Idempotency-Key vertelt een API die dit ondersteunt dat hij een herhaling van hetzelfde verzoek moet negeren. Zo kan een nieuwe poging geen tweede factuur voor order 10482 aanmaken.

Het tegenovergestelde van een webhook is polling: de koppeling vraagt met een vaste tussenpoos of er iets is veranderd. Oudere systemen staan vaak alleen polling toe, en sommige hebben helemaal geen API, alleen een bestandsexport of een database. Die systemen koppelen valt onder integratie van legacy-systemen.

De meeste koppelingen in finance en bedrijfsvoering zetten één soort record over van het systeem waar het ontstaat naar het systeem dat het daarna nodig heeft: een order, een factuur, een klant of een boeking. Drie typische gevallen laten zien wat er overgaat en waar het lastige deel zit.

Webshop naar boekhouding

Betaalde orders worden verkoopfacturen, terugbetalingen worden creditnota's en uitbetalingen van de betaalprovider worden eraan gekoppeld. E-commerceplatforms zoals Shopify en WooCommerce, en boekhoudpakketten zoals Exact Online, publiceren gedocumenteerde API's voor dit soort processen.

Het lastige deel is geld dat niet één op één overeenkomt. Een betaalprovider betaalt vaak één keer per dag uit voor veel orders, minus zijn kosten. Dan moet één banktransactie aan tientallen facturen en een boeking voor die kosten worden gekoppeld. Btw voor klanten in andere EU-landen en afrondingsverschillen zijn de andere gebruikelijke bronnen van uitzonderingen.

CRM naar ERP

Wordt een deal in het CRM gewonnen, dan gaan de klant en de order naar het ERP, zodat de order geleverd en gefactureerd kan worden. De betaalstatus gaat terug, zodat de accountmanager ziet of de klant heeft betaald. CRM's zoals HubSpot en Salesforce, en ERP's zoals AFAS Profit, documenteren hun API's openbaar.

Beide systemen bevatten klantgegevens, dus de eerste beslissing is welk systeem eigenaar is van welk veld. Afleveradres en betalingsvoorwaarden horen misschien bij het ERP, contactpersoon en dealnotities bij het CRM. Zonder die afspraak overschrijft een wijziging in het ene systeem een correctie in het andere. Dubbele records zijn het andere veelvoorkomende probleem: hetzelfde bedrijf twee keer ingevoerd onder een net iets andere naam.

Klantportaal naar planning

Een klant boekt in een portaal een tijdslot voor een levering of een servicebezoek. Het portaal vraagt het planningssysteem welke tijdsloten vrij zijn, reserveert er een en toont de bevestiging. Verplaatst een planner de afspraak, dan gaat die wijziging terug naar het portaal.

Het lastige deel is timing. Twee klanten kunnen tegelijk het laatste tijdslot proberen te boeken. Het planningssysteem moet dus in één stap reserveren en bevestigen, en het portaal heeft een duidelijke melding nodig als een tijdslot net weg is.

In alle drie de gevallen is de API aanroepen het kleinere deel van het werk. Daarom brengen we in onze projecten voor systeemintegratie eerst in kaart welk systeem eigenaar is van elk veld, voordat we iets koppelen.

Er zijn drie manieren om een koppeling te krijgen: een standaardconnector van een van de leveranciers aanzetten, een flow bouwen in een integratieplatform zoals n8n, Make of Zapier, of koppelcode laten schrijven voor jouw systemen. Welke past, hangt af van het volume, hoe kritisch het proces is, hoe ongebruikelijk de veldkoppeling is en wie het onderhoudt.

Bestaat er een standaardconnector die je proces dekt, begin daar dan mee; veel koppelingen hebben nooit meer nodig. Test de connector eerst met je lastige gevallen, zoals creditnota's en deelleveringen. We bouwen op integratieplatforms waar die passen en schrijven maatwerkcode waar volume of logica daarom vraagt, zoals je leest op onze pagina API-koppeling laten maken.

De meeste storingen in koppelingen zijn stil. Een record komt nooit aan, komt twee keer aan of komt aan met een leeg veld, en niemand merkt het tot de maandafsluiting of een klacht van een klant. Elk probleem heeft een bekende tegenmaatregel, en je kunt de bouwer of verkoper van de koppeling vragen welke er zijn ingebouwd.

Rate limits

API's beperken hoeveel verzoeken een client per minuut of per dag mag sturen. Een run bij de maandafsluiting of een grote import kan die grens raken. De API antwoordt dan met 429 Too Many Requests, vaak met een header die zegt wanneer je het opnieuw kunt proberen. Spreid grote taken over de tijd, gebruik bulk-endpoints waar die er zijn, wacht zo lang als de API vraagt en zet de overige records in een wachtrij, zodat er geen verloren gaan.

Gewijzigde velden en API-versies

Een leverancier hernoemt een veld, maakt een optioneel veld verplicht of stopt met een oude API-versie. Of iemand in je eigen organisatie voegt een btw-code toe in het ene systeem en vergeet het andere. De koppeling blijft draaien, maar records komen in het verkeerde veld terecht of worden geweigerd.

Bouw op een API met versienummers als die er is, en volg de aankondigingen van de leverancier over onderdelen die verdwijnen. Controleer elk record tegen de vorm die de koppeling verwacht, en zet elk record dat niet past apart, met de reden. Kondigt een leverancier een wijziging aan, test die dan in een sandbox (een testkopie van het systeem) voordat de wijziging live gegevens raakt.

Stille storingen

Deze kosten het meest, omdat niets ze meldt. Een webhook gaat verloren omdat de ontvangende kant een paar minuten plat lag. Een toegangstoken verloopt en de nachtelijke synchronisatie stopt zonder één fout te loggen. Een API geeft een succescode terug met een foutmelding in het antwoord.

Let naast fouten ook op ontbrekende activiteit: zijn er tijdens openingstijden twee uur lang geen orders gesynchroniseerd, dan moet iemand dat horen. Lees de inhoud van het antwoord naast de statuscode, waarschuw voordat inloggegevens verlopen en controleer periodiek wat er sinds de vorige run is veranderd, zodat gemiste webhooks alsnog worden opgepikt.

Opnieuw proberen

Tijdelijke fouten, zoals een time-out of een korte storing, zijn het waard om opnieuw te proberen. De koppeling probeert het zelf nog eens, wacht na elke poging langer en stopt na een vast aantal pogingen. Blijvende fouten, zoals een onbekende btw-code, mislukken hoe vaak je ze ook verstuurt. Die gaan naar een wachtrij waar een medewerker het record en de fout ziet, de oorzaak oplost en het record opnieuw verstuurt.

Dubbele records en idempotentie

Nieuwe pogingen brengen hun eigen risico mee. Het boekhoudsysteem maakt de factuur aan, het antwoord loopt op de terugweg in een time-out, de koppeling probeert het opnieuw en de klant krijgt twee facturen. Webhooks veroorzaken hetzelfde probleem, omdat veel platforms elke gebeurtenis minstens één keer afleveren, en dat is soms twee keer.

Daartegen helpt idempotentie: hetzelfde verzoek twee keer sturen heeft hetzelfde effect als het één keer sturen. Gebruik een idempotency key als de API die ondersteunt, controleer of er al een record met dezelfde referentie bestaat voordat je een nieuw record aanmaakt, en houd bij welke gebeurtenissen al verwerkt zijn.

Meldingen die een mens bereiken

Een melding in een gedeelde mailbox die niemand leest, doet niets. Stuur elke fout naar een vaste eigenaar, met het record, de fout en een manier om het opnieuw te versturen. Een geweigerde factuur hoort bij finance; een verbinding die plat ligt, hoort bij wie de koppeling beheert. Bundel herhaalde fouten, zodat één storing één melding geeft.

Aansluitcontrole

De aansluitcontrole is het laatste vangnet, en financeteams kennen het principe al van het aansluiten van bankafschriften op het grootboek. Een gepland rapport vergelijkt beide systemen: bijvoorbeeld het aantal en de totale waarde van de betaalde webshoporders van gisteren met de verkoopfacturen die die dag in de boekhouding zijn aangemaakt, met elk verschil op een rij. Het rapport vangt ook handmatige wijzigingen op die maar in één systeem zijn gedaan.

Stel deze vragen voordat je een koppeling accepteert, van een leverancier of van je eigen team:

• Wat gebeurt er met een record dat het andere systeem weigert, en wie krijgt een melding?
• Kan dezelfde gebeurtenis, als die twee keer binnenkomt, een tweede factuur of order aanmaken?
• Hoe merken we het als er een dag lang niets is gesynchroniseerd?
• Welk systeem wint als hetzelfde veld in beide systemen wordt gewijzigd?
• Is er een aansluitrapport, en wie leest het?
• Wie merkt het als een leverancier zijn API wijzigt, en wie past de koppeling aan?

Wat er rond de verbinding zit, bepaalt vooral de kosten van een API-koppeling: hoeveel systemen en soorten records er meedoen, hoe goed hun API's zijn, of data één of twee kanten op gaat, hoeveel uitzonderingen het proces heeft en hoeveel monitoring de koppeling nodig heeft. Vraag hoe een offerte met elk van deze punten rekening houdt.

• Systemen en soorten records. Klanten, orders, facturen en creditnota's hebben elk hun eigen veldkoppeling en regels nodig.
• Kwaliteit van de API. Duidelijke documentatie, een sandbox en webhooks versnellen het werk; ontbrekende velden of een ongedocumenteerde API vertragen het.
• Richting. Synchronisatie in twee richtingen vraagt per veld afspraken over eigenaarschap en een aanpak voor conflicten.
• Uitzonderingen, zoals deelleveringen, buitenlandse btw en samengevoegde klanten, die elk een vastgelegde afhandeling nodig hebben.
• Historische data die gekoppeld of gemigreerd moet worden voordat de live synchronisatie begint.
• Monitoring en support na de livegang, inclusief tools om records opnieuw te versturen en aansluitrapporten.
• Licenties: kosten voor connectors, platformgebruik en bedragen die sommige leveranciers vragen voor API-toegang of hogere rate limits.

Reken naast de bouw ook de lopende kosten mee, want de systemen aan beide kanten blijven veranderen. We spreken scope en kosten af in een schriftelijk plan na de verkenning, zodra de systemen, de data en de uitzonderingen in kaart zijn gebracht.

Kan ik zelf een API-koppeling maken?

Voor eenvoudige gevallen vaak wel. Koppelt een standaardconnector of integratieplatform twee veelgebruikte tools, is het volume laag en is een fout record makkelijk te zien en te herstellen, dan kan iemand in je team met de juiste kennis het opzetten en beheren. Voeg de controles uit het deel over storingen toe, want platforms laten de meeste daarvan aan jou over.

Laat de koppeling bouwen als die op grote schaal facturen, betalingen of klantrecords aanmaakt, twee kanten op synchroniseert, een ouder systeem gebruikt of een audit moet doorstaan.

Is een API-koppeling veilig?

Dat kan, afhankelijk van hoe je de koppeling opzet. Bewaar inloggegevens in een secrets manager, buiten spreadsheets en e-mail. Geef elke koppeling alleen de toegang die ze nodig heeft: een sleutel die facturen aanmaakt, hoeft de salarisadministratie niet te kunnen lezen. Verstuur data via versleutelde verbindingen en controleer de handtekening op binnenkomende webhooks, zodat niemand nepgebeurtenissen kan sturen.

Beperk persoonsgegevens tot wat het ontvangende systeem nodig heeft en houd ze uit logs. Trek sleutels in als een medewerker of leverancier vertrekt, en sluit een verwerkersovereenkomst met wie een koppeling beheert die persoonsgegevens verwerkt.

Wat is het verschil tussen een webhook en polling?

Bij een webhook stuurt het bronsysteem een bericht zodra er iets gebeurt. Bij polling vraagt de koppeling met vaste tussenpozen of er iets is veranderd. Webhooks zijn sneller en lichter, maar een bericht kan verloren gaan. Betrouwbare koppelingen gebruiken daarom vaak webhooks voor de snelheid en een periodieke controle om gemiste berichten op te vangen.