Zgw Apis

ZGW API-standaarden & Haal Centraal

Integreer met de standaard-API's voor zaakgericht werken en basisregistraties bij de Nederlandse overheid.

Bron: VNG Realisatie — ZGW API's | Haal Centraal | API Design Rules

ZGW API-standaarden — overzicht

De ZGW API's zijn de VNG-standaarden voor zaakgericht werken, onderdeel van de Common Ground-architectuur.

Referentie-implementatie

Open Zaak is de open-source referentie-implementatie van alle ZGW API's: github.com/open-zaak/open-zaak

Zaken API — kernoperaties

Zaak aanmaken

POST /zaken/api/v1/zaken HTTP/1.1
Host: openzaak.gemeente.nl
Authorization: Bearer {token}
Content-Type: application/json

{
  "bronorganisatie": "123456789",
  "zaaktype": "https://catalogi.gemeente.nl/api/v1/zaaktypen/{uuid}",
  "verantwoordelijkeOrganisatie": "123456789",
  "startdatum": "2026-02-23",
  "omschrijving": "Aanvraag omgevingsvergunning Hoofdstraat 1"
}

Response (201 Created):

{
  "url": "https://openzaak.gemeente.nl/zaken/api/v1/zaken/{uuid}",
  "uuid": "b7c1e3d4-...",
  "identificatie": "ZAAK-2026-000123",
  "bronorganisatie": "123456789",
  "zaaktype": "https://catalogi.gemeente.nl/api/v1/zaaktypen/{uuid}",
  "startdatum": "2026-02-23",
  "status": null
}

Status wijzigen

POST /zaken/api/v1/statussen HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "zaak": "https://openzaak.gemeente.nl/zaken/api/v1/zaken/{zaak-uuid}",
  "statustype": "https://catalogi.gemeente.nl/api/v1/statustypen/{uuid}",
  "datumStatusGezet": "2026-02-23T10:00:00Z",
  "statustoelichting": "Zaak in behandeling genomen"
}

Zaak opvragen met expand

GET /zaken/api/v1/zaken/{uuid}?expand=status,resultaat,zaaktype HTTP/1.1
Authorization: Bearer {token}
Accept: application/json

Zoeken op kenmerken

GET /zaken/api/v1/zaken?zaaktype=https://...&startdatum__gte=2026-01-01&ordering=-startdatum&page=1 HTTP/1.1
Authorization: Bearer {token}

Documenten API — informatieobjecten

Document uploaden

POST /documenten/api/v1/enkelvoudiginformatieobjecten HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "bronorganisatie": "123456789",
  "creatiedatum": "2026-02-23",
  "titel": "Aanvraagformulier omgevingsvergunning",
  "auteur": "Jan Jansen",
  "taal": "nld",
  "informatieobjecttype": "https://catalogi.gemeente.nl/api/v1/informatieobjecttypen/{uuid}",
  "inhoud": "base64-encoded-content",
  "formaat": "application/pdf",
  "bestandsnaam": "aanvraag.pdf"
}

Document koppelen aan zaak

POST /zaken/api/v1/zaakinformatieobjecten HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "zaak": "https://openzaak.gemeente.nl/zaken/api/v1/zaken/{zaak-uuid}",
  "informatieobject": "https://documenten.gemeente.nl/api/v1/enkelvoudiginformatieobjecten/{doc-uuid}"
}

Catalogi API — configuratie

Zaaktypen opvragen

GET /catalogi/api/v1/zaaktypen?catalogus=https://...&status=alles HTTP/1.1
Authorization: Bearer {token}

Statustypen bij een zaaktype

GET /catalogi/api/v1/statustypen?zaaktype=https://catalogi.gemeente.nl/api/v1/zaaktypen/{uuid} HTTP/1.1
Authorization: Bearer {token}

Haal Centraal — basisregistratie-API's

BRP Personen bevragen

POST /haalcentraal/api/brp/personen HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "RaadpleegMetBurgerservicenummer",
  "burgerservicenummer": ["999993653"],
  "fields": ["naam", "geboorte", "verblijfplaats"]
}

Response:

{
  "personen": [
    {
      "naam": {
        "voornamen": "Jan",
        "geslachtsnaam": "Jansen"
      },
      "geboorte": {
        "datum": "1990-01-15"
      },
      "verblijfplaats": {
        "verblijfadres": {
          "straat": "Hoofdstraat",
          "huisnummer": 1,
          "postcode": "1234AB",
          "woonplaats": "Amsterdam"
        }
      }
    }
  ]
}

BAG Adressen zoeken

GET /haalcentraal/api/bag/adressen?postcode=1234AB&huisnummer=1 HTTP/1.1
Authorization: Bearer {token}

Authenticatie en autorisatie

JWT-token voor ZGW API's

ZGW API's gebruiken JWT-tokens met een specifiek claims-formaat:

import jwt
import time

def create_zgw_token(client_id: str, secret: str) -> str:
    """Maak een JWT-token aan voor ZGW API-authenticatie."""
    payload = {
        "iss": client_id,
        "iat": int(time.time()),
        "client_id": client_id,
        "user_id": "",
        "user_representation": ""
    }
    return jwt.encode(payload, secret, algorithm="HS256")

NL API Design Rules — verplichte regels

RFC 7807 foutresponse

{
  "type": "https://gemeente.nl/fouten/validatie",
  "title": "Validatiefout",
  "status": 400,
  "detail": "Het veld 'startdatum' is verplicht.",
  "instance": "/zaken/api/v1/zaken",
  "invalidParams": [
    {
      "name": "startdatum",
      "code": "required",
      "reason": "Dit veld is vereist."
    }
  ]
}

Paginering

ZGW API's gebruiken page-number paginering:

GET /zaken/api/v1/zaken?page=2&pageSize=100 HTTP/1.1

Response:

{
  "count": 523,
  "next": "https://openzaak.gemeente.nl/zaken/api/v1/zaken?page=3",
  "previous": "https://openzaak.gemeente.nl/zaken/api/v1/zaken?page=1",
  "results": [...]
}

Haal Centraal API's gebruiken cursor- of HAL-paginering met _links:

{
  "_embedded": { "adressen": [...] },
  "_links": {
    "self": { "href": "/adressen?page=1" },
    "next": { "href": "/adressen?page=2" }
  }
}

Implementatie-checklist

• ZGW-versie: gebruik de laatste stabiele versie van elke API (controleer VNG-documentatie)
• Catalogi eerst: configureer zaaktypen, statustypen, resultaattypen in Catalogi API vóór gebruik
• JWT-authenticatie: implementeer token-generatie conform ZGW-specificatie
• TLS: alle API-communicatie via HTTPS (NL API Design Rule API-03)
• Foutafhandeling: verwerk RFC 7807 foutresponses correct
• Paginering: verwerk next/previous links voor grote resultaatsets
• Expand: gebruik expand parameter om N+1 queries te voorkomen
• Notificaties: abonneer op ZGW notificaties voor asynchrone verwerking
• Audittrail: audittrail API inschakelen voor traceerbaarheid
• BSN-bescherming: BSN alleen via beveiligde verbinding; niet loggen
• Fields: gebruik fields parameter bij Haal Centraal voor dataminimalisatie
• OpenAPI: documenteer eigen API's met OpenAPI v3.x
• developer.overheid.nl: publiceer API op developer.overheid.nl

Gerelateerde skills

Meer informatie

• VNG ZGW API-standaarden | GitHub
• Open Zaak — referentie-implementatie
• Haal Centraal | GitHub
• NL API Design Rules
• developer.overheid.nl — API-catalogus Nederlandse overheid
• API Design Rules extensies