Berichten

Schuldhulpverleningsgegevens

De technische beschrijving van de API is in het volgende OAS3-bestand beschreven:

Toon OAS3 beschrijving

openapi: 3.1.0
info:
  title: DDAS Gegevens Uitwissel API - SHV
  description: |
    API voor het uitwisselen van Schuldhulpverleningsgegevens (SHV) met het CBS.
    Beveiligd met OAuth 2.0 Client Credentials Grant.
    Payload-integriteit en authenticiteit via JAdES payload signing conform Geonovum
    KP-APIs signing-jades module (header: nlgov-adr-payload-sig, PS256, detached,
    alleen digest getekend, key meegestuurd via x5c).

    Error handling is FSC-compatibel (Logius FSC Core 1.0.0): bij FSC-gerelateerde fouten
    wordt de header `Fsc-Error-Code` meegegeven met een geldige ERROR_CODE_... waarde.
  version: 1.0.0
  contact:
    name: DDAS-beheer
    url: https://divosa.nl/ddas

servers:
  - url: https://api.gegevensuitwissel.com/v1
    description: Productieomgeving
  - url: https://api-test.gegevensuitwissel.com/v1
    description: Acceptatie-/testomgeving

security:
  - OAuth2: [read]

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.gegevensuitwissel.com/token
          scopes:
            read: Toegang om SHV-gegevens op te halen

  headers:
    Digest:
      description: SHA-256 digest van de payload (conform RFC 3230). Verplicht bij berichten met body.
      schema:
        type: string
        pattern: '^SHA-256=[A-Za-z0-9+/=]{43,44}$'
      required: true

    NlgovAdrPayloadSig:
      required: true
      description: >
        De protected header bevat minimaal:
        - alg: PS256
        - kid: key identifier
        - x5c: volledige X.509 certificaatketen (PKIoverheid)
        - typ: "JOSE"

        De publieke sleutel wordt afgeleid uit het eerste certificaat in de x5c-array.
        Bij validatie dient:
        - de certificaatketen gevalideerd te worden tot PKIoverheid root
        - OCSP of CRL controle plaats te vinden
        - geldigheidsduur gecontroleerd te worden
      schema:
        type: string
        description: JWS Compact Serialization (detached payload)
        example: >
          eyJhbGciOiJQUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJzaHYtY2VydC0yMDI2IiwieDVjIjpbIk1JSURvakNDQW9xZ0F3SUJBZ0lVTzRkR2Vtb0V4YW1wbGVDZXJ0aWZpY2F0ZTEiLCJNSUlEbXpDQ0FvZ2dBd0lCQWdJVUJjQ2hhaW5DZXJ0MiJdfQ.. [BASE64URL_SIGNATURE]

    Fsc-Error-Code:
      description: |
        Verplichte FSC-header bij fouten conform FSC Core 1.0.0 (Inway/Outway).
        Bevat een ERROR_CODE_... uit de FSC-standaard (bijv. ERROR_CODE_ACCESS_TOKEN_INVALID).
      schema:
        type: string
        enum:
          - ERROR_CODE_ACCESS_TOKEN_MISSING
          - ERROR_CODE_ACCESS_TOKEN_INVALID
          - ERROR_CODE_ACCESS_TOKEN_EXPIRED
          - ERROR_CODE_WRONG_GROUP_ID_IN_TOKEN
          - ERROR_CODE_SERVICE_NOT_FOUND
          - ERROR_CODE_SERVICE_UNREACHABLE
          - ERROR_CODE_METHOD_UNSUPPORTED
      example: ERROR_CODE_ACCESS_TOKEN_INVALID

  schemas:
    Uitwisselmodel:
      $ref: 'https://raw.githubusercontent.com/VNG-Realisatie/ddas/main/v1.0/json_schema_Uitwisselmodel.json'

    Paginering:
      type: object
      required:
        - pageSize
        - currentPage
        - totalPages
        - totalRecords
      properties:
        pageSize:
          description: Het aantal records per pagina
          type: integer
          minimum: 1
          example: 25000
        currentPage:
          description: De huidige pagina
          type: integer
          minimum: 1
          example: 1
        totalPages:
          description: Het totaal aantal beschikbare pagina's
          type: integer
          minimum: 1
          example: 3
        totalRecords:
          description: Het totaal aantal te versturen records
          type: integer
          minimum: 0
          example: 72643

    GegevensRequest:
      type: object
      properties:
        aanleverperiodeStartdatum:
          type: string
          format: date
          example: "2025-01-01"
        aanleverperiodeEinddatum:
          type: string
          format: date
          example: "2025-12-31"
        aanleverende_organisatie:
          type: string
          example: "Gemeente Voorbeeldstad"
        page:
          type: integer
          minimum: 1
          example: 1
        pageSize:
          type: integer
          minimum: 1
          example: 25000
      additionalProperties: false

    FscError:
      type: object
      required: [code, domain]
      properties:
        code:
          type: string
          description: ERROR_CODE_... uit FSC standaard
          example: ERROR_CODE_ACCESS_TOKEN_INVALID
        domain:
          type: string
          enum: [ERROR_DOMAIN_INWAY, ERROR_DOMAIN_OUTWAY]
          example: ERROR_DOMAIN_INWAY
        title:
          type: string
          example: Ongeldige access token
        detail:
          type: string
          example: De meegegeven Fsc-Authorization token is ongeldig of verlopen
        status:
          type: integer
          example: 401

    ProblemDetails:
      type: object
      description: Probleemdetails volgens RFC 7807 / RFC 9457.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: URI die het type fout identificeert.
          example: "https://api.example.nl/problems/ongeldig-request"
        title:
          type: string
          description: Korte, leesbare omschrijving van het probleemtype.
          example: "Ongeldig request"
        status:
          type: integer
          description: HTTP-statuscode.
          example: 400
        detail:
          type: string
          description: Specifieke toelichting op deze fout.
          example: "De parameter page moet groter zijn dan of gelijk zijn aan 1."
        instance:
          type: string
          format: uri-reference
          description: URI-referentie naar deze specifieke foutinstantie.
          example: "/vs?aanleverperiodeStartdatum=2026-01-01&page=0"

paths:
  /gegevens:
    post:
      summary: Aanvragen en ontvangen van SHV-gegevens
      operationId: postGegevens
      description: |
        Stuurt een verzoek om SHV-gegevens over een bepaalde periode / organisatie.
        Het verzoek én het antwoord worden beschermd met een nlgov-adr-payload-sig
        header (JAdES payload signing, PS256, alleen digest getekend).
      security:
        - OAuth2: [read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GegevensRequest'
      responses:
        '200':
          description: Succesvol antwoord met de gevraagde SHV-gegevens
          headers:
            Digest:
              $ref: '#/components/headers/Digest'
            nlgov-adr-payload-sig:
              $ref: '#/components/headers/NlgovAdrPayloadSig'
          content:
            application/json:
              schema:
                type: object
                required:
                  - gegevens
                properties:
                  gegevens:
                    $ref: '#/components/schemas/Uitwisselmodel'
                  paginering:
                    allOf:
                      - $ref: '#/components/schemas/Paginering'
                    description: >
                      Alleen aanwezig als de gegevenslevering gepagineerd wordt.
                      Als dit object aanwezig is, zijn alle velden binnen Paginering verplicht.

        '400':
          description: Ongeldig verzoek (bijv. ongeldige filters of syntaxis)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

        '401':
          description: Geen of ongeldige authenticatie (FSC-compatibel)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
            WWW-Authenticate:
              schema:
                type: string
              description: Bearer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '403':
          description: Toegang geweigerd (bijv. verkeerde groep in token)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '404':
          description: Service of resource niet gevonden
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '405':
          description: Niet-ondersteunde HTTP-methode (FSC Outway fout)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '422':
          description: Request syntactisch correct, maar inhoudelijk niet verwerkbaar
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

        '429':
          description: Rate limit overschreden

        '502':
          description: Service niet bereikbaar (FSC Inway fout)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

• Klik hier om het bestand te downloaden

Vroegsignaleringsgegevens

De technische beschrijving van de API is in het volgende OAS3-bestand beschreven:

Toon OAS3 beschrijving

openapi: 3.1.0
info:
  title: DDAS Gegevens Uitwissel API - VS
  description: |
    API voor het uitwisselen van VroegSignalen (VS) met het CBS.
    Beveiligd met OAuth 2.0 Client Credentials Grant.
    Payload-integriteit en authenticiteit via JAdES payload signing conform Geonovum
    KP-APIs signing-jades module (header: nlgov-adr-payload-sig, PS256, detached,
    alleen digest getekend, key meegestuurd via x5c).

    Error handling is FSC-compatibel (Logius FSC Core 1.0.0): bij FSC-gerelateerde fouten
    wordt de header `Fsc-Error-Code` meegegeven met een geldige ERROR_CODE_... waarde.
  version: 1.0.0
  contact:
    name: DDAS-beheer
    url: https://divosa.nl/ddas

servers:
  - url: https://api.gegevensuitwissel.com/v1
    description: Productieomgeving
  - url: https://api-test.gegevensuitwissel.com/v1
    description: Acceptatie-/testomgeving

security:
  - OAuth2: [read]

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.gegevensuitwissel.com/token
          scopes:
            read: Toegang om VS-gegevens op te halen

  headers:
    Digest:
      description: SHA-256 digest van de payload (conform RFC 3230). Verplicht bij berichten met body.
      schema:
        type: string
        pattern: '^SHA-256=[A-Za-z0-9+/=]{43,44}$'
      required: true

    NlgovAdrPayloadSig:
      required: true
      description: >
        De protected header bevat minimaal:
        - alg: PS256
        - kid: key identifier
        - x5c: volledige X.509 certificaatketen (PKIoverheid)
        - typ: "JOSE"

        De publieke sleutel wordt afgeleid uit het eerste certificaat in de x5c-array.
        Bij validatie dient:
        - de certificaatketen gevalideerd te worden tot PKIoverheid root
        - OCSP of CRL controle plaats te vinden
        - geldigheidsduur gecontroleerd te worden
      schema:
        type: string
        description: JWS Compact Serialization (detached payload)
        example: >
          eyJhbGciOiJQUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJzaHYtY2VydC0yMDI2IiwieDVjIjpbIk1JSURvakNDQW9xZ0F3SUJBZ0lVTzRkR2Vtb0V4YW1wbGVDZXJ0aWZpY2F0ZTEiLCJNSUlEbXpDQ0FvZ2dBd0lCQWdJVUJjQ2hhaW5DZXJ0MiJdfQ.. [BASE64URL_SIGNATURE]

    Fsc-Error-Code:
      description: |
        Verplichte FSC-header bij fouten conform FSC Core 1.0.0 (Inway/Outway).
        Bevat een ERROR_CODE_... uit de FSC-standaard (bijv. ERROR_CODE_ACCESS_TOKEN_INVALID).
      schema:
        type: string
        enum:
          - ERROR_CODE_ACCESS_TOKEN_MISSING
          - ERROR_CODE_ACCESS_TOKEN_INVALID
          - ERROR_CODE_ACCESS_TOKEN_EXPIRED
          - ERROR_CODE_WRONG_GROUP_ID_IN_TOKEN
          - ERROR_CODE_SERVICE_NOT_FOUND
          - ERROR_CODE_SERVICE_UNREACHABLE
          - ERROR_CODE_METHOD_UNSUPPORTED
      example: ERROR_CODE_ACCESS_TOKEN_INVALID

  schemas:
    Uitwisselmodel:
      $ref: 'https://raw.githubusercontent.com/VNG-Realisatie/ddas-vroegsignalering/main/v1.0/json_schema_Uitwisselmodel.json'

    Paginering:
      type: object
      required:
        - pageSize
        - currentPage
        - totalPages
        - totalRecords
      properties:
        pageSize:
          description: Het aantal records per pagina
          type: integer
          minimum: 1
          example: 25000
        currentPage:
          description: De huidige pagina
          type: integer
          minimum: 1
          example: 1
        totalPages:
          description: Het totaal aantal beschikbare pagina's
          type: integer
          minimum: 1
          example: 3
        totalRecords:
          description: Het totaal aantal te versturen records
          type: integer
          minimum: 0
          example: 72643

    GegevensRequest:
      type: object
      properties:
        aanleverperiodeStartdatum:
          type: string
          format: date
          example: "2025-01-01"
        aanleverperiodeEinddatum:
          type: string
          format: date
          example: "2025-12-31"
        aanleverende_organisatie:
          type: string
          example: "Gemeente Voorbeeldstad"
        page:
          type: integer
          minimum: 1
          example: 1
        pageSize:
          type: integer
          minimum: 1
          example: 25000
      additionalProperties: false

    FscError:
      type: object
      required: [code, domain]
      properties:
        code:
          type: string
          description: ERROR_CODE_... uit FSC standaard
          example: ERROR_CODE_ACCESS_TOKEN_INVALID
        domain:
          type: string
          enum: [ERROR_DOMAIN_INWAY, ERROR_DOMAIN_OUTWAY]
          example: ERROR_DOMAIN_INWAY
        title:
          type: string
          example: Ongeldige access token
        detail:
          type: string
          example: De meegegeven Fsc-Authorization token is ongeldig of verlopen
        status:
          type: integer
          example: 401

    ProblemDetails:
      type: object
      description: Probleemdetails volgens RFC 7807 / RFC 9457.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: URI die het type fout identificeert.
          example: "https://api.example.nl/problems/ongeldig-request"
        title:
          type: string
          description: Korte, leesbare omschrijving van het probleemtype.
          example: "Ongeldig request"
        status:
          type: integer
          description: HTTP-statuscode.
          example: 400
        detail:
          type: string
          description: Specifieke toelichting op deze fout.
          example: "De parameter page moet groter zijn dan of gelijk zijn aan 1."
        instance:
          type: string
          format: uri-reference
          description: URI-referentie naar deze specifieke foutinstantie.
          example: "/vs?aanleverperiodeStartdatum=2026-01-01&page=0"

paths:
  /gegevens:
    post:
      summary: Aanvragen en ontvangen van VS-gegevens
      operationId: postGegevens
      description: |
        Stuurt een verzoek om VS-gegevens over een bepaalde periode / organisatie.
        Het verzoek én het antwoord worden beschermd met een nlgov-adr-payload-sig
        header (JAdES payload signing, PS256, alleen digest getekend).
      security:
        - OAuth2: [read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GegevensRequest'
      responses:
        '200':
          description: Succesvol antwoord met de gevraagde VS-gegevens
          headers:
            Digest:
              $ref: '#/components/headers/Digest'
            nlgov-adr-payload-sig:
              $ref: '#/components/headers/NlgovAdrPayloadSig'
          content:
            application/json:
              schema:
                type: object
                required:
                  - gegevens
                properties:
                  gegevens:
                    $ref: '#/components/schemas/Uitwisselmodel'
                  paginering:
                    allOf:
                      - $ref: '#/components/schemas/Paginering'
                    description: >
                      Alleen aanwezig als de gegevenslevering gepagineerd wordt.
                      Als dit object aanwezig is, zijn alle velden binnen Paginering verplicht.

        '400':
          description: Ongeldig verzoek (bijv. ongeldige filters of syntaxis)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

        '401':
          description: Geen of ongeldige authenticatie (FSC-compatibel)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
            WWW-Authenticate:
              schema:
                type: string
              description: Bearer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '403':
          description: Toegang geweigerd (bijv. verkeerde groep in token)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '404':
          description: Service of resource niet gevonden
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '405':
          description: Niet-ondersteunde HTTP-methode (FSC Outway fout)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

        '422':
          description: Request syntactisch correct, maar inhoudelijk niet verwerkbaar
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

        '429':
          description: Rate limit overschreden

        '502':
          description: Service niet bereikbaar (FSC Inway fout)
          headers:
            Fsc-Error-Code:
              $ref: '#/components/headers/Fsc-Error-Code'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/FscError'

• Klik hier om het bestand te downloaden

Hieronder worden de berichten die in het OAS-bestand technisch beschreven zijn, toegelicht.

Encoding

Conform de specificaties voor de bestandsuitwisseling voor schuldhulpverlening en vroegsignalering, 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^*)

• aanleverperiodeEinddatum (date - startdatum van rapportageperiode, default leeg: gegevensleverancier bepaalt dan einddatum^*)

• 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, 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)

^*: 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 ondertekend met de private sleutel van de verzender van het vraagbericht - in dit geval CBS. Zie het hoofdstuk Signing en Versleuteling 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 en vroegsignaleringsgegevens.

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 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 met gebruik van de eigen private sleutel. Zie het hoofdstuk Signing en Versleuteling 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

• Gegenereerd door de gekozen methode van FSC

• Gegenereerd door de de FSC Inway