API koppeling testen voor livegang: de complete checklist

Kort antwoord: test de gouden workflow, randgevallen, foutscenario's, performance onder piek en reconciliatie met je boekhouding. Draai minimaal twee weken parallel met echte data voordat je het handmatige proces stopt. Bij financiële koppelingen doe je minstens één volledige maandafsluiting parallel, zodat je zeker weet dat de boekhouding klopt. Zonder reconciliatie rapport weet je achteraf niet of een stille fout je administratie heeft verpest.

Waarom een testplan belangrijk is

Een API koppeling die 95 procent van de gevallen goed verwerkt, lijkt prima. Maar die 5 procent is waar je boekhouder het vindt: een ontbrekende BTW regel, een dubbele boeking, een refund die niet is teruggedraaid. Die fouten kosten gemiddeld meer tijd om te corrigeren dan het hele handmatige proces voorheen.

De beste koppelingen falen niet voor de duidelijke foutsituaties. Ze falen voor de randgevallen. Een testplan is daar om die randgevallen expliciet te maken voordat je live gaat. Lees voor context ook wat komt kijken bij een API koppeling laten maken.

De vijf soorten tests

1. Functionele tests. Doet de koppeling wat er in het functioneel ontwerp staat? Voor elke datastroom bouw je een set testgevallen en vergelijk je input met output. Dit dekt de gouden pad en de meest gangbare variaties.

2. Randgeval tests. Wat gebeurt er bij 0 euro bedragen, negatieve bedragen, lege velden, extreme tekenlengtes, tekens buiten ASCII, en in grensgevallen rondom tijdzones en seizoenstijd wisselingen?

3. Performance tests. Kan de koppeling jouw piekvolume aan zonder de API limieten van leveranciers te raken? Bij een Stripe of Exact Online koppeling zijn die limieten belangrijk, want wie de limiet raakt krijgt backoff en vertraging.

4. Foutherstel tests. Wat gebeurt er als de externe API een 500 teruggeeft, of halverwege een batch timeout oplevert? Wordt er netjes opnieuw geprobeerd, wordt de fout gelogd en gealarmeerd, en kan de koppeling na herstel verder zonder duplicaten te maken?

5. Reconciliatie. Klopt het eindbeeld in het doelsysteem met het bronsysteem, inclusief aantallen, bedragen en BTW? Dit is de belangrijkste test voor financiële koppelingen.

Checklist: gouden pad

Voor de dagelijkse happy flow minimaal testen:

Nieuwe transactie wordt binnen afgesproken SLA in het doelsysteem aangemaakt.
Alle verplichte velden zijn gevuld en kloppen: bedrag, datum, klant, omschrijving, grootboek, BTW code.
Er wordt geen duplicaat aangemaakt als hetzelfde bron-ID tweemaal binnenkomt.
Een gewone refund of creditnota wordt correct tegengeboekt.
Rapportage en dashboards tonen het nieuwe item zonder handmatig ingrijpen.

Checklist: randgevallen die mensen vergeten

Dit zijn de scenarios die op papier zeldzaam lijken, maar bij echte volumes altijd langskomen:

Valuta en afronding. Transacties in USD of GBP, wisselkoersverschillen, afrondingsregels tussen bron en doel.
BTW situaties. BTW verlegd, gemengde tarieven in één order, 0 procent tarief bij export.
Refunds en terugboekingen. Gedeeltelijke refund, refund na maandafsluiting, refund van een oud tijdperk waar tarieven anders waren.
Tijdzone grenzen. Een transactie die om 23:58 wordt aangemaakt en om 00:02 bij je boekhouding binnenkomt. Valt die in de juiste maand?
Dubbele referenties. Twee klanten met hetzelfde e-mailadres, ordernummers die worden hergebruikt, kvk-nummers die wijzigen.
Uitval van de externe API. Leverancier heeft maintenance, timeout middenin een batch. Wat is de staat na herstel?
Grote hoeveelheden in één batch. 10.000 transacties in één keer doorduwen. Hoe reageert rate limiting?

Je hoeft niet elk randgeval tot de laatste komma af te handelen. Minimaal moet voor elk randgeval gelden: ofwel het werkt, ofwel er komt een alert en de transactie blijft in foutstatus staan zonder duplicaten te veroorzaken.

Performance onder piek

Bij volume gevoelige koppelingen is het niet genoeg om de gemiddelde dag te testen. Vraag jezelf:

Wat is mijn piekdag volume in de laatste 12 maanden? Meestal is dat Black Friday, maandeind of een campagne dag.
Kan de koppeling 3x dat volume aan zonder vertraging?
Wat gebeurt er met de queue als er een tijdelijke hiccup is bij een leverancier?

Een loadtest met historische data is de betrouwbaarste manier om dit te meten. Let vooral op: response tijden, rate limit headers, en of het systeem na de piek binnen redelijke tijd weer bij is.

Reconciliatie: de belangrijkste test voor financiële koppelingen

Voor elke koppeling die bedragen of facturen verplaatst, moet er een reconciliatie rapport zijn. Dat rapport toont per dag:

Aantal items in het bronsysteem versus aantal in het doelsysteem.
Totaalbedrag per groep (inkomsten, BTW, fees, refunds) in bron en doel.
Items die bewust zijn uitgefilterd, met reden.
Items die in een foutstatus staan en wachten op handmatige actie.

Zonder dit rapport kun je niet bewijzen dat je administratie correct is. Met dit rapport wel, en je merkt stille fouten binnen één dag in plaats van tijdens de kwartaalafsluiting.

Hoe lang parallel draaien?

Algemene richtlijnen:

Minimaal twee weken parallel draaien bij koppelingen zonder financiële impact.
Minimaal één volledige maandafsluiting parallel bij financiële koppelingen. Dus als je koppeling op de 5e live zou gaan, wacht tot na de maandafsluiting van die maand.
Bij grote volumes: parallel draaien tot je bronsysteem en doelsysteem drie dagen op rij 100 procent matchen in je reconciliatie rapport.

Parallel draaien kost tijd en aandacht, maar is de goedkoopste verzekering. Een fout in maand één van productie ontdekken kost dagen. Dezelfde fout in een parallel run kost uren.

Wanneer mag je live?

Go criteria die je vooraf vastlegt:

Alle functionele tests groen.
Alle randgevallen of afgehandeld, of met een alert gedekt.
Performance test gehaald op 3x piek volume.
Foutherstel werkt: retry logica, idempotentie, geen duplicaten na herstel.
Reconciliatie rapport: drie opeenvolgende dagen perfect gematcht.
Rollback plan gedocumenteerd voor het geval het misgaat.

Mist een van deze: niet live gaan. Liever een week later dan een maand correcties achteraf.

Veelgestelde vragen

Hoe lang moet ik een API koppeling testen voordat ik live ga? Minimaal twee weken parallel draaien met echte data naast je handmatige proces. Bij financiële koppelingen vaak een volledige maandafsluiting, zodat je ook de reconciliatie hebt geverifieerd.

Moet ik met testdata of productiedata testen? Beide. Functionele tests doe je met testdata in een staging omgeving. Eindvalidatie doe je met echte productiedata in read-only mode of een sandbox van de leverancier, anders ontdek je datadependencies pas bij livegang.

Wat zijn de belangrijkste randgevallen om te testen? Refunds en creditnota's, valuta anders dan euro, BTW verleggen, grensgevallen in de tijdzone rondom middernacht, dubbele transactie nummers, en wat er gebeurt als de externe API een timeout geeft midden in een batch.

Hoe weet ik of de koppeling goed presteert onder piekvolume? Door een loadtest te draaien met het 3x van je normale dagvolume. Kijk naar response tijden, rate limit gedrag bij de leveranciers API en of de queue backlog weer wegloopt na de piek.

Wat moet in het reconciliatie rapport staan? Aantal verwerkte items per dag, verschil tussen bronsysteem en doelsysteem, uitgefilterde items met reden, en alle items die in een foutstatus zijn beland. Zonder dit rapport weet je niet of een stille fout je boekhouding heeft verpest.

Kan ik pas live als alle randgevallen werken? Nee, maar wel met ofwel een afhandeling voor elk randgeval, ofwel een monitor die alarmeert als een onbekend randgeval optreedt. Zeldzame edge cases zoals negatieve valuta kun je ook later oplossen als ze in alert komen.