Zaken API

API voor het opslaan en ontsluiten van zaakgegevens.

De API ondersteunt het opslaan en het naar andere applicaties ontsluiten van gegevens over alle gemeentelijke zaken, van elk type. Opslag vindt plaats conform het RGBZ waarin objecten, gegevens daarvan en onderlinge relaties zijn beschreven. Het bevat echter niet alle gegevens uit het RGBZ: documenten worden bijv. opgeslagen in de Documenten API, besluiten in de Besluiten API, etc. Vanuit zaken worden er dan ook relaties gelegd naar andere resources.

Gegevensmodel

De zaak vormt de kern van het zaakgericht werken. De omvang en afbakening worden bepaald door het traject van (aan)vraag tot (passend) antwoord. Een zaak komt daarmee overeen met een bedrijfsproces.

Hoofd- en deel-zaken

Als een product of dienst via verschillende bedrijfsprocessen tot stand komt, wordt gewerkt met deelzaken. De hoofdzaak coördineert dat alle deelzaken samen leiden tot het (passende) antwoord op de (aan)vraag van de initiator.

Relevante andere zaken

Soms heeft de ene zaak betrekking op een andere zaak, zoals een bezwaarzaak die volgt op een vergunningzaak.

Aan elkaar gerelateerde zaken (met elk hun eigen bedrijfsproces/aanleiding) worden vastgelegd als AndereRelevanteZaak. Dit zijn zowel zaken binnen dezelfde organisatie als van verschillende organisaties.

Zaakobject

Elke zaak heeft ergens betrekking op wat is vastgelegd met de relatie naar zaakobject. De, bij de ontwikkeling van de API’s gebruikte, zaakobjecten (mor, verblijfsobject, …) kunnen als resource of m.b.v. identificerende gegevens worden opgenomen bij het zaakobject. Aangezien nog niet kan worden aangenomen dat deze vanuit de bron beschikbaar zijn.

Betrokken en rollen

Ook heeft elke zaak één of meer betrokkenen, die via hun rol aan de zaak gerelateerd zijn. De verschillende typen betrokkenen (medewerker, natuurlijk persoon, niet natuurlijk persoon en organisatieonderdeel), zijn nu opgenomen in de ZakenAPI. Aangezien nog niet kan worden aangenomen dat deze vanuit de bron beschikbaar zijn.

Relatie met besluiten en documenten

Een besluit kan een uitkomst zijn van een zaak van de zaakbehandelende organisatie. Besluit heeft dan ook een optionele relatie met de zaak waarvan het een uitkomst is. Deze relatie wordt in de Zaken API vastgelegd in zaakbesluit. Een informatieobject kan tot meer dan één zaak behoren en een zaak kan meer dan één informatieobjecten bevatten. De relatie tussen zaak en informatieobject is vastgelegd in zaakinformatieobject (Zaken API) en objectinformatieobject (Documenten API), waarbij zaakinformatieobject leidend is.

Zaakdossier

Een zaak, met eventuele deelzaken dan wel de verwijzing naar de hoofdzaak, alle kenmerken, alle daaraan gerelateerde Informatieobjecten en alle andere gerelateerde gegevens (via rol, zaakobject, etc.) vormen gezamenlijk het zaakdossier.

Zaakcontactmomenten

Nieuw in versie 1.1.0

Voor versie 1.1.0 bestond er geen Contactmomenten, Klanten en Verzoeken API’s en werden klantcontacten in de Zaken API opgenomen. Vanaf versie 1.1.0 is deze resource deprecated - consumers horen van de contactmomenten API gebruik te maken.

Over een zaak kunnen één of meerdere klantinteracties plaatsvinden. De relatie met contactmomenten wordt gelegd via Zaakcontactmoment (Zaken API) en objectcontactmoment (Contactmomenten API). De relatie met verzoeken wordt gelegd via Zaakverzoek (Zaken API) en objectverzoek (Verzoeken API).

Specificatie van de Zaken API

Release Notes

De release notes van de versies staan beschreven op deze pagina.

Known Issues

De known issues van de versies staan beschreven op deze pagina.

Releases

Referentie-implementatie Zaken API

In release Zaken API 1.5.0 is het expand mechanisme toegevoegd aan de standaard. Om redenen zoals omschreven in deze pagina is daarom Zaken API versie 1.2.1 komen te vervallen.

Versie	Release datum	API specificatie
1.5.1	26-09-2023	ReDoc, Swagger
1.4.1	26-09-2023	ReDoc, Swagger
1.3.1	26-09-2022	ReDoc, Swagger
1.5.0	22-08-2023	ReDoc, Swagger
1.4.0	21-03-2023	ReDoc, Swagger
~~1.2.1~~	~~21-12-2022~~	VERVALLEN ~~ReDoc, Swagger~~
1.3.0	19-12-2022	ReDoc, Swagger, Diff
1.2.0	2021-08-31	ReDoc, Swagger, Diff
1.1.0	24-05-2021	ReDoc, Swagger, Diff
1.0.2	2020-06-12	ReDoc, Swagger, Diff
1.0.1	2019-12-16	ReDoc, Swagger, Diff
1.0.0	2019-11-18	ReDoc, Swagger

Specificatie van gedrag

Zaken APIen (ZRC) MOETEN aan twee aspecten voldoen:

de ZRC openapi.yaml MOET volledig geïmplementeerd zijn.
het run-time gedrag beschreven in deze standaard MOET correct geïmplementeerd zijn.

OpenAPI specificatie

Alle operaties beschreven in openapi.yaml MOETEN ondersteund worden en tot hetzelfde resultaat leiden als de referentie-implementatie van het ZRC.

Het is NIET TOEGESTAAN om gebruik te maken van operaties die niet beschreven staan in deze OAS spec, of om uitbreidingen op operaties in welke vorm dan ook toe te voegen.

Run-time gedrag

Bepaalde gedrageningen kunnen niet in een OAS spec uitgedrukt worden omdat ze businesslogica bevatten. Deze gedragingen zijn hieronder beschreven en MOETEN zoals beschreven geïmplementeerd worden.

Valideren `zaaktype` op de `Zaak`-resource (zrc-001)

aangepast in versie 1.5.0

Bij het aanmaken (zaak_create) of bijwerken (zaak_update, zaak_partial_update) van een zaak MOET de URL-referentie naar het zaaktype gevalideerd worden op het bestaan. Indien het ophalen van het zaaktype niet (uiteindelijk) resulteert in een HTTP 200 status code, MOET het ZRC antwoorden met een HTTP 400 foutbericht.

De provider MOET tevens valideren dat het opgehaalde zaaktype een zaaktype is conform de vigerende Catalogi API specificatie.

Garanderen uniciteit `bronorganisatie` en `identificatie` op de `Zaak`-resource (zrc-002)

Bij het aanmaken (zaak_create) en bijwerken (zaak_update en zaak_partial_update) MOET gevalideerd worden dat de combinatie identificatie en bronorganisatie uniek is, indien de identificatie door de consumer meegestuurd wordt.

Indien de identificatie niet door de consumer gestuurd wordt, dan MOET het ZRC de identificatie genereren op een manier die garandeert dat de identificatie uniek is binnen de bronorganisatie.

Valideren `informatieobject` op de `ZaakInformatieObject`-resource (zrc-003)

Bij het aanmaken (zaakinformatieobject_create) MOET de URL-referentie naar het informatieobject gevalideerd worden op het bestaan. Indien het ophalen van het object niet (uiteindelijk) resulteert in een HTTP 200 status code, MOET het ZRC antwoorden met een HTTP 400 foutbericht.

Valideren relatieinformatie op `ZaakInformatieObject`-resource (zrc-004)

Op basis van het objectType MOET de aardRelatie gezet worden conform het RGBZ. Omdat het objectType zaak is, moet aardRelatie gelijk zijn aan "hoort_bij".

De registratiedatum MOET door het systeem gezet worden op het moment van aanmaken.

Bij het updaten (zaakinformatieobject_update en zaakinformatieobject_partial_update) is het NIET TOEGESTAAN om de relatie te wijzingen. Bij andere waardes voor de attributen zaak, en informatieobject MOET het ZRC antwoorden met een HTTP 400 foutbericht.

Synchroniseren relaties met informatieobjecten (zrc-005)

Wanneer een relatie tussen een INFORMATIEOBJECT en een ZAAK gemaakt of bijgewerkt wordt, dan MOET het ZRC in het DRC ook deze relatie aanmaken/bijwerken.

Een voorbeeld:

Een informatieobject wordt gerelateerd aan een zaak door een consumer:

 POST https://zrc.nl/api/v1/zaakinformatieobjecten HTTP/1.0

 {
     "informatieobject": "https://drc.nl/api/v1/enkelvoudigeinformatieobjecten/1234",
     "zaak": "https://zrc.nl/api/v1/zaken/456789",
     "titel": "",
     "beschrijving": ""
 }

Het ZRC MOET de relatie spiegelen in het DRC:

 POST https://drc.nl/api/v1/objectinformatieobjecten HTTP/1.0

 {
     "informatieobject": "https://drc.nl/api/v1/enkelvoudigeinformatieobjecten/1234",
     "object": "https://zrc.nl/api/v1/zaken/456789",
     "objectType": "zaak"
 }

Merk op dat het aanmaken van de relatie niet gelimiteerd is tot het aanmaken via de API. Indien elders (bijvoorbeeld via een admininterface) een relatie tot stand kan komen, dan MOET deze ook gesynchroniseerd worden.

Data filteren bij de bron op basis van zaaktypes (zrc-006)

Het AC legt op het niveau van zaaktype vast welke operaties mogelijk zijn en wat de maximale vertrouwelijkheidaanduiding is voor een consumer.

Het ZRC MAG ENKEL zaken ontsluiten waarvan:

het zaaktype voorkomt in de autorisaties van de consumer.
de vertrouwelijkheidaanduiding lager of gelijk aan de maximale vertrouwelijkheidaanduiding is voor het betreffende zaaktype.

De API-specificatie legt vast welke scopes nodig zijn voor welke operaties. Een provider MOET operaties blokkeren op zaken waarvan de nodige scopes niet toegekend zijn voor het zaaktype van de betreffende zaak.

Indien een operatie niet toegelaten is, dan MOET de provider met een HTTP 403 foutbericht antwoorden.

Een consumer is verbonden aan het concept Applicatie, waarop autorisaties gedefinieerd worden. Het is mogelijk om op het niveau van Applicatie de vlag heeftAlleAutorisaties te zetten. Indien deze gezet is, dan MOET de provider alle operaties voor deze consumer toelaten, op alle zaken.

Afsluiten zaak (zrc-007)

Een zaak wordt afgesloten door een eindstatus toe te kennen aan een Zaak. Elk ZaakType MOET minimaal één StatusType kennen. De eindstatus binnen een ZaakType is het StatusType met het hoogste volgnummer.

Een Zaak MOET een Resultaat hebben voor deze afgesloten kan worden.

De Zaak.einddatum MOET logisch afgeleid worden uit het toekennen van de eindstatus via de Status.datumStatusGezet.

Als een Zaak een eindstatus heeft dan is de zaak afgesloten en mogen gegevens van de zaak niet meer aangepast worden (behalve om redenen van correctie). Dit MOET beveiligd worden met de scope zds.scopes.zaken.geforceerd-bijwerken. “Gegevens van de zaak” omvat hier ook de gerelateerde gegevens zoals klantcontacten, resultaat, rollen, statussen, zaakinformatieobjecten, zaakobjecten, zaakbesluiten en zaakeigenschappen.

Bij het afsluiten van een Zaak MOET het ZRC het Informatieobject.indicatieGebruiksrecht controleren van alle gerelateerde informatieobjecten. Deze MAG NIET null zijn, maar MOET true of false zijn. Indien dit niet het geval is, dan dient het ZRC een validatiefout te genereren met code indicatiegebruiksrecht-unset.

Heropenen zaak (zrc-008)

Bij het heropenen van een Zaak MOET de client een andere status toevoegen aan de zaak dan een eindstatus. Hiervoor MOET de client de scope zds.scopes.zaken.heropenen hebben.

Tevens MOET de provider de volgende velden op null zetten zodra een eindstatus wordt gewijzigd in een andere status:

Zaak.einddatum
Zaak.archiefactiedatum
Zaak.archiefnominatie

Vertrouwelijkheidaanduiding van een zaak (zrc-009)

Indien de client een vertrouwelijkheidaanduiding meegeeft bij het aanmaken of bewerken van een zaak, dan MOET de provider deze waarde toekennen. Indien de client deze niet expliciet toekent, dan MOET deze afgeleid worden uit Zaak.ZaakType.vertrouwelijkheidaanduiding.

Een Zaak response van de provider MOET altijd een geldige waarde voor vertrouwelijkheidaanduiding bevatten. Een client MAG een waarde voor vertrouwelijkheidaanduiding meesturen.

Valideren `communicatiekanaal` op de `Zaak` resource (zrc-010)

Bij het aanmaken (zaak_create) en bijwerken (zaak_update en zaak_partial_update) MOET de URL-referentie naar het communicatiekanaal gevalideerd worden op het bestaan. Indien het ophalen van het zaaktype niet (uiteindelijk) resulteert in een HTTP 200 status code, MOET het ZRC antwoorden met een HTTP 400 foutbericht.

Het ophalen van deze resource moet een JSON-document zijn met de vorm van een communicatiekanaal zoals gedocumenteerd op de referentielijsten-api:

{
    "url": "http://example.com",
    "naam": "string",
    "omschrijving": "string"
}

Valideren `relevanteAndereZaken` op de `Zaak`-resource (zrc-011)

De lijst relevanteAndereZaken bevat URL-referenties naar andere zaken. Elke URL-referentie MOET gevalideerd worden op het bestaan. Indien het ophalen van de url niet (uiteindelijk) resulteert in een HTTP 200 status code, MOET het ZRC antwoorden met een HTTP 400 foutbericht.

In het foutbericht MOET de naam binnen invalid-params dan relevanteAndereZaken.<index> zijn, waarbij index start bij 0.

Gegevensgroepen (zrc-012)

De client MAG gegevensgroepen zoals Zaak.verlenging en Zaak.opschorting meesturen met een waarde null om aan te geven dat er geen waarde gezet is. Dit is equivalent aan het niet-meesturen van de key in de request body. Als de client een (genest) object meestuurt, dan MOET de provider hierop de validatie van de gegevensgroep toepassen.

De provider MOET altijd de geneste structuur van de gegevensgroep antwoorden.

Valideren `hoofdzaak` op de `Zaak`-resource (zrc-013)

Bij het aanmaken of bewerken van een Zaak kan de hoofdzaak aangegeven worden. Dit MOET een geldige URL-referentie naar een Zaak zijn, indien opgegeven.

Indien de client een hoofdzaak opgeeft die zelf een deelzaak is (i.e. Zaak.hoofdzaak != null), dan moet het ZRC antwoorden met een HTTP 400 foutbericht (deelzaken van deelzaken zijn NIET toegestaan).

Indien de client een zaak bewerkt en diezelfde zaak als URL-referentie meegeeft als hoofdzaak, dan moet het ZRC antwoorden met een HTTP 400 foutbericht (een zaak MAG GEEN deelzaak van zichzelf zijn).

`Zaak.betalingsindicatie` en `Zaak.laatsteBetaaldatum` (zrc-014)

Indien de betalingsindicatie de waarde "nvt" heeft en een waarde gegeven is voor laatsteBetaaldatum, dan MOET het ZRC antwoorden met een HTTP 400 foutbericht. Bij alle andere waarden van betalingsindicatie MAG een waarde opgegeven worden voor laatsteBetaaldatum.

Indien een waarde ingevuld is voor laatsteBetaaldatum en de betalingsindicatie wordt gewijzigd naar "nvt", dan MOET de laatsteBetaaldatum op null gezet worden.

Valideren van producten en/of diensten bij een `Zaak` (zrc-015)

Bij het aanmaken (zaak_create) en bijwerken (zaak_update en zaak_partial_update) MOET de collectie productenOfDiensten worden getoetst tegen het Zaaktype.productenOfDiensten van het betreffende zaaktype. De producten en/of diensten van de zaak MOETEN een subset van de producten en/of diensten op het zaaktype zijn.

Valideren tegen de catalogus en bijhorende typen

Het zaaktype van een zaak legt vast wat de mogelijke waarden zijn voor gerelateerde resources aan zaken. Dit MOET gevalideerd worden door een provider.

Valideren dat het statustype van een Status bij het Zaak.zaaktype hoort (zrc-016)