Dit is een oude revisie van het document!
ZGW OpenZaak API Functionaliteit
In het kader van Zaak Gericht Werken (ZGW) kan OpenWave zich gedragen als een Open Zaak Systeem waarmee gecommuniceerd kan worden conform de OpenZaak API.
Zie voor snel inzicht van de vereisten die de functioneel beheerder moet uitvoeren: OpenZaak API minimale configuratie.
Alle onderstaande POST en GET berichten moeten in de authorization header voorzien worden van een geldig Bearer JWT token, behalve het opvragen van de token zelf
Ophalen catalogus-informatie
Om cataglogus-informatie (meta-informatie cq identifiers over zaaktypen, eigenschapen ,rollen, documenttypes e.d.) op te halen is het volgende berichtenverkeer mogelijk:
Zie ook: https://vng-realisatie.github.io/gemma-zaken/standaard/catalogi/redoc-1.3.1#tag/catalogussen
Aanbrengen van zaken
Uploaden van document
Ophalen Authorisatie Token
Alle POST en GET berichten moeten in de authorization header voorzien worden van een geldig Bearer JWT token.
Dit token kan worden opgevraagd met een POST op het endpoint: base-url/api/zgw/authentication/token/.
De base_url is de implementatie van OpenWave waar tegenaan gepraat moet worden. bijvoorbeeld: https://acc.rommeldam.open-wave.nl
Whitelist
De zender die hier om een authorisatietoken vraagt zal gewhitelist moeten worden. Dit kan in de tabellen tbendpointlist en tbipauthorisationlist onder de tegel Endpoints whitelist op het nieuwe beheerportaal onder de kolom Gebruikers.
In de tabel tbendpointlist zal minimaal het endpoint api/zgw gedefinieerd moeten zijn met daaronder (in de tabel tbipauthorisationlist) het IP-adres van de zender.
In de authorization header van dit POST bericht om een token aan te vragen dienen alleen de parameters Username en Password onder Basic Authorization te worden gevuld.
Per implementatie worden deze username en password uitgereikt en vastgelegd in de medewerkerstabel.
In de tabel tbmedewerkers moet hiertoe een nieuwe medewerkerskaart aangemaakt worden met:
- Loginnaam (dvloginnaam) = de uit te reiken Username
- Client secret bij loginnaam t.b.v. accesstoken (dvclientsecret) = het uit te reiken Password. Let op: De ingetoetste waarde kan door OpenWave automatisch gecrypt worden opgeslagen indien Getal1 van de instelling Sectie: Encryption en Item: Method de waarde 3 heeft. Zie 2-way encryptie van externe wachtwoorden. Aan de zender moet dus de ongecrypte versie worden uitgereikt.
De (robot)-medewerker moet in dienst zijn (vervaldatum leeg of > vandaag) en de kolom met de omschrijving 1=robot, 2=browser, 3=beide (dnmaginmap) moet de waarde 3 hebben.
Response bericht
In de body van het retourbericht bij responsecode 201 wordt de token afgeleverd bijv.:
Voorbeeld response
{
"valid_from": "2024-07-29T11:19:49",
"token_type": "Bearer",
"expires_in": 300,
"token": "eyJ0eXAiOiAiSldUIiwiYWxnIjogIkhTMjU2In0.eyJ1c2VyX2lkIjoiIiwiaXNzIjoiUmVtIEF1dG9tYXRpc2VyaW5nIiwidXNlcl9yZXByZXNlbnRhdGlvbiI6IiIsImlhdCI6MTcyMjI0NDc4OTQzNSwiY2xpZW50X2lkIjoiWkdXVGVzdCJ9.pEOZhPMLl5hC5jezq3MQYWHkApmFguruYe9aWTMCxVM"
}
De token is 300 seconden geldig in dit voorbeeld (is tevens de defaultwaarde).
In Getal1 van de instelling Sectie: Logon en Item: TokenExpireSeconds kan desgewenst een afwijkende duur worden opgegeven.
Indien het token niet kon worden gegenereerd wordt in de body van het responsebericht met een responsecode anders dan 200 of 201 de oorzaak daarvan weergegeven.
Een succesvol uitgetrokken token wordt opgeslagen in de tabel tbaccesstoken benaderbaar via het detailscherm van de robotmedewerker (beheerportaal) waaraan de token verbonden is.
Een token blijft 8 uur bestaan, daarna wordt deze opgeschoond. Van deze 8 uur kan afgeweken worden met Getal2 van de instelling Sectie: Logon en Item: TokenExpireSeconds. Bij de waarde 0 of kleiner wordt niet opgeschoond.
GET berichten ophalen Catalogus-infromatie
Alle onderstaande GET berichten moeten in de authorization header voorzien worden van een geldig Bearer JWT token
Opvragen lijst van zaaktypen
Op het endpoint base-url/api/zgw/catalogi/api/v1/zaaktypen/ kan met een GET een lijst opgevraagd kan worden van de benaderbare zaaktype-uuids uit OpenWave met bijbehorende roltype-uuids en informatieobjecttype-uuids (documenttypes).
Bij succes wordt de responsecode 200 geretourneerd met in de body een geneste array van deze zaaktypes met eigenschappen.
Zie Opvragen lijst met zaaktypes conform OpenZaak API.
Opvragen lijst van informatieobjecttypen
Op het endpoint base-url/api/zgw/catalogi/api/v1/informatieobjecttypen/ kan met een GET een lijst opgevraagd kan worden van de benaderbare informatieobjecttypen (documenttypes) uit OpenWave.
Bij succes wordt de responsecode 200 geretourneerd met in de body een geneste array van deze informatieobjecttypes met eigenschappen.
Zie Opvragen lijst met informatieobjecttypen conform OpenZaak API.
Opvragen lijst van zaakobjecttypen
Op het endpoint base-url/api/zgw/catalogi/api/v1/zaakobjecttypen/ kan met een GET een lijst opgevraagd kan worden van de benaderbare zaakobjecttypen uit OpenWave. OpenWave ondersteunt vooralsnog alleen de objecttypen adres en medewerker
Bij succes wordt de responsecode 200 geretourneerd met in de body een geneste array van deze zaakobjecttypes met eigenschappen.
Zie Opvragen lijst met zaakobjecttypen conform OpenZaak API|.
Opvragen lijst van roltypen
Op het endpoint base-url/api/zgw/catalogi/api/v1/roltypen/ kan met een GET een lijst opgevraagd kan worden van de benaderbare roltypen (tbzgwroltypes) uit OpenWave met de zaaktypes waaraan deze rollen gekoppeld zijn.
Een roltype is een unieke combinatie uit de koppeltabel tussen een adressoort (tbadressoort) en zaaktype (tbsoortomgverg of tbsoortovverg).
Bij succes wordt de responsecode 200 geretourneerd met in de body een geneste array van deze roltypes met eigenschappen. Bijv. initiator, belanghebbende e.d.
Zie Opvragen lijst met roltypen conform OpenZaak API|.
Opvragen lijst van eigenschappen
Op het endpoint base-url/api/zgw/catalogi/api/v1/eigenschappen/ kan met een GET een lijst opgevraagd kan worden van de extra eigenschappen die aan een zaak kunnen worden toegvoegd met de zaaktypes waaraan deze eigenschappen gekoppeld zijn.
Bij succes wordt de responsecode 200 geretourneerd met in de body een geneste array van deze eigenschappen. Bijv. om een zaak te kopelen aan een inrichting of om een domein toe te voegen: informatie die niet in de zaakobjecttypen en creeerzaak is opgenomen.
Zie Opvragen lijst met eigenschappen conform OpenZaak API
POST berichten creeeren /complementeren zaak
Alle onderstaande POST berichten moeten in de authorization header voorzien worden van een geldig Bearer JWT token
Creëer Nieuwe Zaak
Op het endpoint base-url/api/zgw/zaken/api/v1/zaken/ kan een POST worden geplaatst waarmee OpenWave een nieuwe zaak kan aanmaken.
Bij succes wordt de responsecode 201 geretourneerd met in de body onder meer de uitgetrokken unieke UUID-code voor de zaak, waarmee in een vervolgbericht een contactrol kan worden aangemaakt en waarmee één of meer geüploade documenten aan deze zaak kunnen worden gekoppeld.
Zie Creëer ZGW zaak conform OpenZaak API.
Creëer zaakobject bij zaak
Op het endpoint base-url/api/zgw/zaken/api/v1/zaakobjecten/ kan een POST worden geplaatst waarmee OpenWave een zaakobject van objecttype adres kan aanmaken en koppelen aan een zaak. Bij succes wordt de responsecode 201 geretourneerd met in de body onder meer de uitgetrokken unieke UUID-code voor de combinatie zaak/zaakobject. Zie Creëer zaakobject conform OpenZaak API.
Creëer Rol en contactpersoon bij zaak
Op het endpoint base-url/api/zgw/zaken/api/v1/rollen/ kan een POST worden geplaatst waarmee OpenWave een contactpersoon onder een bepaalde rol kan aanmaken. Bij succes wordt de responsecode 201 geretourneerd met in de body onder meer de uitgetrokken unieke UUID-code voor de combinatie zaak/rol/contactadres. Zie Creëer rol en contactadres conform OpenZaak API.
Maak zaakeigenschap aan bij zaak
Op het endpoint base-url/api/zgw/zaken/api/v1/zaken/{identifier}/zaakeigenschappen kan een POST worden geplaatst waarmee OpenWave een bepaalde zaakeigenschap kan toevoegen bijv een inrichtingsnr op grond waarvan de eerder aangemaakte zaak gekoppeld kan worden aan die inrichting.
De {identifier} in bovengenoemd endpoint is de UUID die geretourneerd is aan een eerder gecreeerde zaak (Creëer ZGW zaak conform OpenZaak API)
Bij succes wordt de responsecode 201 geretourneerd met in de body onder meer een uitgetrokken fake unieke UUID-code.
Zie Maak zaakeigenschap aan conform OpenZaak API
Koppel document aan een zaak
Op het endpoint base-url/api/zgw/zaken/api/v1/zaakinformatieobjecten/ kan een POST worden geplaatst met de UUID van een zaak (zie response bij creëer nieuwe zaak) en een UUID van een eerder geüpload document (zie uploaden van document). OpenWave kan hiermee het document aan een zaak koppelen en dat document op de juiste bestemming plaatsen.
Bij succes wordt de responsecode 200 geretourneerd met in de body onder meer de uitgetrokken unieke UUID-code voor de combinatie document/zaak.
Zie Koppel Document aan Zaak conform OpenZaak API.
Uploaden document
Alle onderstaande POST berichten moeten in de authorization header voorzien worden van een geldig Bearer JWT token
Uploaden van een document
Op het endpoint base-url/api/zgw/documenten/api/v1/enkelvoudiginformatieobjecten/ kan een POST worden geplaatst met een document dat in het vervolgbericht Koppel Document Aan Zaak aan een zaak wordt gekoppeld. Bij succes wordt de responsecode 201 geretourneerd met in de body onder meer de uitgetrokken unieke UUID-code voor het document. Zie Uploaden document conform OpenZaak API.