API

ERP-NL gebruikt API’s voor communicatie tussen frontend, backend en externe systemen. De meeste API’s zijn interne applicatie-API’s die door de ERP-NL frontend worden gebruikt. Daarnaast is er een beperkte publieke API voor machine-to-machine integraties.

Deze pagina beschrijft de API’s functioneel en technisch op hoofdlijnen: waarvoor ze bedoeld zijn, hoe ze gebruikt worden en waar ontwikkelaars, beheerders en integratiepartners op moeten letten.

API-overzicht

ERP-NL kent twee hoofdgroepen API’s.

API-groep	Pad	Doel
Interne applicatie-API	/api/*	Wordt gebruikt door de ERP-NL frontend
Publieke API	/api/v1/*	Bedoeld voor externe systemen en machine-to-machine integraties

De interne API is primair bedoeld voor de eigen applicatie. De publieke API is bedoeld voor gecontroleerde externe integraties.

Wanneer gebruik je welke API?

Situatie	Gebruik
De ERP-NL frontend opent een scherm	Interne API
Een gebruiker voert een actie uit in de applicatie	Interne API
Een extern systeem wil gegevens aanbieden	Publieke API
Een extern systeem wil een betalingsverzoek aanmaken	Publieke API
Een ontwikkelaar wil endpoints testen	Swagger UI of ReDoc
Een integratieplatform wil contractinformatie lezen	OpenAPI-schema

Interne API

De interne API staat onder /api/*. Deze API wordt gebruikt door de React frontend om gegevens op te halen, acties uit te voeren en schermen bij te werken.

De interne API ondersteunt onder andere:

• authenticatie;
• gebruikers;
• organisaties;
• bankrekeningen;
• betalingen;
• betaalbatches;
• payment files;
• Crediteuren;
• Verplichtingen;
• Grootboek;
• Reconciliatie;
• Ontvangstenverwerking;
• Incasso;
• bijlagen;
• audit events;
• notificaties;
• platformbeheer;
• RBAC;
• setup seed jobs.

Publieke API

De publieke API staat onder /api/v1/*. Deze API is bedoeld voor externe systemen die ERP-NL op een gecontroleerde manier willen aanroepen.

De huidige publieke API-documentatie richt zich vooral op betalingsverzoeken. Dit betekent dat externe systemen betalingsverzoeken kunnen aanbieden of raadplegen via daarvoor bedoelde endpoints.

Beschikbare documentatie-endpoints zijn:

Endpoint	Doel
/api/v1/docs	Swagger UI
/api/v1/redoc	ReDoc-documentatie
/api/v1/openapi.json	OpenAPI-schema

Gebruik /api/v1/docs of /api/v1/redoc om de actuele technische endpointdocumentatie te bekijken.

API-landschap

Conceptueel ziet het API-landschap er als volgt uit:

flowchart LR
  Frontend[ERP-NL frontend] --> InternalApi[Interne API /api]
  ExternalSystem[Extern systeem] --> PublicApi[Publieke API /api/v1]
  InternalApi --> Backend[FastAPI backend]
  PublicApi --> Backend
  Backend --> Services[Domeinservices]
  Services --> Database[(PostgreSQL)]
  Services --> Audit[Audit events]
  Services --> Notifications[Notificaties]

De frontend gebruikt de interne API. Externe systemen gebruiken de publieke API. Beide routes komen uiteindelijk uit bij backendservices die businesslogica, validatie, autorisatie en databaseverwerking uitvoeren.

Authenticatie

API’s vereisen authenticatie. De exacte manier van authenticatie hangt af van het type API.

Voor interne applicatie-API’s geldt:

• de gebruiker moet zijn ingelogd;
• de frontend stuurt authenticatie mee;
• de backend controleert sessie of token;
• rechten bepalen welke endpoints en acties beschikbaar zijn.

Voor publieke integraties geldt:

• publieke API’s gebruiken OAuth2 Client Credentials via Keycloak;
• externe systemen gebruiken een client-id en client-secret;
• requests worden namens een technische client uitgevoerd;
• de backend controleert token, rechten en organisatiecontext.

Autorisatie en rechten

Authenticatie bepaalt wie of welk systeem aanroept. Autorisatie bepaalt wat die gebruiker of client mag doen.

ERP-NL gebruikt rechten om API-toegang te beperken. Voorbeelden van rechten zijn:

• facturen lezen;
• betalingen lezen;
• batches verwerken;
• gebruikers beheren;
• auditinformatie bekijken;
• setup wijzigen;
• betalingsverzoeken aanmaken.

Een API-call kan mislukken wanneer:

• de gebruiker niet is ingelogd;
• het token ongeldig of verlopen is;
• de gebruiker geen rechten heeft;
• de organisatiecontext ontbreekt;
• de gevraagde actie niet is toegestaan voor de huidige status.

Organisatiecontext

ERP-NL ondersteunt meerdere organisaties. API-calls moeten daarom rekening houden met organisatiecontext.

Voor gebruikers betekent dit:

• gegevens horen bij een actieve organisatie;
• rechten kunnen per organisatie verschillen;
• dezelfde gebruiker kan in meerdere organisaties andere toegang hebben.

Voor ontwikkelaars betekent dit:

• API-calls moeten de juiste organisatiecontext respecteren;
• endpoints mogen geen gegevens uit andere organisaties lekken;
• tests moeten organisatie-isolatie controleren;
• nieuwe endpoints moeten expliciet rekening houden met organisatiecontext.

Request- en responseformaat

API-calls gebruiken JSON.

Voor muterende calls, zoals POST, PUT of PATCH, hoort de request meestal deze header te gebruiken:

Content-Type: application/json

Clients moeten JSON responses kunnen verwerken.

Een eenvoudige request kan er conceptueel zo uitzien:

POST /api/v1/payment-requests
Content-Type: application/json
Authorization: Bearer <token>

OpenAPI

ERP-NL publiceert een OpenAPI-schema voor de publieke API.

Het OpenAPI-schema is beschikbaar via:

/api/v1/openapi.json

Dit schema kan worden gebruikt voor:

• technische documentatie;
• contract-first integratieafspraken;
• clientgeneratie;
• testautomatisering;
• validatie van request- en responsevormen;
• API-review.

Swagger UI en ReDoc gebruiken dit schema om de API visueel te documenteren.

Swagger UI

Swagger UI is beschikbaar via:

/api/v1/docs

Gebruik Swagger UI om:

• beschikbare endpoints te bekijken;
• requestmodellen te inspecteren;
• responsemodellen te bekijken;
• endpoints handmatig te testen, indien authenticatie correct is ingericht;
• integratiegedrag te verkennen.

ReDoc

ReDoc is beschikbaar via:

/api/v1/redoc

Gebruik ReDoc vooral om:

• API-documentatie rustig te lezen;
• objectmodellen te bekijken;
• request- en responsevelden te begrijpen;
• integratieafspraken te bespreken met externe partijen.

Functionele API-domeinen

De API’s sluiten aan op de functionele modules van ERP-NL.

Domein	Voorbeelden van functionaliteit
Auth	Login, sessie, gebruiker ophalen, wachtwoord wijzigen
Users	Gebruikersbeheer
Organizations	Organisaties en organisatieleden
Crediteuren	Leveranciers, facturen, betalingsverzoeken, betaalprocesverzoeken
Betalingen	Betaalinstructies, batches, SEPA, bankfeedback
Grootboek	Journaalposten, saldi, proefbalans, periodeafsluiting
Verplichtingen	Budgetten, reserveringen, verplichtingen, kasverplichtingen
Reconciliatie	Reconciliatie runs, uitzonderingen, herkenningsregels
Ontvangstenverwerking	Ontvangsten, openstaande posten, exceptions
Incasso	Mandaten, instructies, batches, uitzonderingen
Attachments	Upload, metadata, preview, download, soft delete
Audit	Audit events en controle-informatie
Notifications	Meldingen en taken
Inrichting	Initialisatie, demo-data, configuratie

Betalingsverzoeken-API

De publieke API richt zich momenteel op betalingsverzoeken. Een betalingsverzoek is een verzoek aan ERP-NL om een betaling of betalingsproces op te starten of vast te leggen.

Een betalingsverzoek kan functioneel worden gebruikt wanneer een extern systeem een betaalverzoek wil aanbieden zonder direct in de ERP-NL frontend te werken.

Conceptueel:

flowchart LR
  External[Extern systeem] --> API[Publieke API]
  API --> Request[Betalingsverzoek]
  Request --> Crediteuren[Crediteuren]
  Crediteuren --> Betalingen[Betalingen]

De exacte velden, endpoints en responsemodellen moeten worden bekeken in de actuele OpenAPI-documentatie.

Interne API en frontend

De frontend gebruikt de interne API om schermen te vullen en acties uit te voeren.

Voorbeelden:

Frontendactie	API-gebruik
Facturen openen	Ophalen van facturen via interne Crediteuren API
Betaling aanmaken	Muterende call naar Betalingen API
Batch valideren	Actie-endpoint op batch
Uitzondering oplossen	Muterende call op exception
Gebruikers beheren	Interne setup/users API
Audit bekijken	Ophalen van audit events

Voor eindgebruikers is dit meestal onzichtbaar. Voor ontwikkelaars is het belangrijk dat frontend, backend en permissions consistent blijven.

Muterende acties

Muterende API-calls wijzigen gegevens of starten processen.

Voorbeelden zijn:

• gebruiker aanmaken;
• factuur wijzigen;
• betaling aanmaken;
• batch valideren;
• XML genereren;
• batch verzenden;
• uitzondering oplossen;
• seed job starten.

Voor muterende acties geldt:

• gebruik Content-Type: application/json;
• controleer autorisatie;
• controleer organisatiecontext;
• valideer input;
• leg waar nodig audit vast;
• geef duidelijke foutmeldingen terug.

Statusovergangen

Veel API-acties zijn afhankelijk van status. Een object kan alleen naar een volgende stap wanneer de huidige status dat toestaat.

Voorbeelden:

Object	Voorbeeld van statusafhankelijke actie
Factuur	Alleen vrijgeven voor betaling wanneer controles akkoord zijn
Betaling	Alleen exporteren wanneer betaling geldig is
Batch	Alleen verzenden wanneer batch succesvol gevalideerd is
Incasso-instructie	Alleen opnemen in batch wanneer instructie compatibel is
Uitzondering	Alleen oplossen wanneer oorzaak is beoordeeld
Seed job	Alleen starten wanneer gebruiker juiste rechten heeft

Nieuwe endpoints moeten statusovergangen expliciet controleren.

Foutafhandeling

API’s horen consistente foutresponses te geven. Voor gebruikers worden fouten meestal vertaald naar meldingen in de frontend.

Veelvoorkomende foutcategorieën zijn:

Fout	Betekenis
400 Bad Request	Request is ongeldig of mist gegevens
401 Unauthorized	Gebruiker of client is niet geauthenticeerd
403 Forbidden	Gebruiker of client heeft geen rechten
404 Not Found	Object of endpoint bestaat niet
409 Conflict	Actie conflicteert met huidige status of bestaande gegevens
422 Unprocessable Entity	Validatiefout op input
500 Internal Server Error	Onverwachte serverfout

Bij nieuwe endpoints moet duidelijk zijn welke fouten kunnen optreden en hoe een client daarop moet reageren.

Validatie

API’s valideren input voordat gegevens worden opgeslagen of acties worden uitgevoerd.

Voorbeelden van validaties zijn:

• verplichte velden;
• geldige datums;
• geldige bedragen;
• geldige valuta;
• geldige IBAN of BIC;
• geldige statusovergangen;
• geldige organisatiecontext;
• bestaande referenties naar objecten;
• toegestane acties voor de huidige gebruiker.

Validatie is belangrijk om te voorkomen dat de applicatie onjuiste of onvolledige gegevens verwerkt.

Audit en traceerbaarheid

Belangrijke API-acties horen traceerbaar te zijn. Dit is vooral belangrijk bij financiële processen.

Voorbeelden van acties die auditwaardig zijn:

• factuur goedkeuren;
• factuur vrijgeven voor betaling;
• betaling aanmaken;
• batch verzenden;
• incasso-instructie aanmaken;
• uitzondering oplossen;
• gebruiker of rol wijzigen;
• setup wijzigen;
• periode afsluiten.

Audit helpt bij controle, foutonderzoek en verantwoording.

API-beveiliging

API-beveiliging is belangrijk omdat ERP-NL financiële processen ondersteunt.

Belangrijke uitgangspunten zijn:

• geen endpoints zonder passende authenticatie;
• geen muterende acties zonder expliciete autorisatie;
• organisatie-isolatie afdwingen;
• input valideren;
• geen gevoelige informatie lekken in foutmeldingen;
• audit vastleggen voor belangrijke acties;
• technische clients beperken tot noodzakelijke rechten;
• secrets niet in code of documentatie opnemen.

Public API integratieproces

Voor een externe integratie is de aanbevolen werkwijze:

flowchart TD
  Start[Start integratie] --> Scope[Bepaal functionele scope]
  Scope --> Contract[Controleer OpenAPI-contract]
  Contract --> Auth[Configureer OAuth2 client]
  Auth --> Test[Test in testomgeving]
  Test --> Errors[Controleer foutafhandeling]
  Errors --> Audit[Controleer audit en logging]
  Audit --> GoLive[Productiegang]

Praktische stappen:

1. Bepaal welk proces gekoppeld moet worden.
2. Controleer of de publieke API dit proces ondersteunt.
3. Bekijk /api/v1/redoc.
4. Gebruik /api/v1/openapi.json als contract.
5. Richt OAuth2 Client Credentials in.
6. Stem organisatiecontext en rechten af.
7. Test requests in een testomgeving.
8. Controleer foutresponses.
9. Controleer auditinformatie.
10. Maak productieafspraken voor monitoring en support.

Nieuwe API-endpoints ontwikkelen

Nieuwe endpoints moeten consistent zijn met de bestaande API-opzet.

Checklist voor nieuwe endpoints:

• past het endpoint binnen het juiste domein;
• is authenticatie verplicht;
• zijn permissions expliciet;
• wordt organisatiecontext gecontroleerd;
• zijn request- en responsemodellen duidelijk;
• is inputvalidatie aanwezig;
• zijn foutresponses consistent;
• is audit nodig;
• zijn tests toegevoegd;
• is OpenAPI-documentatie correct;
• is de relevante gebruikersdocumentatie bijgewerkt.

API-documentatie gebruiken bij integraties

Voor een externe integratie is de aanbevolen werkwijze:

1. Bekijk de functionele documentatie.
2. Open /api/v1/redoc voor de API-structuur.
3. Open /api/v1/openapi.json voor het technische contract.
4. Controleer authenticatie via OAuth2 Client Credentials.
5. Stem organisatiecontext en rechten af.
6. Test requests eerst in een testomgeving.
7. Controleer foutafhandeling.
8. Leg integratieafspraken vast.
9. Monitor eerste verwerking.
10. Voeg audit- en supportafspraken toe.

Veelvoorkomende vragen

Waar vind ik de API-documentatie?

Gebruik:

/api/v1/docs
/api/v1/redoc
/api/v1/openapi.json

Wat is het verschil tussen /api/* en /api/v1/*?

/api/* is de interne API voor de ERP-NL frontend. /api/v1/* is de publieke API voor externe integraties.

Kan een extern systeem de interne API gebruiken?

In principe is de interne API bedoeld voor de eigen frontend. Externe systemen horen de publieke API te gebruiken.

Hoe authenticeren externe systemen?

Via OAuth2 Client Credentials met Keycloak.

Moet een externe API-call een organisatie meegeven?

API-calls moeten organisatie-isolatie respecteren. De exacte manier waarop organisatiecontext wordt bepaald, hangt af van de implementatie en clientinrichting.

Waar vind ik het OpenAPI-schema?

Via:

/api/v1/openapi.json

Kan ik een client genereren uit het OpenAPI-schema?

Ja, het OpenAPI-schema kan worden gebruikt voor clientgeneratie, maar controleer altijd of de gegenereerde client past bij authenticatie, organisatiecontext en foutafhandeling.

Waar staat meer technische referentie?

Meer detail staat in de repository onder:

docs/reference/public-api.md

Aandachtspunten

Let bij API-gebruik op het volgende:

• gebruik de publieke API voor externe integraties;
• gebruik de interne API niet als stabiel extern contract;
• controleer altijd authenticatie en autorisatie;
• respecteer organisatiecontext;
• test foutscenario’s expliciet;
• verwerk 401, 403, 409 en 422 netjes in clients;
• leg belangrijke muterende acties vast in audit;
• gebruik OpenAPI als technisch contract;
• documenteer integratieafspraken;
• gebruik geen productiegegevens in testcalls;
• behandel secrets en tokens als vertrouwelijke gegevens.