Documentatie van een integratie: wat leg je vast zodat opvolging later mogelijk is?

Door Clen Mourik

Zonder goede documentatie wordt een systeemkoppeling een black box zodra de bouwer weg is. Wat leg je vast zodat je over 2 jaar nog snapt hoe het werkt — en wat kost het je als je dat niet doet?

Hoeveel uur zou het kosten als je systemen morgen stoppen met praten? Je AFAS-koppeling met Exact Online die orders automatisch doorstuurt, je webshop die voorraad synchroniseert, je werkbon-app die uren registreert — allemaal black boxes zodra de bouwer weg is. Niemand weet meer hoe het werkt. En dan gebeurt er een API-update.

Dat is het moment waarop veel MKB-bedrijven ontdekken dat ze geen documentatie hebben. Geen overzicht van welke systemen met elkaar praten, geen uitleg over hoe de data stroomt, geen contactpersoon meer van de partij die het gebouwd heeft. De koppeling draait al twee jaar probleemloos, dus niemand heeft er meer naar gekeken. Tot hij stopt.

Wat moet je vastleggen bij een integratie zodat opvolging later mogelijk is? En misschien nog belangrijker: wat kost het je als je dat niet doet?

Inhoudsopgave

• Belangrijkste punten
• Waarom integratiedocumentatie geen luxe is
• Wat leg je vast bij een systeemkoppeling
• De technische laag: API, authenticatie en dataflow
• De functionele laag: welk proces ondersteunt de koppeling
• Veelgemaakte fouten bij integratiedocumentatie
• Hoe houd je documentatie actueel
• Wat kost het als je geen documentatie hebt
• Veelgestelde vragen
• Conclusie: een investering die zichzelf terugbetaalt

Belangrijkste punten

Waarom integratiedocumentatie geen luxe is

In 2024 gebruikte 81,5% van het Nederlandse MKB een basisniveau van digitalisering, een stijging van 75% in 2021 (Rijksoverheid). Dat betekent meer softwarepakketten, meer koppelingen, en meer afhankelijkheid van systemen die met elkaar moeten praten.

Het probleem: organisaties gebruiken gemiddeld 1.061 verschillende applicaties, maar slechts 29% daarvan is geïntegreerd (ICTMagazine). De koppelingen die er wel zijn, worden vaak gebouwd zonder dat iemand vastlegt hoe ze werken. Tot er iets misgaat.

Een installatiebedrijf dat we kennen had een koppeling tussen hun werkbon-app en AFAS. Werkte perfect. Tot de app-leverancier een update doorvoerde en de koppeling stilletjes stopte met synchroniseren. Pas na drie weken ontdekte de administratie dat er geen uren meer binnenkwamen. Resultaat: 180 werkbonnen handmatig overtypen, facturen te laat de deur uit, en een boze boekhouder.

Wat ik in de praktijk zie is dat bedrijven pas beseffen dat ze documentatie nodig hebben op het moment dat ze het niet hebben. Dan ben je te laat.

Goede documentatie van een integratie is niet alleen een technisch document voor developers. Het is een verzekeringspolis tegen afhankelijkheid, kennishiaten en onverwachte storingen. En het is de handleiding die ervoor zorgt dat je over twee jaar nog snapt waarom je bepaalde keuzes gemaakt hebt.

Wat leg je vast bij een systeemkoppeling

Een complete integratiedocumentatie bestaat uit drie lagen: de technische laag, de functionele laag, en de organisatorische laag. Alle drie zijn nodig. Een document dat alleen API-endpoints beschrijft is voor een beheerder zinloos. Een document dat alleen het bedrijfsproces beschrijft helpt de developer niet als er een fout opgelost moet worden.

De drie lagen van integratiedocumentatie

Neem een groothandel die orders van hun webshop automatisch naar hun boekhoudpakket stuurt. De technische laag beschrijft dat er een REST API gebruikt wordt met OAuth 2.0, dat de koppeling elke 5 minuten nieuwe orders ophaalt, en dat het klant-ID uit de webshop gemapt wordt op het debiteurnummer in de boekhouding.

De functionele laag legt uit dat deze koppeling het orderproces ondersteunt, dat alleen orders met status "betaald" worden doorgezet, en dat er een controle zit op dubbele orders. De organisatorische laag vertelt wie de beheerder is, waar de API-keys staan, en dat de webhostingpartij een SLA heeft van 99,5% uptime.

Zonder die drie lagen is je documentatie onvolledig. En onvolledige documentatie is net zo gevaarlijk als geen documentatie.

De technische laag: API, authenticatie en dataflow

De technische documentatie is het deel dat een developer of systeembeheerder nodig heeft om de koppeling te begrijpen, te onderhouden of te repareren. Dit is wat er minimaal in moet staan:

• Systeemnamen en versies: Welke systemen zijn gekoppeld en welke API-versie wordt gebruikt. "AFAS Profit REST API v2" is veel nuttiger dan "de AFAS-koppeling".
• Authenticatiemethode: OAuth 2.0, API-key, HMAC? En waar zijn de credentials opgeslagen (wachtwoordmanager, Azure Key Vault)?
• Endpoints en veldmapping: Welke API-endpoints worden aangeroepen en welk veld uit systeem A wordt welk veld in systeem B?
• Dataflow-diagram: Een visualisatie van hoe data stroomt. Welk systeem is de "master" (de versie van de waarheid) en welk systeem volgt?
• Triggermoment: Realtime via webhook, polling (elke X minuten), of batch ('s nachts om 02:00)?
• Error handling: Wat gebeurt er als de API een fout teruggeeft? Wordt er geretried? Krijgt iemand een melding?
• Rate limits: Hoeveel API-calls mag je per uur/dag doen voordat je een 429-error krijgt?
• Logging en monitoring: Waar worden foutmeldingen vastgelegd en wie krijgt een alert bij een storing?

Een voorbeeld uit de praktijk: een productiebedrijf had een koppeling tussen hun productie-app en Exact Online voor materiaalverbruik. De app stuurde elke avond een batch met verbruikte materialen door. Wat niemand had gedocumenteerd: de API had een limiet van 100 regels per call. Op een drukke dag werden er 120 artikelen verbruikt. De koppeling crashte, maar gaf geen foutmelding. Pas drie weken later viel het op dat de voorraadstanden niet klopten.

Bij een klant van ons zagen we dat een ongedocumenteerde API-limiet wekenlang stille fouten produceerde. De voorraad was 15% te hoog geboekt omdat overschrijdingen niet werden doorgezet.

Technische documentatie hoeft geen roman te zijn. Een gestructureerd document met alle relevante technische details, aangevuld met een dataflow-diagram, is vaak genoeg. Het gaat erom dat iemand die de koppeling niet gebouwd heeft toch kan begrijpen hoe hij werkt.

Meer over hoe verschillende systemen met elkaar samenwerken vind je op onze pagina over systeemintegraties.

De functionele laag: welk proces ondersteunt de koppeling

De meest voorkomende fout in integratiedocumentatie is dat er alleen techniek wordt vastgelegd. Een document vol endpoints en authenticatiemethodes is voor een proces-eigenaar of functioneel beheerder nutteloos. Die wil weten: welk probleem lost deze koppeling op? Welke business rules zijn verwerkt? Wat moet er gebeuren als er iets fout gaat?

De functionele laag beschrijft het waarom achter de koppeling. Neem een bouwbedrijf dat werkbonnen via een mobiele app registreert en die automatisch doorzet naar hun projectadministratie in AFAS. De technische documentatie vertelt hoe de API werkt. De functionele documentatie legt uit:

• Dat deze koppeling het urenregistratieproces ondersteunt
• Dat alleen afgeronde werkbonnen worden doorgezet (status "goedgekeurd")
• Dat uren worden toegewezen aan een projectnummer uit AFAS
• Dat materiaalverbruik in een apart veld wordt vastgelegd voor nacalculatie
• Dat de koppeling realtime werkt, zodat de projectleider direct inzicht heeft in gewerkte uren

Zonder die functionele context is de koppeling een black box. Als een nieuwe medewerker de beheerrol overneemt, snapt die niet waarom bepaalde keuzes gemaakt zijn. Waarom worden uren pas doorgezet na goedkeuring? Omdat de projectleider anders geen grip heeft op foutieve registraties. Waarom realtime en niet 's nachts in een batch? Omdat het bouwbedrijf anders pas de volgende dag ziet hoeveel uren er op een project zijn gemaakt.

Business rules vastleggen

Elke integratie bevat business rules: voorwaarden waaronder data wel of niet wordt doorgezet. Die rules moeten expliciet vastgelegd worden. Een paar voorbeelden:

• Een webshop stuurt alleen orders door naar de boekhouding als de betaling is ontvangen
• Een CRM-koppeling maakt alleen een nieuwe relatie aan in de boekhouding als het adres compleet is (straat, huisnummer, postcode, plaats)
• Een voorraadkoppeling synchroniseert alleen artikelen met een voorraad > 0
• Een facturatiekoppeling past automatisch BTW-percentage aan op basis van land van levering

Als die rules niet gedocumenteerd zijn, ontstaan er vragen zodra de koppeling zich anders gedraagt dan verwacht. "Waarom wordt deze order niet doorgezet?" "Omdat de betaling nog niet binnen is, staat in de business rules van de koppeling." Zonder documentatie kost zo'n vraag een uur zoeken. Met documentatie is het antwoord in 30 seconden gevonden.

Meer voorbeelden van procesautomatisering vind je in onze klantverhalen.

Veelgemaakte fouten bij integratiedocumentatie

Sommige fouten zien we keer op keer terugkomen bij bedrijven die hun integraties laten documenteren. Vaak pas nadat er iets fout is gegaan.

Fout 1: Alleen de techniek documenteren

Een document vol API-endpoints en JSON-voorbeelden is nutteloos voor de bedrijfsvoering. Zonder functionele context snapt niemand waarom de koppeling er is en welk proces hij ondersteunt. De koppeling werkt, maar niemand weet meer wat hij doet.

Fout 2: Documentatie schrijven voor de verkeerde doelgroep

Een integratiedocument geschreven vanuit managementperspectief ("deze koppeling bespaart 10 uur per week") helpt de beheerder niet die de koppeling moet onderhouden. Een document vol technisch jargon helpt de proces-eigenaar niet die moet begrijpen wat er gebeurt als er een fout optreedt. Schrijf voor beide doelgroepen, of maak twee documenten.

Fout 3: Documentatie wordt nooit bijgewerkt

Een integratiedocument van twee jaar geleden is vaak misleidender dan geen document. API's worden geüpdatet, systemen veranderen, business rules worden aangepast. Als de documentatie niet mee-evolueert, klopt er niks meer van. Maak afspraken over wie de documentatie bijwerkt en wanneer.

Fout 4: De koppeling bouwen voordat het proces beschreven is

We zien het regelmatig: een bedrijf wil een integratie en begint direct met bouwen. Pas achteraf blijkt dat het onderliggende proces helemaal niet gestandaardiseerd is. Resultaat: de koppeling automatiseert chaos. Eerst het proces beschrijven en optimaliseren, dan pas automatiseren.

Fout 5: Geen logging of alerting vastleggen

Stille fouten zijn het grootste risico bij integraties. Orders die niet worden doorgezet, voorraadstanden die niet kloppen, facturen die ontbreken. Zonder logging en alerting ontdek je dat pas weken later. In de documentatie moet staan: waar worden fouten gelogd, wie krijgt een melding bij een storing, en hoe vaak wordt de log gecontroleerd.

Slechte datakwaliteit kost het Nederlandse bedrijfsleven €20 miljard per jaar (Techzine). Een groot deel daarvan komt door ongedocumenteerde integraties die stille fouten produceren.

Fout 6: Point-to-point koppelingen zonder overzicht

Elk systeem heeft een eigen koppeling met elk ander systeem. Na een paar jaar heb je 20 koppelingen die door verschillende partijen zijn gebouwd. Niemand heeft overzicht. Eén wijziging in een systeem breekt drie koppelingen. Dit heet integration spaghetti. Voorkom dit door een centraal overzicht te houden van alle actieve koppelingen en hun onderlinge afhankelijkheden.

Bekijk onze pagina over populaire integratiecombinaties voor voorbeelden van veelvoorkomende koppelingen.

Hoe houd je documentatie actueel

Een integratiedocument is geen eenmalig klusje. Het moet groeien met de organisatie. Maar hoe zorg je ervoor dat documentatie actueel blijft zonder dat het een administratieve last wordt?

Maak documentatie-onderhoud onderdeel van het wijzigingsproces

Elke keer dat er iets verandert aan de integratie, moet de documentatie worden bijgewerkt. Maak het een gewoonte: geen productie-release zonder documentatie-update. Dit voorkomt dat de documentatie achterloopt.

Wijs een eigenaar aan

Iemand moet verantwoordelijk zijn voor de documentatie. Dat hoeft geen developer te zijn. Een functioneel beheerder of applicatiebeheerder kan prima de eigenaar zijn van het document. Zorg wel dat die persoon toegang heeft tot de juiste bronnen en weet waar de documentatie staat.

Review de documentatie periodiek

Plan elk half jaar een moment in om alle integratiedocumentatie door te lopen. Klopt alles nog? Zijn er koppelingen bijgekomen of verdwenen? Zijn contactpersonen nog actueel? Een halve dag per jaar investeren in een documentatie-check bespaart veel hoofdpijn als er iets fout gaat.

Gebruik versiebeheer

Sla documentatie op in een systeem met versiebeheer (bijvoorbeeld een wiki, Notion, of gewoon een gedeelde map met duidelijke versienummering). Zo kun je altijd terugkijken naar een eerdere versie als dat nodig is.

Wat kost het als je geen documentatie hebt

De kosten van slecht gedocumenteerde integraties zijn lastig te meten, omdat ze vaak verborgen blijven. Tot het misgaat.

Herbouw kost 3-5x meer

Als een koppeling stopt en niemand weet meer hoe hij werkt, moet je hem opnieuw bouwen. Of reverse-engineeren, wat nog duurder is. Een koppeling die oorspronkelijk €2.000 kostte om te bouwen, kost €6.000-€10.000 om te herbouwen zonder documentatie. Simpelweg omdat je eerst moet uitzoeken hoe het oorspronkelijk werkte.

Afhankelijkheid van de oorspronkelijke bouwer

Zonder documentatie ben je afhankelijk van de persoon of het bedrijf dat de koppeling gebouwd heeft. Als die niet meer beschikbaar is, zit je vast. We zien dat regelmatig: een ZZP'er die de webshop-koppeling bouwde is gestopt, en niemand snapt hoe de koppeling werkt. Resultaat: vendor lock-in en hoge onderhoudskosten.

Verloren productiviteit door stille fouten

Stille fouten zijn het gevaarlijkst. Een koppeling die stilletjes stopt met synchroniseren, of die foutieve data doorstuurt zonder waarschuwing. Pas weken later ontdek je dat orders ontbreken, voorraad niet klopt, of facturen niet zijn verzonden. De tijd die het kost om die fouten op te sporen en te herstellen kan oplopen tot tientallen uren.

Slechts 35% van de Nederlandse organisaties heeft een volledig overzicht van de IT-kosten (Techzine). Een groot deel van die verborgen kosten zit in slecht gedocumenteerde integraties.

Rekenvoorbeeld: een webshop zonder documentatie

Stel: een webshop met 100 orders per dag heeft een koppeling tussen de webshop en het boekhoudpakket. Die koppeling stopt door een API-update. Zonder documentatie duurt het 3 dagen om uit te zoeken wat er mis is en het op te lossen. In die tijd moeten orders handmatig worden verwerkt: 100 orders x 3 minuten per order x 3 dagen = 900 minuten = 15 uur handmatig werk. Bij €40/uur is dat €600 aan loonkosten. Plus de kosten van de developer die het moet oplossen.

Met goede documentatie had de storing in een paar uur opgelost kunnen worden. De investering in documentatie betaalt zichzelf terug bij de eerste storing.

Wil je weten wat een integratie voor jouw situatie kan opleveren? Neem een kijkje bij onze branche-specifieke oplossingen.

Veelgestelde vragen

Moet ik alle integraties documenteren, ook de simpele?

Ja. Ook een simpele koppeling kan problemen veroorzaken als niemand meer weet hoe hij werkt. De documentatie hoeft niet ingewikkeld te zijn — een A4'tje met de belangrijkste technische en functionele details is vaak al genoeg.

Wie moet de integratiedocumentatie schrijven?

Bij voorkeur de partij die de koppeling bouwt. Maak het onderdeel van de opdracht: geen oplevering zonder documentatie. Als je achteraf documenteert, kost het meer tijd omdat je dingen moet reconstrueren.

In welk format bewaar ik integratiedocumentatie het beste?

Dat hangt af van je organisatie. Een wiki of kennisbank (zoals Notion, Confluence) werkt goed omdat je gemakkelijk kunt zoeken en versies kunt bijhouden. Een gedeelde map met Word- of PDF-bestanden kan ook, zolang er duidelijke afspraken zijn over naamgeving en versiebeheer.

Hoe vaak moet ik integratiedocumentatie updaten?

Bij elke wijziging aan de integratie. En minimaal een keer per half jaar een volledige check of alles nog klopt. Zet het in je agenda, anders gebeurt het niet.

Wat als de leverancier weigert documentatie aan te leveren?

Dan heb je een probleem. Goede leveranciers leveren standaard documentatie aan. Als een partij weigert, is dat een red flag. Je wordt afhankelijk van die partij en hebt geen grip op je eigen systemen. Overweeg een andere leverancier.

Kan ik integratiedocumentatie laten maken door een externe partij?

Ja, als de bestaande documentatie ontbreekt of verouderd is, kun je een externe partij inhuren om de integraties te analyseren en te documenteren. Dat kost tijd en geld, maar geeft je wel grip terug op je systemen.

Wat zijn de kosten van het laten documenteren van een integratie?

Dat hangt af van de complexiteit. Voor een simpele koppeling tussen twee systemen kun je uitgaan van 4-8 uur werk. Voor een complexere integratie met meerdere systemen en business rules kan dat oplopen tot 16-24 uur. Reken op €75-€125 per uur, afhankelijk van het niveau van de specialist.

Conclusie: een investering die zichzelf terugbetaalt

Integratiedocumentatie voelt als een kostenpost zonder directe waarde. Tot je het nodig hebt. En dan blijkt het de beste investering die je kon doen.

Goede documentatie maakt je onafhankelijk van de bouwer, geeft grip op je IT-landschap, en voorkomt dat een integratie een black box wordt. Het bespaart tijd bij storingen, maakt opvolging mogelijk, en zorgt ervoor dat kennis niet verdwijnt als iemand vertrekt.

De kosten van documentatie zijn overzichtelijk: een paar uur werk per integratie. De kosten van geen documentatie zijn onvoorspelbaar en vaak veel hoger: herbouw, afhankelijkheid, stille fouten, verloren productiviteit.

Begin klein. Als je vandaag één integratie documenteert, ben je al verder dan de meeste MKB-bedrijven. Maak er een gewoonte van. Elke nieuwe koppeling komt met documentatie. Elke wijziging wordt vastgelegd. Over een jaar heb je een compleet overzicht van je IT-landschap en kun je met een gerust hart schakelen tussen leveranciers.

Wil je weten hoe wij bij SyncIT integraties bouwen én documenteren? Of heb je bestaande koppelingen die je graag gedocumenteerd wil zien? Plan een vrijblijvend gesprek en we kijken samen naar wat er nodig is om grip te krijgen op je systemen.