Koppelprofiel Zaaksysteem API: verschil tussen versies

Uit ZaaksysteemWiki
Ga naar: navigatie, zoeken
(→‎Instellingen)
 
(18 tussenliggende versies door dezelfde gebruiker niet weergegeven)
Regel 3: Regel 3:
  
 
= Instellingen =
 
= Instellingen =
 +
Zie ook de Zaaksysteem API Manual: <nowiki>https://<domeinnaam>/man/Zaaksysteem::Manual::API::V1</nowiki>.
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Regel 23: Regel 24:
 
<li>Behandelen: De externe partij mag gegevens uitlezen en wijzigingen uitvoeren</li>
 
<li>Behandelen: De externe partij mag gegevens uitlezen en wijzigingen uitvoeren</li>
 
</ul>
 
</ul>
 +
 +
Let op: Deze instelling is onderhevig aan de rechten van de medewerker. Als de medewerker enkel raadpleegrechten heeft zal de instelling 'Behandelen' deze rechten op 'Raadplegen' houden. Als de medewerker behandelrechten heeft zal de instelling 'Raadplegen' de rechten juist beperkt houden tot 'Raadplegen'.
 
|-
 
|-
 
|Zoekopdracht
 
|Zoekopdracht
Regel 51: Regel 54:
  
 
Deze informatieset wordt uitgebreid met alle informatie die zichtbaar is binnen de geselecteerde zoekopdracht (dus op basis van de geselecteerde filters en kolommen).
 
Deze informatieset wordt uitgebreid met alle informatie die zichtbaar is binnen de geselecteerde zoekopdracht (dus op basis van de geselecteerde filters en kolommen).
 +
|-
 +
|Gebruik API voor externe systeemberichten
 +
|Geef hier aan of de API gebruikt kan worden voor het versturen van externe systeemberichten in de zaaktype regels
 
|-
 
|-
 
|Trigger URL
 
|Trigger URL
−
|De URL waar de externe partij berichtgeving van zaaksysteem op moet ontvangen. Zie ook: [http://wiki.zaaksysteem.nl/Zaaktypebeheer_Regels#Zaaksysteem_API:_Api-Zaken Regel - Extern systeembericht]
+
|De URL waar de externe partij berichtgeving van zaaksysteem op moet ontvangen. Zie ook: [[Zaaktypebeheer_Regels#Zaaksysteem_API:_Api-Zaken|Regel - Extern systeembericht]]
  
 
Let op: Dit moet een https:// zijn.
 
Let op: Dit moet een https:// zijn.
Regel 59: Regel 65:
 
|Trigger CA Certificaat
 
|Trigger CA Certificaat
 
|Eventueel het certificaat voor de trigger URL
 
|Eventueel het certificaat voor de trigger URL
 +
|-
 +
|-
 +
|Trigger Client Certificaat
 +
|Eventueel het certificaat dat door Zaaksysteem.nl is aangemaakt (publiek en privaat). Het publieke deel van dit certificaat moet bij de ontvanger van het triggerbericht geïnstalleerd staan
 
|-
 
|-
 
|API URI
 
|API URI
 
|
 
|
 +
|-
 +
|Example: CSV via powershell
 +
|Met dit windows commando (powershell) kan de output van de ingestelde zoekopdracht geëxporteerd worden als CSV.
 +
|-
 +
|Example: CSV via Curl
 +
|Met dit unix commando (curl) kan de output van de ingestelde zoekopdracht geëxporteerd worden als CSV.
 
|}
 
|}
 +
 +
= API v1 =
 +
Zaaksysteem biedt de mogelijkheid om een opgeslagen zoekopdracht te selecteren die vervolgens op te vragen is door <omgeving>/api/v1/case te bezoeken.
 +
De uitvoer van <omgeving>/api/v1/case is in JSON formaat.
 +
 +
= API2CSV =
 +
Om de integratie met andere systemen makkelijker te maken biedt Zaaksysteem ook de mogelijkheid om de API v1 uitvoer in een comma separated value (CSV) formaat uit te voeren.
 +
Op deze pagina staat beschreven hoe beheerders deze functionaliteit op hun omgeving kunnen installeren, en hoe gebruikers de uitvoer in CSV kunnen opvragen.
 +
 +
Let op: Integratie met andere applicaties is mogelijk. Deze applicaties moeten een http get commando uit kunnen voeren waarbij enkele headers meegegeven dienen te worden (zie het Curl commando voor meer info voor welke headers).
 +
 +
=== Instructie voor Windows omgeving ===
 +
Voer het volgende Powershell commando uit in een terminal (anders dan de Powershell terminal):
 +
<pre>
 +
powershell -ExecutionPolicy unrestricted -Command "$cmd = (New-Object Net.WebClient);
 +
$cmd.Headers.Add(\"API-Interface-Id\",\"71\"); $cmd.Headers.Add(\"API-Key\",\"1234\");
 +
$cmd.DownloadString(\"https://quarterly.zaaksysteem.nl/app/api2csv\");
 +
</pre>
 +
Het resultaat is de output van de opgeslagen zoekopdracht in CSV formaat. Deze kan gekopiëerd worden voor gebruik in een andere applicatie. De response kan ook direct opgeslagen worden door aan het Powershell commando '  | Out-File –FilePath c:\folder\structuur\bestandsnaam.csv toe te voegen.
 +
 +
<pre>
 +
powershell -ExecutionPolicy unrestricted -Command "$cmd = (New-Object Net.WebClient);
 +
$cmd.Headers.Add(\"API-Interface-Id\",\"71\"); $cmd.Headers.Add(\"API-Key\",\"1234\");
 +
$cmd.DownloadString(\"https://quarterly.zaaksysteem.nl/app/api2csv\"); | Out-File –FilePath c:\path\bestandsnaam.csv
 +
</pre>
 +
 +
=== Instructie voor UNIX / Mac omgeving ===
 +
Voer het volgende Powershell commando uit in een terminal:
 +
<pre>
 +
curl --header "API-Interface-Id: 71" --header "API-Key: 1234" "https://quarterly.zaaksysteem.nl/app/api2csv"
 +
</pre>
 +
 +
Het resultaat is de output van de opgeslagen zoekopdracht in CSV formaat. Deze kan gekopiëerd worden voor gebruik in een andere applicatie. De response kan ook direct opgeslagen worden door aan het Curl commando ' bestandsnaam.txt' toe te voegen.
 +
 +
<pre>
 +
curl --header "API-Interface-Id: 71" --header "API-Key: 1234" "https://quarterly.zaaksysteem.nl/app/api2csv" > file.txt
 +
</pre>
 +
 +
 +
===Meer zoekresultaten ontvangen===
 +
De Zaaksysteem API geeft standaard 10 zoekresultaten terug. <br/>
 +
Wil je meer of minder resultaten terugkrijgen via API2CSV, dan kan je gebruik maken van de paginering parameters van de Zaaksysteem API. Dat zijn rows_per_page en page.
 +
Met rows_per_page bepaal je hoeveel resultaten je per uitvoering van het cURL / Powershell commando krijgt,
 +
met page bepaal je welke pagina van de resultaten je terug krijgt.
 +
Dus als er 100 resultaten zijn, en je stelt rows_per_page in op 50, dan zijn er 2 pagina's met resultaten. Je zou dan twee keer het commando moeten uitvoeren, een keer met page=1 en een keer met page=2.
 +
Gebruik de parameters door een vraagteken achter het cURL / Powershell commando te plaatsen, gevolgd door een of meerdere van de parameters, gescheiden door een vraagteken.
 +
<pre>
 +
?rows_per_page=50
 +
?rows_per_page=30?page=2
 +
?page=6</pre>
 +
Voorbeeld
 +
<pre>curl --header "API-Interface-Id: 71" --header "API-Key: 1234" "https://quarterly.zaaksysteem.nl/app/api2csv?rows_per_page=50&page=1"
 +
of:
 +
powershell -ExecutionPolicy unrestricted -Command "$cmd = (New-Object Net.WebClient); $cmd.Headers.Add(\"API-Interface-Id\",\"71\");
 +
$cmd.Headers.Add(\"API-Key\",\"1234\"); $cmd.DownloadString(\"https://quarterly.zaaksysteem.nl/app/api2csv?rows_per_page=50&page=1\");</pre>
 +
 +
=== Troubleshooting ===
 +
Wanneer er geen resultaten zijn moet eerst gecontroleerd worden of de gebruiker die ingesteld staat bij 'Medewerker' in het Zaaksysteem API koppelprofiel überhaupt resultaten krijgt in Uitgebreid Zoeken. Daarna kan gecontroleerd worden of de medewerker wel raadpleegrechten heeft tot de zaaktype(n).

Huidige versie van 5 jun 2019 om 09:13

Met deze koppeling kan een externe partij gegevens uit het zaaksysteem uitlezen en/of het zaaksysteem berichten aan een externe partij sturen.

Instellingen

Zie ook de Zaaksysteem API Manual: https://<domeinnaam>/man/Zaaksysteem::Manual::API::V1.

Titel Omschrijving
Versie De versie van dit koppelprofiel
API sleutel De unieke API sleutel waarmee de externe partij kan authenticeren
Medewerker De externe partij heeft hetzelfde toegangsniveau als de geselecteerde gebruiker: Zaken raadplegen en wijzigingen aan zaken aanbrengen. Eventuele wijzigingen die de externe partij binnen zaaksysteem uitvoert zullen namens deze gebruiker gedaan worden.
Toegangsniveau Het toegangsniveau dat deze API verschaft:
  • Raadplegen: De externe partij mag gegevens uitlezen
  • Behandelen: De externe partij mag gegevens uitlezen en wijzigingen uitvoeren

Let op: Deze instelling is onderhevig aan de rechten van de medewerker. Als de medewerker enkel raadpleegrechten heeft zal de instelling 'Behandelen' deze rechten op 'Raadplegen' houden. Als de medewerker behandelrechten heeft zal de instelling 'Raadplegen' de rechten juist beperkt houden tot 'Raadplegen'.

Zoekopdracht Standaard verschaft de API toegang tot de volgende metainformatie van een zaak:
case.number Zaaknummer
case.status Zaakstatus
case.subject_external Extra informatie PIP
case.phase Zaakfase
case.result Zaakresultaat
case.date_of_registration Registratiedatum
case.date_target Streefafhandeldatum

Deze informatieset wordt uitgebreid met alle informatie die zichtbaar is binnen de geselecteerde zoekopdracht (dus op basis van de geselecteerde filters en kolommen).

Gebruik API voor externe systeemberichten Geef hier aan of de API gebruikt kan worden voor het versturen van externe systeemberichten in de zaaktype regels
Trigger URL De URL waar de externe partij berichtgeving van zaaksysteem op moet ontvangen. Zie ook: Regel - Extern systeembericht

Let op: Dit moet een https:// zijn.

Trigger CA Certificaat Eventueel het certificaat voor de trigger URL
Trigger Client Certificaat Eventueel het certificaat dat door Zaaksysteem.nl is aangemaakt (publiek en privaat). Het publieke deel van dit certificaat moet bij de ontvanger van het triggerbericht geïnstalleerd staan
API URI
Example: CSV via powershell Met dit windows commando (powershell) kan de output van de ingestelde zoekopdracht geëxporteerd worden als CSV.
Example: CSV via Curl Met dit unix commando (curl) kan de output van de ingestelde zoekopdracht geëxporteerd worden als CSV.

API v1

Zaaksysteem biedt de mogelijkheid om een opgeslagen zoekopdracht te selecteren die vervolgens op te vragen is door <omgeving>/api/v1/case te bezoeken. De uitvoer van <omgeving>/api/v1/case is in JSON formaat.

API2CSV

Om de integratie met andere systemen makkelijker te maken biedt Zaaksysteem ook de mogelijkheid om de API v1 uitvoer in een comma separated value (CSV) formaat uit te voeren. Op deze pagina staat beschreven hoe beheerders deze functionaliteit op hun omgeving kunnen installeren, en hoe gebruikers de uitvoer in CSV kunnen opvragen.

Let op: Integratie met andere applicaties is mogelijk. Deze applicaties moeten een http get commando uit kunnen voeren waarbij enkele headers meegegeven dienen te worden (zie het Curl commando voor meer info voor welke headers).

Instructie voor Windows omgeving

Voer het volgende Powershell commando uit in een terminal (anders dan de Powershell terminal): 

powershell -ExecutionPolicy unrestricted -Command "$cmd = (New-Object Net.WebClient);
$cmd.Headers.Add(\"API-Interface-Id\",\"71\"); $cmd.Headers.Add(\"API-Key\",\"1234\"); 
$cmd.DownloadString(\"https://quarterly.zaaksysteem.nl/app/api2csv\");

Het resultaat is de output van de opgeslagen zoekopdracht in CSV formaat. Deze kan gekopiëerd worden voor gebruik in een andere applicatie. De response kan ook direct opgeslagen worden door aan het Powershell commando ' | Out-File –FilePath c:\folder\structuur\bestandsnaam.csv toe te voegen. 

powershell -ExecutionPolicy unrestricted -Command "$cmd = (New-Object Net.WebClient);
$cmd.Headers.Add(\"API-Interface-Id\",\"71\"); $cmd.Headers.Add(\"API-Key\",\"1234\"); 
$cmd.DownloadString(\"https://quarterly.zaaksysteem.nl/app/api2csv\"); | Out-File –FilePath c:\path\bestandsnaam.csv

Instructie voor UNIX / Mac omgeving

Voer het volgende Powershell commando uit in een terminal: 

curl --header "API-Interface-Id: 71" --header "API-Key: 1234" "https://quarterly.zaaksysteem.nl/app/api2csv"

Het resultaat is de output van de opgeslagen zoekopdracht in CSV formaat. Deze kan gekopiëerd worden voor gebruik in een andere applicatie. De response kan ook direct opgeslagen worden door aan het Curl commando ' bestandsnaam.txt' toe te voegen. 

curl --header "API-Interface-Id: 71" --header "API-Key: 1234" "https://quarterly.zaaksysteem.nl/app/api2csv" > file.txt


Meer zoekresultaten ontvangen

De Zaaksysteem API geeft standaard 10 zoekresultaten terug.
Wil je meer of minder resultaten terugkrijgen via API2CSV, dan kan je gebruik maken van de paginering parameters van de Zaaksysteem API. Dat zijn rows_per_page en page. Met rows_per_page bepaal je hoeveel resultaten je per uitvoering van het cURL / Powershell commando krijgt, met page bepaal je welke pagina van de resultaten je terug krijgt. Dus als er 100 resultaten zijn, en je stelt rows_per_page in op 50, dan zijn er 2 pagina's met resultaten. Je zou dan twee keer het commando moeten uitvoeren, een keer met page=1 en een keer met page=2. Gebruik de parameters door een vraagteken achter het cURL / Powershell commando te plaatsen, gevolgd door een of meerdere van de parameters, gescheiden door een vraagteken. 

?rows_per_page=50
?rows_per_page=30?page=2
?page=6

Voorbeeld 

curl --header "API-Interface-Id: 71" --header "API-Key: 1234" "https://quarterly.zaaksysteem.nl/app/api2csv?rows_per_page=50&page=1"
of:
powershell -ExecutionPolicy unrestricted -Command "$cmd = (New-Object Net.WebClient); $cmd.Headers.Add(\"API-Interface-Id\",\"71\");
 $cmd.Headers.Add(\"API-Key\",\"1234\"); $cmd.DownloadString(\"https://quarterly.zaaksysteem.nl/app/api2csv?rows_per_page=50&page=1\");

Troubleshooting

Wanneer er geen resultaten zijn moet eerst gecontroleerd worden of de gebruiker die ingesteld staat bij 'Medewerker' in het Zaaksysteem API koppelprofiel überhaupt resultaten krijgt in Uitgebreid Zoeken. Daarna kan gecontroleerd worden of de medewerker wel raadpleegrechten heeft tot de zaaktype(n).

Overgenomen van "http://wiki.zaaksysteem.nl/index.php?title=Koppelprofiel_Zaaksysteem_API&oldid=10032"