API-documentatie: standaarden en checklist voor betaal-API's
2026-07-15
Maandagochtend. Een partnerteam wil koppelen met je betaal-API, de business wacht op de eerste testrun, en de eerste Slack-thread gaat niet over de logica maar over een banale vraag: welk veld is verplicht, welk optioneel, en hoe ziet een nette foutmelding eruit? Op dat moment blijkt of je documentatie alleen “bestaat” of echt werkt.
In een gereguleerde omgeving als fintech is slechte API-documentatie geen cosmetisch probleem. Ze levert vragen op, rekt integraties op, vertraagt goedkeuringen en vergroot de kans dat een correct gebouwde client struikelt over een verkeerd begrepen detail. Bij SEPA-processen komt daar nog bij dat formaatgrenzen, validatieregels en vakjargon samenkomen.
Goede standaarden voor API-documentatie lossen dat op. Ze geven ontwikkelaars, technisch schrijvers, productteams, compliance en externe integrators één gemeenschappelijke taal. Het gaat er niet alleen om dat er een OpenAPI-bestand is, maar dat de documentatie volledig, consistent, testbaar en actueel blijft.
Waarom goede API-documentatie het verschil maakt
Veel teams merken pas onder druk hoe duur zwakke documentatie is. De API is technisch stabiel, maar de integratie loopt vast: niet door ontbrekende endpoints, maar door onduidelijke authenticatie, onvolledige voorbeeldpayloads, ontbrekende foutgevallen of verouderde beschrijvingen.
De grootste wrijving zit zelden in het happy path. Ze zit op de plek waar een ontwikkelaar snel moet beslissen: wat gebeurt er bij een ongeldig IBAN, een onvolledige machtiging, een verouderd bestandsformaat of een verkeerde veldkoppeling? Geeft de documentatie daar geen duidelijk antwoord op, dan bouwt elk partnerteam zijn eigen interpretatie. Dan ontstaan supporttickets en schaduwlogica.
De gevolgen:
- meer vragen over velden, formaten en authenticatie;
- foutieve implementaties, omdat integrators standaardwaarden of foutcodes anders lezen;
- riskante releases, die live gaan voordat changelog en voorbeelden zijn bijgewerkt;
- een slechte ontwikkelaarservaring: een functioneel goede API voelt toch “lastig”.
Vuistregel: komt dezelfde integratievraag twee keer bij support binnen, dan ontbreekt het antwoord in de documentatie of is het te moeilijk te vinden.
Er bestaat geen wettelijk voorgeschreven standaard voor API-documentatie. In de praktijk volgen de meeste publieke en private aanbieders de OpenAPI-specificatie: niet omdat een auditor erom vraagt, maar omdat een schone specificatie de enige robuuste basis is voor consistentie, tooling en beheer.
Specificaties: OpenAPI, AsyncAPI of RAML
Robuuste documentatie begint bij een machineleesbare specificatie, niet bij een HTML-pagina die achteraf wordt bijgewerkt. De specificatie legt paden, methodes, parameters, schema’s, authenticatie en foutmodellen vast. In de betaalwereld is dat de werkbasis voor reviews, validatie, tests en goedkeuringen.
| Criterium | OpenAPI (Swagger) | AsyncAPI | RAML |
|---|---|---|---|
| Primair gebruik | REST-API’s, synchrone communicatie | Event-gedreven en asynchrone API’s | REST-API’s met nadruk op ontwerp |
| Formaten | JSON en YAML | JSON en YAML | YAML |
| Tooling | Zeer breed: UI, mocking, validatie | Goed voor messaging en events | Degelijk, maar kleiner |
| Geschikt voor SEPA-REST-API’s | Zeer goed | Alleen als aanvulling | Mogelijk, zelden eerste keus |
| Sterk punt | Standaardisatie, interoperabiliteit, automatisering | Events en berichtstromen beschrijven | Leesbaarheid en modelgedreven ontwerp |
Voor REST-API’s in de financiële sector is OpenAPI de norm. Een veld is daar zelden “gewoon een string”: het heeft formaatregels, lengtebeperkingen en effect op het proces. Wie JSON omzet naar pain.001 of pain.008, moet die regels precies vastleggen, en vrije tekst is daarvoor niet genoeg. OpenAPI werkt met tools als Swagger UI, Redoc, mockservers, contracttests en SDK-generatoren, en laat zich koppelen aan linting en CI-controles.
AsyncAPI past wanneer integraties via events lopen: statusberichten uit een verwerkingspijplijn of batchresultaten via een queue. RAML is interessant voor teams die sterk modelgedreven ontwerpen, maar levert in een OpenAPI-omgeving vaak extra vertaalwerk op.
De praktische regel: gebruik OpenAPI voor het synchrone contract en voeg AsyncAPI alleen toe waar events echt gedocumenteerd moeten worden. Als aanvulling, niet als vervanging.
De onderdelen van goede API-documentatie
Een specificatie alleen beantwoordt niet de vragen die integrators dagelijks hebben. Goede documentatie combineert referentie, onboarding, context en beheerkennis.
Introductie en snelstart
Leg eerst in heldere zinnen uit waarvoor de API dient: betalingen aanmaken, bestanden valideren, conversies starten of status opvragen. Daarna een korte route naar het eerste succes: toegangsvoorwaarden begrijpen, authenticatie instellen, een eerste request sturen, een geslaagde response lezen en een typische fout herkennen.
Authenticatie en autorisatie
“API-key” of “OAuth” noemen is niet genoeg. Ontwikkelaars moeten weten waar ze de credentials meegeven, welke scopes of rollen gelden, hoe lang tokens geldig zijn en hoe test- en productietoegang gescheiden zijn. Beschrijf ook welke fouten optreden bij ontbrekende of ongeldige autorisatie.
Endpoints, datamodellen en foutbeelden
Elk endpoint heeft een doel, methode, pad, parameters, headers, request- en responseschema en voorbeelden nodig, zowel geslaagd als mislukt. In de betaalwereld zijn foutgevallen geen voetnoot maar de kern van de integratie. Goede documentatie heeft daarnaast uitvoerbare codevoorbeelden in meerdere talen, interactieve testmogelijkheden en toegankelijke opmaak.
Wat vaak ontbreekt: gebruiksscenario’s. Voor een SEPA-API wil een ontwikkelaar niet alleen velddefinities, maar ook de volgorde van validatie, conversie, statusopvraag en foutafhandeling. En een bijgehouden changelog met versiespecifieke voorbeelden.
Een endpoint documenteren: voorbeeld en foutafhandeling
Neem een realistisch endpoint: GET /sepa-orders/{orderId}, dat de status van een eerder aangemaakte SEPA-opdracht teruggeeft. Begin met het doel:
Geeft de actuele verwerkingsstatus van een SEPA-opdracht terug. Geschikt voor polling na het aanmaken of valideren van een betaalbestand.
Daarna de structuur: methode GET, pad /sepa-orders/{orderId}, padparameter orderId, authenticatie met een bearer-token, en de mogelijke responses. Een cURL-voorbeeld volstaat voor de eerste stap:
curl -X GET "https://api.example.com/sepa-orders/ord_12345" \
-H "Authorization: Bearer {access_token}" \
-H "Accept: application/json"
Een geslaagde response moet niet alleen veldnamen tonen, maar ook hun betekenis:
{
"orderId": "ord_12345",
"status": "processed",
"format": "pain.001",
"createdAt": "2026-01-12T09:15:00Z",
"completedAt": "2026-01-12T09:15:08Z"
}
status heeft een lijst toegestane waarden nodig, format zakelijke context en de tijdvelden een formaatspecificatie. Foutgevallen horen direct eronder: 401 (token ontbreekt of is verlopen), 403 (geen rechten op deze opdracht), 404 (orderId bestaat niet) en 429 (te veel requests).
Een foutmelding als { "message": "invalid request" } helpt niemand. Beter is een gestructureerd foutobject:
{
"error": {
"code": "INVALID_IBAN",
"message": "The provided IBAN is invalid.",
"details": { "field": "debtorIban" }
}
}
Clients kunnen dan reageren op code, ontwikkelaars zien direct welk veld het betreft en support en engineering spreken dezelfde taal. Bij betaalbestanden moet je bovendien zakelijke validatiefouten en technische fouten uit elkaar houden. Meer patronen vind je in ons artikel over technische API-documentatie en over de SEPA XML-API.
Versiebeheer zonder verrassingen
Of je versies in het pad (/v2/...) of in een header meegeeft, is bijzaak. Waar het om gaat: externe teams moeten weten wanneer gedrag verandert en hoe lang oude varianten blijven werken. Documenteer je versiestrategie, wat als breaking change telt, vanaf wanneer iets verouderd is, hoe bestaande clients migreren en welke wijziging in welke versie zit. Een “stille” wijziging in een bestaand endpoint is in de financiële sector funest voor vertrouwen.
Beveiliging, privacy en Docs as Code
Documentatie is vaak openbaar of breed intern beschikbaar. Beschrijf daarom de procedure, niet het geheim: de OAuth-flow, de rollen, het meegeven van tokens, de foutsituaties. Gebruik plaatshouders als {access_token} en {client_id} en voorbeeld-IBAN’s in plaats van echte gegevens. Wat nooit in voorbeelden hoort: echte keys of tokens, echte klantgegevens (namen, IBAN’s, adressen, machtigingskenmerken) en overbodig gedetailleerde interne beveiligingsmechanismen. Benoem wel welke velden persoonsgegevens bevatten en waarom ze nodig zijn, zodat ontwikkelaars voorzichtig zijn met logs en testdata.
Kernpunt: documenteer precies zoveel als een integrator nodig heeft om correct en veilig te bouwen. Niet meer.
De werkbare aanpak is Docs as Code: het OpenAPI-bestand staat in de repository, hoort in dezelfde pull request als de API-wijziging en doorloopt dezelfde kwaliteitscontroles. Een workflow die in de praktijk werkt:
- Endpoint, schema of regel wijzigen.
- OpenAPI-bestand in dezelfde commit bijwerken.
- Linting en schemavalidatie in de build.
- Voorbeelden, changelog en documentatie genereren.
- Review op breaking changes en zakelijke impact.
- Documentatieportaal automatisch publiceren.
Vier bouwstenen leveren bijna altijd winst op: spec-linting, controles op breaking changes, een mockserver vanuit de specificatie en gegenereerde voorbeelden. Voor SEPA-API’s controleert linting meer dan syntaxis: datumformaten, bedragvelden, tekensets, kenmerken, idempotency-headers en consistente naamgeving. Maar tooling vervangt geen inhoudelijk goede specificatie: een slecht beschreven SEPA-veld blijft slecht beschreven, ook als Swagger UI het mooi weergeeft. Laat daarom ook mensen meekijken die betaalprocessen, storneringen en formaatgrenzen kennen.
Checklist voor de documentatie van een SEPA-JSON-API
| Controlevraag | Waarom het telt |
|---|---|
| Is er een volledige OpenAPI-specificatie voor alle endpoints? | Basis voor tooling, review en tests |
| Is de koppeling van Excel- of CSV-kolommen naar JSON-velden beschreven? | Daar ontstaan de meeste vragen |
| Zijn er aparte voorbeelden voor overboeking en incasso? | Eén abstract voorbeeld leidt tot verwarring |
| Zijn validatiefouten beschreven met code en veldverwijzing? | Ongeldig IBAN of ontbrekend verplicht veld moet machineleesbaar zijn |
| Zijn succes- en foutscenario’s per kritiek endpoint gedocumenteerd? | Niet alleen 200 OK |
| Is de authenticatie uitgelegd zonder geheimen? | Veilig en toch bruikbaar |
| Is asynchrone verwerking of statusopvraag uitgelegd? | Wanneer polling zinvol is, welke status definitief is |
| Zijn er kopieerbare codevoorbeelden in meerdere talen? | Teams starten sneller |
| Is er een changelog? | Wijzigingen zijn zichtbaar vóór de uitrol |
| Zijn termen consequent en is de documentatie toegankelijk? | Betaling, machtiging en bestand wisselen niet van naam |
Goede documentatie meet je niet aan de hoeveelheid tekst, maar aan of een extern team zonder overleg een schoon integratiepad vindt. Bekijk hoe dat er in de praktijk uitziet in de documentatie van de GenerateSEPA-API.
Veelgestelde vragen
- Welke standaard past bij REST-API's in de financiële sector?
- OpenAPI is in de praktijk de norm. Het beschrijft endpoints, schema's, verplichte velden, authenticatie en foutmodellen machineleesbaar, zodat mensen en tools dezelfde bron gebruiken. Voor event-gedreven onderdelen kun je AsyncAPI als aanvulling gebruiken.
- Is HTML-documentatie genoeg zonder OpenAPI?
- Voor een eenvoudige interne API misschien, maar voor betaal-API's niet. Zonder machineleesbare specificatie kun je niet automatisch linten, mocken, op breaking changes controleren of voorbeelden synchroon houden. HTML-pagina's raken daardoor snel verouderd.
- Wat moet een SEPA-API extra goed documenteren?
- De koppeling van bronvelden naar SEPA-velden, de validatieregels voor IBAN, bedragen, data en tekensets, aparte voorbeelden voor overboeking en incasso, en machineleesbare foutcodes met veldverwijzing. Ook statuswaarden en wanneer een verwerking definitief is, moeten duidelijk zijn.
- Hoe voorkom je dat API-documentatie veroudert?
- Werk met Docs as Code: het OpenAPI-bestand staat in de repository en wordt in dezelfde pull request als de codewijziging bijgewerkt. Linting, controles op breaking changes en automatisch gegenereerde voorbeelden in de CI-pipeline houden documentatie en API gelijk.
