ZGW OpenZaak API Functionaliteit [Documentatie]

Deze pagina is alleen-lezen. Je kan de broncode bekijken maar niet veranderen. Neem contact op met de beheerder als je denkt dat dit niet klopt.
====== ZGW OpenZaak API Functionaliteit ======

{{tag>openwave:1.33:applicatiebeheer:functionaliteiten:zgw}}

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.\\
OpenWave ondersteunt:
  * **het opvragen van een lijst van mogelijke zaaktypen** zie GET //Alle ZAAKTYPEN opvragen// op [[https://vng-realisatie.github.io/gemma-zaken/standaard/catalogi/redoc-1.3.1#tag/zaaktypen/operation/zaaktype_list]]
  * **het opvragen van een lijst van mogelijke informatieobjecttypen** zie GET //Alle informatieobjecttypen opvragen// op [[https://vng-realisatie.github.io/gemma-zaken/standaard/catalogi/redoc-1.3.1#tag/informatieobjecttypen/operation/informatieobjecttype_list]]
  * **het verwerken van een creëer zaak bericht** zie POST //Maak een ZAAK aan// op [[https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/vng-Realisatie/zaken-api/1.5.1/src/openapi.yaml#tag/zaken/operation/zaak_create]]
  * ** het verwerken van een creeer zaakobject bericht van het objectType Adres** zie POST //Maak een ZAAKOBJECT aan// op [[https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/vng-Realisatie/zaken-api/1.5.1/src/openapi.yaml#tag/zaakobjecten/operation/zaakobject_create]]
  * **het verwerken van een creëer rol bericht bij een zaak** zie POST //Maak een ROL aan bij een ZAAK// op [[https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/vng-Realisatie/zaken-api/1.5.1/src/openapi.yaml#tag/rollen/operation/rol_create]]
  * **het verwerken van een geüpload document** zie POST //Maak een (ENKELVOUDIG) INFORMATIEOBJECT aan// op [[https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/VNG-Realisatie/gemma-documentregistratiecomponent/1.5.0/src/openapi.yaml#tag/enkelvoudiginformatieobjecten/operation/enkelvoudiginformatieobject_create]]
  * **het koppelen van een eerder geüpload document aan een zaak** zie POST //Maak een ZAAK-INFORMATIEOBJECT relatie aan// op [[https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/vng-Realisatie/zaken-api/1.5.1/src/openapi.yaml#tag/zaakinformatieobjecten/operation/zaakinformatieobject_create]]

Zie voor snel inzicht van de vereisten die de functioneel beheerder moet uitvoeren: [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:vereiste_minimale_instellingen]].

===== Ophalen Authorisatie Token =====

De bovenstaande POST en GET berichten moeten in de authorization header voorzien worden van een geldig Bearer JWT token.\\

Dit token kan worden opgevraagd op het endpoint: //base-url//<nowiki>/api/zgw/authentication/token/</nowiki>.\\
De //base_url// is de implementatie van OpenWave waar tegenaan gepraat moet worden. bijvoorbeeld: //<nowiki>https://acc.rommeldam.open-wave.nl</nowiki>//\\

<adm warning Whitelist>
De zender die hier om een authorisatietoken vraagt zal gewhitelist moeten worden. Dit kan in de tabellen tbendpointlist en tbipauthorisationlist onder de tegel [[openwave:1.33:applicatiebeheer:probleemoplossing:portalen_en_moduleschermen:beheerportaal_nieuw:tegels_kolom_gebruikers: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.
</adm>
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. \\
{{openwave:applicatiebeheer:probleemoplossing:programmablokken:zgw_tokenopvragen.png?600|zgw_tokenopvragen}}

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 [[openwave:1.33:applicatiebeheer:instellen_inrichten:2way_encryptie_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.:
<adm example Voorbeeld response>
  {
  "valid_from": "2024-07-29T11:19:49",
  "token_type": "Bearer",
  "expires_in": 300,
  "token": "eyJ0eXAiOiAiSldUIiwiYWxnIjogIkhTMjU2In0.eyJ1c2VyX2lkIjoiIiwiaXNzIjoiUmVtIEF1dG9tYXRpc2VyaW5nIiwidXNlcl9yZXByZXNlbnRhdGlvbiI6IiIsImlhdCI6MTcyMjI0NDc4OTQzNSwiY2xpZW50X2lkIjoiWkdXVGVzdCJ9.pEOZhPMLl5hC5jezq3MQYWHkApmFguruYe9aWTMCxVM"
  }
</adm>

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.

===== Vervolgberichten met token =====
==== Opvragen lijst van zaaktypen ====

Op het endpoint //base-url//<nowiki>/api/zgw/catalogi/api/v1/zaaktypen/</nowiki> 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 [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:opvragenlijstmetzgwzaaktypen]].

==== Opvragen lijst van informatieobjecttypen ====

Op het endpoint //base-url//<nowiki>/api/zgw/catalogi/api/v1/informatieobjecttypen/</nowiki> kan met een GET een lijst opgevraagd kan worden van de benaderbare informatieobejcttypen (documenttypes) uit OpenWave.
Bij succes wordt de responsecode 200 geretourneerd met in de body een geneste array van deze informatieobjecttypes met eigenschappen.\\
Zie [[.:zgw_open_zaak_api_functionaliteit:opvragen_lijst_informatieobjecttypen|]].

==== Creëer Nieuwe Zaak ====

Op het endpoint //base-url//<nowiki>/api/zgw/zaken/api/v1/zaken/</nowiki> 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 [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_zaak]].   

==== Creëer zaakobject  bij zaak ====

Op het endpoint //base-url//<nowiki>/api/zgw/zaken/api/v1/zaakobjecten/</nowiki> 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 [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeerzgwzaakobject]].

==== Creëer Rol en contactpersoon bij zaak ====

Op het endpoint //base-url//<nowiki>/api/zgw/zaken/api/v1/rollen/</nowiki> 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 [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:creeer_zgw_rol]].   

==== Uploaden van een document ====

Op het endpoint //base-url//<nowiki>/api/zgw/documenten/api/v1/enkelvoudiginformatieobjecten/</nowiki> 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 [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:upload_zgw_document]].   

==== Koppel document aan een zaak ====

Op het endpoint //base-url//<nowiki>/api/zgw/zaken/api/v1/zaakinformatieobjecten/</nowiki> 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 [[openwave:1.33:applicatiebeheer:probleemoplossing:programmablokken:zgw_open_zaak_api_functionaliteit:koppel_zgw_documentaanzaak]].