API Client

De API-clients van het Handhavingsplatform worden beheerd via het Beheerportaal van ACM. Via dit portaal kunnen aansluiters autonoom een API-client aanvragen. Eens de API-client is goedgekeurd en de correcte scopes zijn toegewezen is het mogelijk om de API aan te roepen.

Deze pagina beschrijft de verschillende stappen die nodig zijn om de API aan te roepen:

Er moet een API-client aangevraagd en goedgekeurd worden in het Beheerportaal.
Er moet gebruikmakend van de API-client een access token aangevraagd worden bij ACM.
Met het access token kan de API aangeroepen worden.

Nieuwe API client aanvragen

Het aanvragen van een API client verloopt via het Beheerportaal van ACM:

T&I: https://beheerportaal-ti.vlaanderen.be
Productie: https://beheerportaal.vlaanderen.be

Om te kunnen aanmelden op deze pagina moet je het gebruikersrecht API_beheerder en Client-Beheerder hebben. Dit kan je aanvragen bij je lokale beheerder.

Via “Mijn OAuth Clients“ kan een aansluiter een nieuwe API-client aanvragen voor het Handhavingsplatform.

In het volgende scherm kan de authenticatie methode en verdere informatie aangevuld worden. De API van het Handhavingsplatform kan gevonden worden met volgende referentie:

T&I: Handhavingsdatabank API T&I
Productie: Handhavingsdatabank API

Als de API-client is aangevraagd moet de aansluiter wachten totdat deze is goedgekeurd. Samen met het goedkeuren van de API client zal de beheerder van AJH de correcte scopes toewijzen naargelang de functie van de aansluiter.

Voor beboetingsinstanties is dit ajh_handhavingsplatform_aansluiter_beboetingsinstantie.
Voor inspectiediensten is dit ajh_handhavingsplatform_aansluiter_inspectiedienst.

Deze scopes worden gebruikt voor autorisatie doeleinden binnen het Handhavingsplatform. Het is dus belangrijk dat ze meegegeven worden bij het aanvragen van een access token bij ACM.

Access token aanvragen

Voor het aanroepen van de API moet er eerst een access token aangevraagd worden bij ACM. Dit is mogelijk via de OAuth server-naar-server flow.

De documentatie van ACM https://authenticatie.vlaanderen.be/docs/beveiligen-van-api/oauth-rest/rest-server2server/aanvraag-access-token/ bevat codevoorbeelden voor het aanvragen van een access token.

Het is belangrijk dat volgende scopes meegegeven worden bij het aanvragen van het access token:

vo_info
- Deze scope wordt gebruikt om te valideren voor welke entiteit de client informatie aanmaakt of opvraagt.
ajh_handhavingsplatform_aansluiter_beboetingsinstantie
- Deze scope is enkel van toepassing voor beboetingsinstanties en wordt gebruikt voor autorisatie doeleinden.
ajh_handhavingsplatform_aansluiter_inspectiedienst
- Deze scope is enkel van toepassing voor inspectiediensten en wordt gebruikt voor autorisatie doeleinden.

API aanroepen

De API is bereikbaar via volgende URL’s:

Integration: https://integration.handhaving.api.tni-vlaanderen.be/api
- Deze omgeving moet gebruikt worden door aansluiters die geen MAGDA-integratie hebben.
T&I: https://handhaving.api.tni-vlaanderen.be/api
Productie: https://handhaving.api.vlaanderen.be/api

Het access token van ACM moet als Bearer token meegeven worden via de Authorization header.

voorbeeld

curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -d "{}" \
     -X POST \
     https://handhaving.api.tni-vlaanderen.be/api/aansluiter/v1/handhavingsdossiers/zoeken