Versiebeheer van API's: wat als een leverancier zijn koppeling verandert?

Door Clen Mourik

Je koppeling werkt perfect. Tot de leverancier ineens een nieuwe API-versie uitrolt en je systemen niet meer met elkaar praten. Hoe bescherm je jezelf tegen deze versie-wijzigingen?

Je opent maandagochtend je laptop. De koppeling tussen je magazijnsysteem en je vervoerder heeft de hele nacht doorgedraaid zonder labels te printen. 127 orders wachten. Handmatig werk voor de komende uren.

De oorzaak? De leverancier heeft zijn API aangepast. Een veldnaam veranderd, een endpoint hernoemd. De koppeling die al twee jaar perfect draaide, werkt ineens niet meer. Dit gebeurt vaker dan je denkt — en de meeste MKB-bedrijven merken het pas als het te laat is.

In dit artikel leg ik uit hoe API-versiebeheer werkt, waarom leveranciers hun koppelingen aanpassen, en vooral: hoe je jezelf beschermt tegen onverwachte uitval. Met concrete voorbeelden uit de bouw, groothandel en productie.

Inhoudsopgave

• Belangrijkste punten
• Waarom leveranciers hun API-versies wijzigen
• Wat er misgaat: praktijkvoorbeelden uit het MKB
• Hoe API-versiebeheer technisch werkt
• Vijf fouten die je geld kosten
• Beschermingslagen: middleware en iPaaS
• Wat vraag je je leverancier of koppelingsbouwer?
• Veelgestelde vragen

Belangrijkste punten

Waarom leveranciers hun API-versies wijzigen

Softwareleveranciers zitten niet stil. Ze ontwikkelen nieuwe functies, verbeteren beveiliging, en optimaliseren hun techniek. Dat betekent dat de API — het toegangspunt waarmee jouw systemen met hun software praten — regelmatig aangepast wordt.

Volgens Redocly's API-versiebeheer best practices zijn breaking changes onvermijdelijk bij significante functionaliteitswijzigingen. Een breaking change is een aanpassing die bestaande koppelingen kan verstoren: het verwijderen van een endpoint, het hernoemen van een veld, of het wijzigen van een datastructuur.

Een voorbeeld uit de praktijk: e-Boekhouden zette de oude SOAP-API per 1 januari 2026 uit. Elke koppeling die nog op de oude methode draaide, moest over naar de REST API met een API-sleutel. Bedrijven die dit niet tijdig oppikten, stonden op 1 januari met een volledig stille boekhoudkoppeling.

Nieuwe versies zijn vaak een verbetering

Laten we eerlijk zijn: de meeste API-updates zijn inhoudelijk een vooruitgang. Betere beveiliging, snellere response-tijden, meer mogelijkheden. Het probleem zit hem niet in de update zelf, maar in de overgang.

Als een leverancier zijn API vernieuwt maar de oude versie nog een jaar ondersteunt, heb je alle tijd om rustig te migreren. Maar veel MKB-bedrijven weten niet dat ze iets moeten doen — tot de oude versie wordt uitgezet.

Wat er misgaat: praktijkvoorbeelden uit het MKB

Groothandel met magazijnkoppeling: Picqer en Sendcloud

Een webwinkel met 300-500 orders per dag gebruikt Picqer voor voorraadbeheer en Sendcloud voor verzending. De koppeling maakt automatisch verzendlabels aan zodra een order wordt ingepakt.

Sendcloud wijzigt de structuur van het parcel-endpoint: het veld "recipient_name" wordt hernoemd naar "receiver". De koppeling stuurt nog steeds data naar het oude veldnaam. Resultaat: geen labels, geen verzendingen, oplopende backlog.

Bij 400 orders per dag en 8 minuten handmatig werk per order kom je uit op ruim 53 uur extra werk — meer dan een volledige werkweek voor één medewerker. Dat is niet alleen kostbaar, het verstoort je hele planning.

Bouwbedrijf met urenregistratie: AFAS en externe planning

Een bouwbedrijf met 75 medewerkers gebruikt AFAS Profit voor HR en salaris, gekoppeld aan een planningsapplicatie voor projecturen. Monteurs registreren hun uren in de planning-app, die ze via de AFAS UpdateConnector naar de salarisadministratie stuurt.

AFAS past de veldstructuur van de UpdateConnector aan. De koppeling verstuurt nog data, maar AFAS accepteert ze niet meer. Geen foutmelding, geen crash — gewoon stilte. Pas bij de salarisverwerking blijkt dat drie weken aan uren ontbreken.

Zoals Brixxs terecht opmerkt: veel AFAS-koppelingen mislukken niet op bereikbaarheid, maar op onduidelijke afspraken over velden en uitzonderingen. Dat maakt versiewijzigingen extra risicovol.

Accountantskantoor met factuurkoppeling: Exact Online

Een accountantskantoor verwerkt facturen van klanten automatisch via een koppeling tussen hun portaal en Exact Online. Elke factuur die via het klantportaal binnenkomt, verschijnt automatisch in de boekhouding.

Exact Online introduceert een nieuwe authenticatiemethode en faset de oude OAuth-flow uit. De koppeling krijgt geen toegang meer en facturen verdwijnen in een digitaal zwart gat. Omdat niemand actief controleert of alle facturen aankomen, duurt het weken voordat het probleem opvalt.

Wat ik in de praktijk zie: bedrijven testen hun koppeling vaak alleen bij de start. Daarna draait hij 'vanzelf' — tot het moment dat het niet meer vanzelf gaat.

Hoe API-versiebeheer technisch werkt

API-versiebeheer draait om één kernvraag: hoe kunnen leveranciers hun API verbeteren zonder bestaande koppelingen te breken?

De meeste leveranciers gebruiken URI-versioning: het versienummer staat in de URL. Een voorbeeld:

• Oude versie: https://api.leverancier.nl/v1/orders
• Nieuwe versie: https://api.leverancier.nl/v2/orders

Zolang beide endpoints blijven bestaan, werkt je koppeling gewoon door. Maar zodra de leverancier v1 uitzet, moet je overschakelen naar v2. En dat vergt aanpassingen in je code.

Semantic versioning: de taal van API's

Veel leveranciers hanteren semantic versioning: MAJOR.MINOR.PATCH (bijvoorbeeld 2.4.1). De logica:

• MAJOR (2.0.0): breaking changes, bestaande koppelingen kunnen breken
• MINOR (2.4.0): nieuwe features, backwards compatible
• PATCH (2.4.1): bugfixes, geen impact op functionaliteit

Een MINOR-update hoef je vaak niet direct door te voeren. Een MAJOR-update wél — en daar zit het risico.

Deprecation: de aankondiging van het einde

Wanneer een leverancier een oude API-versie gaat uitfaseren, heet dat deprecation. Best practice volgens Redocly is een tijdlijn van 18-24 maanden:

Het probleem: deze communicatie gaat vaak alleen naar developers of API-gebruikers die zich hebben aangemeld voor updates. Als je koppeling is gebouwd door een externe partij en je hebt geen toegang tot de changelog, mis je de aankondiging.

Vijf fouten die je geld kosten

1. Geen eigenaar voor koppelingsbeheer

De grootste fout: niemand is verantwoordelijk voor het monitoren van API-wijzigingen. De koppeling werkt, dus niemand kijkt ernaar om. Tot hij niet meer werkt.

Wijs één persoon aan — intern of extern — die changelogs en developer-updates volgt. Dat hoeft geen fulltime baan te zijn, maar het moet wél gebeuren.

2. Hardcoded versienummers zonder flexibiliteit

Als je koppeling het versienummer hardcoded in de URL heeft staan (/api/v1/orders), moet je bij elke major update de code aanpassen. Beter: maak het versienummer configureerbaar, zodat je met een instelling kunt omschakelen.

Nog beter: gebruik een integratielaag (iPaaS of middleware) die versie-routing automatisch afhandelt.

3. Geen testomgeving beschikbaar

Veel leveranciers bieden een sandbox-omgeving waar je nieuwe API-versies kunt testen zonder impact op productie. Gebruik die. Test je migratie eerst in de sandbox, controleer of alles werkt, en schakel dan pas over in productie.

Zonder sandbox test je in productie — en dat betekent dat je klanten je proefkonijnen zijn.

4. Volledige afhankelijkheid van één externe bouwer

Je laat een externe partij een koppeling bouwen. Prima. Maar zorg dat je de code in eigen beheer hebt, documentatie krijgt, en afspraken maakt over onderhoudscontracten.

Als de bouwer verdwijnt of niet meer reageert, wil je niet maandenlang vast zitten met een koppeling die je niet zelf kunt aanpassen.

5. Geen monitoring of alerting

Een koppeling die stilletjes stopt met werken is gevaarlijker dan een koppeling die crasht. Bij een crash krijg je een foutmelding. Bij stille fouten merk je pas na dagen of weken dat data ontbreekt.

Richt monitoring in die controleert of de koppeling nog data uitwisselt. Een simpele dagelijkse check: zijn er vandaag orders gesynchroniseerd? Zijn facturen aangemaakt? Zo niet, stuur dan een alert.

Bij een klant van ons bleek drie weken aan urenregistratie niet te zijn doorgekomen naar de salarisadministratie. Geen crash, geen foutmelding — gewoon stilte. Dat had met een simpele monitor voorkomen kunnen worden.

Beschermingslagen: middleware en iPaaS

De vraag is niet of een leverancier zijn API gaat aanpassen, maar hoe je jezelf beschermt tegen de impact. Daar zijn verschillende strategieën voor, elk met eigen voor- en nadelen.

Directe koppeling: simpel maar kwetsbaar

Bij een directe (point-to-point) koppeling praat systeem A rechtstreeks met systeem B via de API. Geen tussenlaag, geen extra complexiteit. Dat is goedkoop en overzichtelijk bij de start.

Nadeel: elke API-wijziging van de leverancier raakt direct jouw koppeling. Geen bufferlaag, geen automatische migratie. Jij — of je bouwer — moet handmatig ingrijpen.

iPaaS: laat het platform het werk doen

Platforms zoals Make, n8n, Zapier of Workato fungeren als tussenlaag. Je bouwt je koppeling met de connectoren van het platform. Als de leverancier zijn API wijzigt, past het iPaaS-platform zijn connector aan — en jouw koppeling blijft werken.

Voordeel: minder beheer, ingebouwde monitoring, snellere implementatie. Voor Exact Online is een iPaaS vaak binnen een dag werkend. Voor AFAS moet je meer tijd reserveren om de connectors te bouwen.

Nadeel: maandelijkse kosten en een nieuwe afhankelijkheid. Je bent nu afhankelijk van zowel de softwareleverancier als het iPaaS-platform.

API Gateway: enterprise-controle

Een API Gateway (zoals MuleSoft, Azure API Management of AWS API Gateway) is een eigen tussenlaag die je zelf beheert. De gateway handelt authenticatie, versie-routing en monitoring af.

Voordeel: volledige controle, hoge schaalbaarheid, enterprise-grade beveiliging. Nadeel: hoge initiële investering en technische kennis vereist. Voor de meeste MKB-bedrijven niet proportioneel.

Wat past bij jouw situatie?

Meer informatie over verschillende integratiestrategieën vind je in ons kennisbank-overzicht, waar we dieper ingaan op wanneer welke aanpak past.

Wat vraag je je leverancier of koppelingsbouwer?

Of je nu een externe partij inschakelt of zelf aan de slag gaat: stel de juiste vragen voordat je begint.

Vragen voor je softwareleverancier

• Hoe communiceren jullie API-wijzigingen? (Changelog, nieuwsbrief, dashboard?)
• Wat is jullie deprecation-beleid? (Hoeveel tijd tussen aankondiging en sunset?)
• Bieden jullie een sandbox-omgeving voor testen?
• Zijn er webhook-notificaties beschikbaar bij API-downtime?
• Waar vind ik de release notes en migratie-handleidingen?

Vragen voor je koppelingsbouwer

• Wie volgt de changelogs van de leveranciers die we gebruiken?
• Wat gebeurt er als een API-versie wordt uitgefaseerd? Wie past de koppeling aan?
• Krijg ik de broncode en documentatie in eigen beheer?
• Is er monitoring ingebouwd die mij waarschuwt bij storingen?
• Hoe testen we nieuwe versies voordat ze live gaan?

Deze vragen lijken misschienbasaal, maar veel koppelingen lopen vast omdat deze afspraken nooit expliciet zijn gemaakt. Bekijk ook onze klantverhalen om te zien hoe andere bedrijven dit hebben aangepakt.

Veelgestelde vragen

Hoe weet ik of mijn leverancier zijn API gaat wijzigen?

De meeste leveranciers communiceren dit via hun developer-portal, changelog of nieuwsbrief. Schrijf je in voor deze updates of vraag je koppelingsbouwer dit actief te monitoren. Bij grote leveranciers zoals AFAS, Exact Online en Sendcloud kun je je aanmelden voor API-updates.

Wat kost het om een koppeling aan te passen na een API-wijziging?

Dat hangt af van de complexiteit van de wijziging. Een simpele veldnaam-aanpassing kan binnen een uur gefikst zijn. Een volledige migratie naar een nieuwe authenticatiemethode of datastructuur kan dagen tot weken kosten. Gemiddeld rekenen we 4-16 uur voor een standaard API-migratie.

Kan ik een koppeling 'toekomstbestendig' maken?

Volledig toekomstbestendig bestaat niet — software blijft evolueren. Maar je kunt het risico beperken door te werken met versie-agnostische architectuur, configureerbare endpoints in plaats van hardcoded URLs, en een integratielaag die versie-routing afhandelt.

Wat is het verschil tussen SOAP en REST API's bij AFAS?

AFAS biedt beide: REST communiceert in JSON, SOAP in XML. Functioneel bieden ze dezelfde mogelijkheden. REST is moderner en flexibeler, SOAP wordt nog gebruikt door oudere systemen. Bij nieuwe koppelingen raden we REST aan — tenzij je legacy-systemen hebt die alleen SOAP ondersteunen.

Hoe vaak moet ik mijn koppeling testen?

Minimaal bij elke aangekondigde API-wijziging van je leverancier, maar idealiter ook periodiek (bijvoorbeeld elk kwartaal) om te controleren of alles nog werkt zoals verwacht. Automatische monitoring helpt om problemen tussen testen door te detecteren.

Wat als mijn externe bouwer niet meer bereikbaar is?

Daarom is het cruciaal om de broncode, documentatie en API-credentials in eigen beheer te hebben. Vraag dit expliciet bij de start van het project. Als je nu vastzit zonder toegang, neem dan contact op — we helpen regelmatig bedrijven met het overnemen en documenteren van bestaande koppelingen.

Grip krijgen op je koppelingen

API-versiebeheer klinkt technisch, maar komt neer op een simpele vraag: wat gebeurt er als een leverancier zijn software aanpast? Heb je daar grip op, of word je verrast?

De bedrijven die hier goed op voorbereid zijn, hebben drie dingen geregeld: iemand die changelogs monitort, een testomgeving om wijzigingen te controleren, en heldere afspraken over wie wat doet. Dat hoeft geen complex IT-landschap te zijn — het begint bij bewustzijn.

Volgens het CBS investeerden Nederlandse bedrijven in 2024 35,5 miljard euro in ICT. Een flink deel daarvan gaat naar software en koppelingen. Zonde als die investering wegvalt omdat een API-wijziging niet tijdig werd opgepikt.

Wil je weten hoe jouw huidige koppelingen ervoor staan? Of heb je vragen over het beschermen van je integraties tegen toekomstige wijzigingen? Plan dan een vrijblijvend adviesgesprek. We kijken met je mee naar je huidige situatie en geven concrete handvatten — geen verkooppraatje, gewoon eerlijk advies.