Meldingsservice (GTMF-API)
Het is mogelijk terugmeldingen te genereren via API endpoints, die ingebouwd wordt in de applicatie van de melder/meldingsorganisatie zelf.
Om dit geïmplementeerd te krijgen komt er uiteraard wel wat ontwikkelwerk bij kijken, waardoor dit eerder weggelegd is voor organisaties die een constante stroom van meldingsobjecten willen genereren, zonder extra inspanningen en zonder een extra applicatie te moeten aanspreken.
De API wordt voorzien door de Generieke Terugmeldfaciliteit (GTMF). GTMF is een generieke bouwsteen die API endpoints voorziet voor het terugmelden van fouten en onvolledigheden in databronnen, het behandelen van de terugmeldingen en het opvolgen van de terugmeldingen.
Wie rechtstreeks gebruik wenst te maken van de endpoints van GTMF kan contact opnemen met digitaal.vlaanderen@vlaanderen.be(opent in uw e-mail applicatie).
Terugmelding opbouwen
Een melding bestaat uit één of meerdere meldingsobjecten. Het zijn de meldingsobjecten die concrete informatie omtrent de gemelde fout of onvolledigheid bevatten. Welke informatie een meldingsobject kan bevatten wordt beschreven in de dataset.
GTMF biedt een endpoint aan waarlangs de dataset, het model waarbinnen de terugmelding voor een bepaalde bron moet passen, kan opgevraagd worden.
Belangrijke velden per dataseteigenschap zijn:
Id: id van de dataseteigenschap door te geven bij het registreren van een terugmelding
Label: leesbaar label van de dataseteigenschap voor weergave in meldingsfront
Verplicht: geeft aan of een dataseteigenschap verplicht moet meegegeven worden om een terugmelding voor de bron te kunnen registreren
Meldbaar: geeft aan of de melder een nieuwe waarde voor de dataseteigenschap kan voorstellen of de huidige waarde achterliggend aangevuld moet worden door de meldingsapplicatie
Datatype: datatype waaraan de waarde voor de dataseteigenschap moet voldoen. Hier kunnen ook codelijsten voorkomen.
Naast specifieke dataseteigenschappen heeft een terugmelding en een onderliggend meldingsobject generieke eigenschappen. Eigenschappen die ongeacht de bron waarvoor een terugmelding wordt gemaakt kunnen voorkomen. Voor de bron GRB kan een meldingsobject volgende generieke eigenschappen hebben:
Beschrijving: vrij tekstveld voor opmerkingen
Geometrie: geometrie horend bij het meldingsobject
Url: link naar een bijlage
Op het niveau van de terugmelding kan een melder een eigen referentie (Referentie Melder) meegeven.
Link naar de dataset voor de Basiskaart Vlaanderen (GRB)(opent in nieuw venster).
Voor GRB is enkel het meldingstype “Ontbrekend” (Id 2) toegestaan. Meer details over de correcte samenstelling van een meldingsobject voor de bron GRB is op deze pagina terug te vinden.
Terugmelding registreren
De endpoints voor het registreren van een terugmelding zijn beveiligd via het Toegangs- en Gebruikersbeheer Vlaanderen ACM-IDM. Dit is het standaard toegangsbeheer voor websites van de Vlaamse Overheid. Meer info hierover vindt u op deze pagina over het aanmelden op het GRB-platform datavalidatie.
Het endpoint waarop een terugmelding kan geregistreerd worden is:
| Omgeving | URL |
|---|---|
| Staging | https://api.melding.staging-vlaanderen.be/api/v1/meldingen |
| Productie | https://api.melding.vlaanderen.be/api/v1/meldingen |
Indien het meldingsobject een bijlage bevat moet de bijlage eerst worden geüpload, vervolgens kan de url naar de bijlage aan het meldingsobject worden toegevoegd. Het endpoint waarlangs een bijlage kan geüpload worden is:
| Omgeving | URL |
|---|---|
| Staging | https://api.melding.staging-vlaanderen.be/api/v1/upload |
| Productie | https://api.melding.vlaanderen.be/api/v1/upload |
Terugmelding status opvolgen
Wie wenst kan de status van zijn terugmelding en zijn meldingsobject(en) opvolgen in de eigen meldingsfront. GTMF biedt hier verschillende endpoints voor aan. Ook deze endpoints zijn beveiligd via ACM-IDM.
Ophalen van een lijst van terugmeldingen:
| Omgeving | URL |
|---|---|
| Staging | https://api.melding.staging-vlaanderen.be/api/v2/meldingen |
| Productie | https://api.melding.vlaanderen.be/api/v2/meldingen |
Ophalen detail van een terugmelding:
| Omgeving | URL |
|---|---|
| Staging | https://api.melding.staging-vlaanderen.be/api/v2/meldingen/{id} |
| Productie | https://api.melding.vlaanderen.be/api/v2/meldingen/{id} |
Ophalen detail meldingsobjecten van een terugmelding:
| Omgeving | URL |
|---|---|
| Staging | https://api.melding.staging-vlaanderen.be/api/v1/meldingen/{meldingid}/meldingsobjecten |
| Productie | https://api.melding.vlaanderen.be/api/v1/meldingen/{meldingid}/meldingsobjecten |
De betekenis van elke status, kan u hier raadplegen.
Technische documentatie
Voor technische details verwijzen we graag door naar de swagger van GTMF:
Een lijst van foutcodes die kunnen voorkomen in de API is hier(opent in nieuw venster) te vinden.
Authenticatie van de GTMF endpoints
De GTMF endpoints zijn beveiligd via ACM/IDM. De authenticatie zal via een achtergrond proces gebeuren op basis van Client Credentials Grants (CCG). Meer informatie over CCG kan u terugvinden in de documentatie van ACM/IDM(opent in nieuw venster).