API
Hieronder vindt u een overzicht van de REST API v1: base URL, authenticatie, endpoints (Core Registry, Tax, Insurance, Inspection, Enforcement), headers, purpose-of-use, audit en rate limiting — wat u nodig heeft om met de API aan de slag te gaan.
Base URL en versioning
Base URL: https://<uw-cvr-domein>/api/v1
De API-versie staat in het path; er wordt geen versie in de headers gebruikt. Toekomstige breaking changes krijgen een nieuw path (bijvoorbeeld /api/v2).
Authenticatie
Web / SPA: Laravel session (cookie) na login; Sanctum stateful voor same-origin API-calls.
API (extern): Bearer token in de header: Authorization: Bearer <token>
Het token is de API key van de partner (die gehashed in de database wordt opgeslagen). De keys worden uitgegeven via het CVR backoffice. Keys horen nooit in de repo of in client-side code thuis.
Standaard headers
| Header | Verplicht | Beschrijving |
|---|---|---|
| Authorization | Ja | Bearer <token> |
| Accept | Aanbevolen | application/json |
| Content-Type | Bij body | application/json voor POST/PUT |
| X-Requested-With | Aanbevolen | XMLHttpRequest (Laravel) |
| X-Correlation-Id | Optioneel | UUID voor request tracing; als u het weggelaat, genereert de server er een en echo't die in de response |
| Idempotency-Key | Aanbevolen | Bij muterende POST of PUT (zoals overschrijving, betaling, activatie of plate issue) om dubbele verwerking te voorkomen |
Core Registry API
Idempotency-Key aanbevolen bij muterende calls.
Tax API
Insurance API
Verzekeraars en partners kunnen via deze endpoint de actuele verzekeringsstatus per registratie doorgeven.
Inspection API (voertuigkeuring / APK)
Keuringsstations of andere partners kunnen keuringsresultaten aanleveren. Bij verlopen valid_until kan een dagelijkse job de registratie schorsen. De enforcement check bevat inspection.is_valid en valid_until.
Enforcement API
Enforcement check (POST /enforcement/check)
Body: plateNumber, purposeCode (verplicht), caseRef (optioneel; voor politie aanbevolen). Response: voertuig, kenteken- en registratiestatus, verzekering, voertuigkeuring (APK), belasting, eigendom/houder en flags. Purpose wordt gelogd voor de audit.
Purpose-of-use en case reference
Voor enforcement- en gemeente-reads is een purposeCode verplicht (in de body of in de header X-Purpose-Code). Alleen purposes die aan de partner of rol zijn toegewezen, zijn toegestaan. Het purpose (en optioneel caseRef) wordt in de audit gelogd.
Voor de politie is een caseRef vereist voor lookups en acties in het kader van een zaak; op die manier is elke toegang aan een case gekoppeld voor verantwoording.
Audit en traceerbaarheid
- Elke enforcement- of gemeente-read wordt gelogd met purpose (en optioneel caseRef).
- Elke write levert een immutable audit-log op met: who, what, when, before/after, reason en context (IP, correlation_id).
- De responses bevatten X-Correlation-Id voor koppeling met de audit en support.
Rate limiting
Per partner wordt een limiet geconfigureerd in CVR (bijvoorbeeld rate_limit_per_minute). Bij overschrijding krijgt u een 429 met Retry-After waar van toepassing. De enforcement-endpoints kunnen extra throttling hebben (bijv. 300/min) om brute-force te beperken.
Foutafhandeling
Bij 4xx of 5xx is de body waar van toepassing application/problem+json met type, title, status en detail. Gebruik de X-Correlation-Id uit de response voor support en debugging.