VNG-Realisatie · brienen · Jun 2, 2026 · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026
diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
@@ -0,0 +1,41 @@
+name: PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+concurrency:
+  group: preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4.2.2
+
+      - uses: actions/setup-python@v5.6.0
+        with:
+          python-version: "3.11"
+
+      - run: pip install -r requirements.txt
+
+      - name: Download OAS YAML files
+        run: |
+          mkdir -p docs/includes
+          curl -L \
+            -o docs/includes/DDAS-SHV.yaml \
+            https://raw.githubusercontent.com/VNG-Realisatie/ddas/refs/heads/main/v1.0/DDAS-SHV.yaml
+          curl -L \
+            -o docs/includes/DDAS-VS.yaml \
+            https://raw.githubusercontent.com/VNG-Realisatie/ddas/refs/heads/main/v1.0/DDAS-VS.yaml
+
+      - run: mkdocs build
+
+      - uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: site/
diff --git a/docs/api/API-componenten.png b/docs/api/API-componenten.png
diff --git a/docs/api/berichten.md b/docs/api/berichten.md
@@ -0,0 +1,80 @@
+# Berichten
+
+## Schuldhulpverleningsgegevens
+
+De technische beschrijving van de API is in het volgende OAS3-bestand beschreven:
+
+<details><summary>Toon OAS3 beschrijving</summary>
+``` { .yaml .copy }
+{!../v1.0/DDAS-SHV.yaml!}
+```
+</details>
+
+- [Klik hier om het bestand te downloaden](https://raw.githubusercontent.com/VNG-Realisatie/ddas-vroegsignalering/main/v1.0/DDAS-SHV.yaml)  
+
+
+## Vroegsignaleringsgegevens
+
+De technische beschrijving van de API is in het volgende OAS3-bestand beschreven:  
+
+<details><summary>Toon OAS3 beschrijving</summary>
+``` { .yaml .copy }
+{!../v1.0/DDAS-VS.yaml!}
+```
+</details>
+
+- [Klik hier om het bestand te downloaden](https://raw.githubusercontent.com/VNG-Realisatie/ddas-vroegsignalering/refs/heads/main/v1.0/DDAS-VS.yaml)  
+
+
+Hieronder worden de berichten die in het OAS-bestand technisch beschreven zijn, toegelicht.
+
+
+## Encoding
+
+Conform de specificaties voor de bestandsuitwisseling voor [schuldhulpverlening](https://vng-realisatie.github.io/ddas/v1.0/uitwisselspecificatie/) en [vroegsignalering](https://vng-realisatie.github.io/ddas-vroegsignalering/v1.0/uitwisselspecificatie/), is de encoding van de berichten UTF-8.
+
+
+## Vraagbericht (request)
+
+Dit is het vraagbericht zoals dat door CBS via de "Outway" naar de "Inway" van de schuldhulpverlener gestuurd wordt. Dit is een POST request waarbij alleen gegevens opgevraagd worden. Er worden geen GET requests gebruikt, omdat hierbij de parameters in de URL zitten en mogelijk cache gegevens gebruikt worden, als de parameters niet wijzigen.
+
+Parameters die meegestuurd kunnen worden (allemaal optioneel):
+
+- aanleverperiodeStartdatum (date - startdatum van rapportageperiode, default leeg: gegevensleverancier bepaalt dan startdatum<sup>*</sup>)
+
+- aanleverperiodeEinddatum (date - startdatum van rapportageperiode, default leeg: gegevensleverancier bepaalt dan einddatum<sup>*</sup>)
+
+- Aanleverende_organisatie (string - organisatie waarvan de gegevens geleverd worden, default alle; alleen relevant als over meer dan 1 organisatie (gemeente/ schuldhulpverlener) gegevens aangeleverd worden)
+
+- page (integer - de gewenste pagina, als er meerdere pagina's aan gegevens zijn; zie ook [niet-functionele eisen](non-functionals.md#performance), default de eerste pagina)
+
+- pageSize (integer - aantal records (vroegsignalen/schuldhulptrajecten) dat in één responsebericht meegestuurd wordt, default leeg: gegevensleverancier bepaalt dan het aantal met een maximum zoals bepaald in de [niet-functionele eisen](non-functionals.md#performance))
+
+
+><sup>*</sup>: als de schuldhulpverlener de start- en einddatum van de rapportageperiode bepaalt, worden de start- en einddatum van de afgelopen rapportageperiode gebruikt. NB: de definitie van de rapportageperiode (start- en einddatum en welke gegevens meegenomen moeten worden) wordt in een aparte beschrijving vastgesteld.   
+>Voorbeeld: als CBS in juli een request voor gegevens verstuurt zonder start- en einddatum en er halfjaarlijks gerapporteerd wordt, dan worden de start- en einddatum waarover gegevens geleverd worden 1 januari, resp. 30 juni van het huidige jaar. Als er per kwartaal gerapporteerd wordt, dan zijn in dit geval de start- en einddatum 1 maart, resp. 30 juni van het huidige jaar.
+
+Het bericht wordt met [JAdES](https://geonovum.github.io/KP-APIs/API-strategie-modules/signing-jades/) ondertekend met de private sleutel van de verzender van het vraagbericht - in dit geval CBS. Zie het hoofdstuk [Signing en Versleuteling](signing-encryptie.md) voor de specificaties van de ondertekening.
+
+
+## Antwoordbericht (response)
+
+Dit is het antwoordbericht van de gegevensbeheerder (systeem dat de bron beheert) met de gewenste gegevens in JSON formaat.
+De payload is gebaseerd op het uitwisselformaat zoals dat is beschreven voor [schuldhulpgegevens](https://vng-realisatie.github.io/ddas/v1.0/uitwisselspecificatie/) en [vroegsignaleringsgegevens](https://vng-realisatie.github.io/ddas-vroegsignalering/v1.0/uitwisselspecificatie/).
+
+Naast de vroegsignalen worden gegevens voor de **paginering** meegegeven. Deze zijn nodig als niet alle gegevens in één responsebericht passen - zie de [niet-functionele eisen](non-functionals.md#performance) voor meer uitleg. Als alle gegevens in één responsebericht passen, hoeven de paginering gegevens niet in het bericht opgenomen te worden.
+
+Ook dit bericht wordt ondertekend met [JAdES](https://geonovum.github.io/KP-APIs/API-strategie-modules/signing-jades/) met gebruik van de eigen private sleutel. Zie het hoofdstuk [Signing en Versleuteling](signing-encryptie.md) voor de specificaties van de ondertekening.
+Versleutelen van de payload is niet nodig.
+
+Mogelijke responses:
+
+- 200: bericht goed verwerkt (met gesigneerde payload)
+
+- Foutberichten conform de FSC standaard:
+
+  - Gegenereerd door de [FSC Manager](https://gitdocumentatie.logius.nl/publicatie/fsc/core/1.0.0/#codes)
+
+  - Gegenereerd door de [gekozen methode van FSC](https://gitdocumentatie.logius.nl/publicatie/fsc/core/1.0.0/#codes-0)
+
+  - Gegenereerd door de [de FSC Inway](https://gitdocumentatie.logius.nl/publicatie/fsc/core/1.0.0/#codes-1)
diff --git a/docs/api/iam.md b/docs/api/iam.md
@@ -0,0 +1,18 @@
+# Identificatie, Authenticatie en Autorisatie
+
+Het bijhouden van de deelnemers in het DDAS-stelsel gebeurt door RINIS in een directory die door FSC gebruikt wordt. Alle deelnemers gebruiken deze directory bij het uitwisselen van berichten. Zie het hoofdstuk [transport](transport.md) voor aansluitspecificaties.
+
+## Identificatie
+
+Identificatie gebeurt op basis van het (sub)OIN van de deelnemer. Dit (sub)OIN wordt bij PKIo certificaten geplaatst in het SerialNumber veld van het Subject. Als de deelnemer geen (sub)OIN heeft, dan wordt het handelsregisternummer hiervoor gebruikt.
+
+## Authenticatie
+
+Systemen worden geauthenticeerd met behulp van het PKIo certificaat.
+
+## Autorisatie
+
+De autorisatie voor toegang wordt vastgelegd in een FSC Contract tussen aanbieder en afnemer. Deze liggen vast in de FSC Manager van de betrokken deelnemers.
+Er is voorlopig maar één service met een vaste set gegevens, waar maar één partij (CBS) toegang toe zal krijgen. Daarom is er geen fijnmazige autorisatie nodig: partijen die toegang hebben tot de service zijn geautoriseerd om gegevens te bevragen.
+
+Als fijnmaziger autorisatie nodig is, dan wordt aangesloten op [Federatieve Toegangsverlening](https://vng-realisatie.github.io/ftv/) en de [NLGov AuthZEN Authorization API](https://logius-standaarden.github.io/authzen-nlgov/).
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -0,0 +1,12 @@
+Dit deel van de documentatie bevat de koppelvlakspecificatie voor de API waarmee schuldhulporganisaties gegevens beschikbaar kunnen stellen aan het CBS.  
+
+De koppelvlakspecificatie bestaat uit de volgende onderdelen:  
+- [Uitgangspunten](uitgangspunten.md): de kaders die gevolgd zijn en de 10 keuzes die gemaakt zijn;  
+- [Overzicht](overzicht.md): overzicht van de oplossing met de relevante componenten;  
+- [Transportlaag](transport.md): specificatie van de transportlaag - de inrichting van het koppelvlak, endpoints van de centrale directory en naamsconventie voor de services;  
+- [Identificatie, Authenticatie en Autorisatie](iam.md): afspraken rond identificatie, authenticatie en autorisatie;  
+- [Signing en encryptie](signing-encryptie.md): afspraken rond het ondertekenen en versleutelen van berichten;  
+- [Berichten](berichten.md): de inhoud van de berichten met OAS3 beschrijving;  
+- [Niet-functionele eisen](non-functionals.md): de niet-functionele eisen aan de services.  
+
+**LET OP**: de koppelvlakspecificatie voor het beschikbaarstellen van vroegsignaleringsgegevens is hetzelfde als die voor het beschikbaarstellen van schuldhulpgegevens - alleen de [naamsconventie](transport.md#naamsconventie) en de [inhoud van de berichten](berichten.md) zijn verschillend. Let er daarom op dat u bij deze onderwerpen de juiste keuze maakt.
diff --git a/docs/api/non-functionals.md b/docs/api/non-functionals.md
@@ -0,0 +1,54 @@
+# Niet functionele eisen
+
+> **OPMERKING!**
+
+>De niet-functionele eisen hieronder zijn op basis van het ontwerp vastgesteld, maar moeten zich nog in de praktijk bewijzen. Tijdens het gebruik van het koppelvlak zal bijgehouden worden hoe de oplossing werkt en of aanscherping van de niet-functionele eisen nodig is. Deze kunnen dan in een aparte afspraak vastgelegd worden, tot de koppelvlakspecificatie als geheel bijgewerkt wordt. Als er inderdaad aparte afspraken over de niet-functionele eisen vastgelegd zijn, gaan die vóór de eisen die in deze koppelvlakspecificatie staan.  
+
+## Beschikbaarheid
+
+De toepassing is niet kritisch: er is geen hoge beschikbaarheid vereist.  
+De services moeten beschikbaar zijn op de momenten dat CBS de gegevens verzameld. Hierover moeten nog afspraken gemaakt worden.
+
+## Performance
+
+De berichtenuitwisseling is synchroon. De API moet daarom binnen de "time-out" tijd reageren op een request. Er is nog te weinig ervaring met het koppelvlak om een goed onderbouwde maximale response-tijd en daaraan gekoppeld een maximaal aantal records.
+Vooralsnog wordt uitgegaan van de volgende maximale aantallen records (vroegsignalen/schuldhulptrajecten):  
+
+| Items | Maximaal aantal per bericht |
+|-------|----------------------------|
+| Schuldhulptrajecten | **25.000** |
+| Vroegsignalen | **50.000** |  
+
+Als het maximaal aantal records overschreven dreigt te worden, moeten de gegevens over verschillende berichten verdeeld worden. In het response-bericht worden dan de velden in het object **paginering** gevuld worden.  
+Dit gebeurt conform de volgende definities:
+
+| Veld | Betekenis | Waarde |
+|------|-----------|--------|
+| **pageSize** | Het aantal records (schuldhulptrajecten/vroegsignalen) per pagina | integer [min: 1, max: 25.000 of 50.000 (zie hierboven)] |
+| **currentPage** | De huidige pagina | integer [min: 1] |
+| **totalPages** | Het totaal aantal beschikbare pagina's | integer [min: 1] |
+| **totalRecords** | Het totaal aantal te versturen records (schuldhulptrajecten/vroegsignalen) | integer [min: 0] |
+
+Het paginering-object is optioneel (als alle gegevens in één bericht passen hoeft het object niet opgenomen te worden in het bericht), maar als er gebruik gemaakt wordt van paginering, **moeten** alle paginering-velden gevuld zijn.  
+In het request-bericht van CBS worden dan ook de volgende paginering velden meegestuurd:
+
+| Veld | Betekenis | Waarde | Opmerking |
+|------|-----------|--------|-----------|
+| **page** | De opgevraagde pagina | integer [min: 1] | Als een niet bestaande pagina opgevraagd wordt, wordt de eerste pagina in het response-bericht teruggestuurd, met paginering-gegevens. Als er geen page in het request-bericht zit, maar er wel gepagineerd moet worden, wordt de eerste pagina in het response-bericht gestuurd. |
+| **pageSize** | Het aantal records (schuldhulptrajecten/vroegsignalen) dat in het response-bericht opgenomen mag worden | integer [min: 1, max: zie hierboven] | Als PageSize in het request-bericht zit en er meer records verstuurd moeten worden, **moet** er gebruik gemaakt worden van paginering |
+
+
+Om belasting van de productiesystemen te beperken mag een cache gebruikt worden, onder de volgende voorwaarden:
+
+- De cache wordt minimaal dagelijks ververst.
+
+- De integriteit van de gegevens in de cache kan gegarandeerd worden. De gegevensleverancier bepaalt zelf hoe deze garantie gegeven kan worden (bijvoorbeeld met controles, checksums, logging of andere maatregelen).
+
+
+## Logging en Monitoring
+
+Verantwoordelijkheid voor monitoring ligt bij partij die verantwoording hierover moet afleggen.
+
+FSC vereist dat er transactielogging bijgehouden wordt. Hiervoor wordt de logging module van OpenFSC gebruikt. Deze vorm van logging bevat geen persoonsgegevens en vereist daarom geen specifieke privacy maatregelen.
+
+Bij de logging van de vragende en leverende systemen, moet er rekening gehouden worden met de AVG als persoonsgegevens (zoals het BSN) gelogd worden. De [DPIA](https://www.divosa.nl/sites/default/files/2025-11/DPIA%20DDAS%20versie%203.0%20%28november%202025%29.pdf) heeft uitgewezen dat de uitgewisselde BSN's niet individueel gelogd hoeven te worden om te voldoen aan het inzagerecht (een algemene vermelding dat schuldhulpverleningsgegevens aan CBS beschikbaar gesteld worden, is voldoende). Dit wordt daarom afgeraden - logging met individuele BSN's vormen immers een nieuwe verwerking met daaraan gekoppelde risico's.
diff --git a/docs/api/overzicht.md b/docs/api/overzicht.md
@@ -0,0 +1,22 @@
+# Overzicht API stelsel
+
+In de onderstaande figuur staan de componenten geschetst die in het API berichtenverkeer een rol spelen.
+
+<!--- NB: bij MKDocs wordt dit
+![overzicht API componenten](overzicht.png)
+--->
+<!--- NB: bij Respec wordt dit --->
+![overzicht API componenten](overzicht.png)
+<!--- --->
+
+In deze figuur is:
+
+- Consumer: de vragende partij - hier is dat CBS
+
+- Provider: de leverende partij - hier is dat de schuldhulpverlenende organisatie of de gegevensleverancier hiervan
+
+- De "directory" waar alle services (API's) gepubliceerd worden, wordt door [RINIS](https://www.rinis.nl/nl/) beheerd
+
+
+Deze specificatie richt zich op de inrichting van alle componenten van dit koppelvlak.
+Bent u enkel geïnteresseerd in de OpenAPI specificatie van de API? Deze staat onder het kopje [Berichten](berichten.md).
diff --git a/docs/api/overzicht.png b/docs/api/overzicht.png
diff --git a/docs/api/signing-encryptie.md b/docs/api/signing-encryptie.md
@@ -0,0 +1,60 @@
+# Ondertekenen en Versleuteling
+
+## Ondertekenen (Signing)
+
+Alle berichten moeten ge-signed worden om de authenticiteit, integriteit en bewijsbaarheid van herkomst van het berichtenverkeer te garanderen.
+
+Signing gebeurt op basis van [ADR-HTTP Message and payload signing with JAdES](https://geonovum.github.io/KP-APIs/API-strategie-modules/signing-jades/) - zie [Uitgangspunten](uitgangspunten.md#gebruik-jades-voor-signen) voor de onderbouwing hiervoor.
+
+Het signeren van het bericht gebeurt met de privé sleutel van de verzender van het bericht, zodat de controle met de publieke sleutel van de verzender kan gebeuren en iedere partij met toegang tot de PKIoverheid trust anchors de handtekening kan verifiëren. Iedere deelnemer van het DDAS-stelsel heeft dus een certificaat nodig voor het ondertekenen van de berichten. Dit moet een ander certificaat zijn dan welke voor het transport gebruikt wordt! Ook dit certificaat is een "services" certificaat, maar met EKU (Extended Key Usage) "Digital Signature".
+Er is gekozen voor het gebruik van PKIo certificaten - zie [Uitgangspunten](uitgangspunten.md#gebruik-pkioverheid-certificaten-voor-authenticatie-signing-en-encryptie) voor de onderbouwing hiervan.
+
+Voor de ondertekening is gekozen om enkel de **payload** te ondertekenen conform de [richtlijnen van ADR](https://geonovum.github.io/KP-APIs/API-strategie-modules/signing-jades/#payload-signing). Volledige message ondertekening is niet nodig voor DDAS.
+Conform de richtlijnen van ADR wordt het PS256 algoritme gebruikt. De signature wordt berekend over de exacte byte-representatie van de HTTP body zoals verzonden.  
+Er is gekozen voor het **JAdES-B** profiel van ondertekenen. JAdES-B betekent dat de handtekening en de ondertekeningscertificaten worden opgenomen, zonder trusted timestamp of ingebedde validatie-informatie. Zwaardere profielen, waarbij ook een trusted timestamp en verificatie informatie geregistreerd wordt, zijn voor DDAS niet nodig.
+De publieke sleutel om de ondertekening te controleren wordt meegestuurd in de header van het bericht via het veld x5c. De hele X.509 certificaatketen wordt meegestuurd, waarbij de eerste waarde gebruikt wordt voor de controle van de ondertekening.
+In de header komen dus het volgende te staan:
+
+<pre><code>nlgov-adr-payload-sig: [JWS Compact Serialization]</code></pre>
+
+Waarin *JWS Compact Serialization* de base64url-gecodeerde waarden conform [RFC 7515](https://www.rfc-editor.org/rfc/rfc7515) van de header en de ondertekening bevatten:
+
+<pre><code>BASE64URL(ProtectedHeader)..BASE64URL(Signature)</code></pre>
+
+*(Let op de dubbele punt (..): het payload-gedeelte is leeg, omdat de payload in de HTTP body zit.)*
+
+De header bevat in elk geval de volgende velden:
+
+<pre><code>{  
+  "alg": "PS256",  
+  "typ": "JOSE",  
+  "kid": "[Key identifer]",  
+  "x5c": [  
+    "[end-entity-cert-base64-der]",  
+    "[intermediate-cert-base64-der]"  
+  ],  
+  "x5t#S256": "[sha256-thumbprint]"  
+}</code></pre>
+
+*(Het veld x5t#S256 is niet verplicht, maar wordt wel aanbevolen)*
+
+
+
+Bij ontvangst moet de ontvanger het volgende doen om de ondertekening te controleren:
+
+- Decode protected header
+
+- Haal eerste certificaat uit x5c
+
+- Valideer certificaatketen tot PKIoverheid root
+
+- Controleer:
+  - Geldigheid certificaat
+  - OCSP of CRL
+
+- Verifieer signature over HTTP body
+
+
+## Versleuteling (Encryptie)
+
+De inhoud van de berichten wordt niet versleuteld. Zie [Uitgangspunten](uitgangspunten.md#berichten-worden-niet-versleuteld) voor de onderbouwing hiervan.