👩‍💻 Voor ontwikkelaars

1 Checklist
2 REST-API
3 Authenticatie & beveiliging
4 Belangrijkste API-endpoints
5 Postman-voorbeeld
6 Code snippets
7 Aandachtspunten

Checklist

☑️ REST-API voor verzendingen en statusopvolging

☑️ API-calls

POST /sendDocument – verzenden van document
GET /status/{id} – status van verzending
GET /consent/{id} – checken of bestemmeling eBox gebruikt
POST /resend/{id} – opnieuw versturen bij fout

☑️ Beveiliging via OAuth2 en tokens (FAS/INSZ of RR-nummer)

☑️ Dataformaten: JSON (metadata), pdf (documenten)

☑️ Voorbeeldimplementaties

Postman-collectie beschikbaar (via downloadlink)
Codesnippets in Java, .NET, Python

☑️ Aandachtspunten

Maximale bestandsgroottes (PDF + bijlagen)
Beveiligde verbinding (TLS 1.2+)
Logging en foutafhandeling: verzenders zijn zelf verantwoordelijk voor retries (herhaalpogingen)
Response feedback: document kan in eBox geplaatst worden, maar gebruiker moet toestemming geven (consent)

REST-API

De Documentendienst kan rechtstreeks worden aangesproken via een REST-API. Deze API is ontworpen om zowel hoge volumes als strikte beveiligingsvereisten te ondersteunen. Op deze pagina vind je de belangrijkste info om als developer meteen aan de slag te gaan.

Authenticatie & beveiliging

Authenticatie
- Gebaseerd op OAuth2.0 tokens via het Federaal Authenticatie Systeem (FAS) voor burgers en RSZ voor ondernemingen.
- Elke API-call moet een geldig token bevatten in de header (Authorization: Bearer <token>).
Verbinding
- Alle communicatie gebeurt via HTTPS/TLS 1.2+.
- Data in rust wordt opgeslagen in Azure Blob Storage met encryptie en key-rotatie.

Belangrijkste API-endpoints

Endpoint	Methode	Doel	Input	Output

Endpoint	Methode	Doel	Input	Output
`/documents`	`POST`	Nieuwe verzending registreren	JSON met metadata + PDF-document	Unieke `documentId`
`/status/{documentId}`	`GET`	Status van een document opvragen	`documentId`	Statuscode + detail
`/consent/{insz}`	`GET`	Toestemming eBox voor burger checken	INSZ-nummer	`true/false`
`/consent/{kbo}`	`GET`	Toestemming eBox voor onderneming checken	KBO-nummer	`true/false`
`/events`	`POST`	Event genereren (melding nieuw document naar BOSA/RSZ)	Eventdata (tijdstip, verzender, onderwerp, bestemmeling)	`200 OK`

Postman-voorbeeld

Een voorbeeld van een document upload naar /documents:

POST /documents
Host: api.documentendienst.vlaanderen.be
Authorization: Bearer <token>
Content-Type: application/json

{
  "channel": "ebox",
  "recipient": {
    "insz": "79012345678"
  },
  "title": "Aanslagbiljet 2025",
  "expirationDate": "2026-12-31",
  "attachments": [
    {
      "fileName": "aanslagbiljet.pdf",
      "contentType": "application/pdf",
      "base64Content": "<BASE64_ENCODED_PDF>"
    }
  ]
}

Response:

{
  "documentId": "DOC-2025-000123",
  "status": "received"
}

Code snippets

Python-voorbeeld (requests)

import requests

url = "https://api.documentendienst.vlaanderen.be/documents"
headers = {"Authorization": "Bearer <token>", "Content-Type": "application/json"}

data = {
  "channel": "paper",
  "recipient": {"name": "Jan Peeters", "address": "Kerkstraat 12, 1000 Brussel"},
  "title": "Belastingbrief",
  "attachments": [
    {
      "fileName": "brief.pdf",
      "contentType": "application/pdf",
      "base64Content": "<BASE64_ENCODED_PDF>"
    }
  ],
  "printOptions": {"rectoVerso": True, "color": False},
  "deliveryOptions": {"registered": False, "priority": "D+3"}
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Aandachtspunten

Bestanden
- Maximaal 6 bijlagen per eBox-document.
- Enkel PDF toegestaan voor documenten.
Toestemming eBox
- Bij elke eBox-zending wordt automatisch gecontroleerd of er een actieve toestemming is.
- Verzenders krijgen feedback in real-time over deze check.
Foutafhandeling
- API geeft gestructureerde foutcodes terug (400 Bad Request, 401 Unauthorized, 500 Server Error).
- Gebruik de status-endpoint om opvolging te automatiseren.
Performance
- De API is schaalbaar tot miljoenen documenten per jaar.
- Bulkverwerking is mogelijk via parallelle API-calls of batch-integratie.

Met de Postman-collectie en voorbeelden kunt u meteen aan de slag.

Documentatie bouwstenen digitale loketten