Het is mogelijk terugmeldingen te genereren via een webservice (API), 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 gebruik wenst te maken van de webservice kan contact opnemen met digitaal.vlaanderen@vlaanderen.be. Indien de terugmelding moet geregistreerd worden vanuit de gebruiker van uw applicatie (user to service, vb. door een burger) bekijken we graag samen de beste oplossing. Wenst u als applicatie (service to service) aan te sluiten kunnen onderstaande stappen gevolgd worden.
Terugmelding opbouwen
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 GRB.
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 hier.
Het endpoint waarop een terugmelding kan geregistreerd worden is:
- Bèta omgeving: https://beta.api.melding.dev-vlaanderen.be/api/v1/meldingen
- Productie omgeving: https://prod.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:
- Bèta omgeving: https://beta.api.melding.dev-vlaanderen.be/api/v1/upload
- Productie omgeving: https://prod.api.melding.vlaanderen.be/api/v1/upload
Onderaan deze pagina is een JSON voorbeeld te vinden van een GRB terugmelding met 2 meldingsobjecten.
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:
- Bèta omgeving: https://beta.api.melding.dev-vlaanderen.be/api/v2/meldingen
- Productie omgeving: https://prod.api.melding.vlaanderen.be/api/v2/meldingen
Ophalen detail van een terugmelding:
- Bèta omgeving: https://beta.api.melding.dev-vlaanderen.be/api/v2/meldingen/{id}
- Productie omgeving: https://prod.api.melding.vlaanderen.be/api/v2/meldingen/{id}
Ophalen detail meldingsobjecten van een terugmelding:
- Bèta omgeving: https://beta.api.melding.dev-vlaanderen.be/api/v1/meldingen/{meldingId}/meldingsobjecten
- Productie omgeving: https://prod.api.melding.vlaanderen.be/api/v1/meldingen/{meldingId}/meldingsobjecten
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 te vinden.
{
"meldingsapplicatie": {
"id": "UniekIdApplicatie"
},
"meldingsorganisatie": {
"id": "123456"
},
"heeftDoelwitten": [
{
"attributen": [
{
"eigenschap": "https://beta.api.melding.dev-vlaanderen.be/api/v1/datasets/GRB/eigenschappen/TPC",
"voorgesteldeWaarde": "2/1"
},
{
"eigenschap": "https://beta.api.melding.dev-vlaanderen.be/api/v1/datasets/GRB/eigenschappen/GVC",
"voorgesteldeWaarde": "5"
},
{
"eigenschap": "https://beta.api.melding.dev-vlaanderen.be/api/v1/datasets/GRB/eigenschappen/GVCASB",
"voorgesteldeWaarde": "-8"
}
],
"meldingstype": "https://beta.api.melding.dev-vlaanderen.be/api/v1/meldingstypes/2",
"datumVaststelling": "2020-12-11T16:00:09.149416+01:00",
"gerelateerdeBody": [
{
"geometrie": "POLYGON((87109.71916161124 169895.7096379754,87126.46916161124 169905.7721379754,87130.03166161124 169899.8346379754,87113.09416161124 169889.8971379754,87109.71916161124 169895.7096379754))",
"beschrijving": "Opmerking"
}
]
},
{
"attributen": [
{
"eigenschap": "https://beta.api.melding.dev-vlaanderen.be/api/v1/datasets/GRB/eigenschappen/TPC",
"voorgesteldeWaarde": "2/2"
},
{
"eigenschap": "https://beta.api.melding.dev-vlaanderen.be/api/v1/datasets/GRB/eigenschappen/GVC",
"voorgesteldeWaarde": "3"
},
{
"eigenschap": "https://beta.api.melding.dev-vlaanderen.be/api/v1/datasets/GRB/eigenschappen/GVCASB",
"voorgesteldeWaarde": "-8"
}
],
"meldingstype": "https://beta.api.melding.dev-vlaanderen.be/api/v1/meldingstypes/2",
"datumVaststelling": "2020-12-11T16:00:09.149416+01:00",
"gerelateerdeBody": [
{
"geometrie": "POLYGON((87099.21916161124 169881.7096379754,87103.15666161124 169884.0846379754,87099.59416161124 169889.7721379754,87095.71916161124 169887.3971379754,87097.34416161124 169884.7721379754,87094.28166161124 169883.0846379754,87095.46916161124 169881.0846379754,87098.59416161124 169882.8346379754,87099.21916161124 169881.7096379754))",
"beschrijving": "Opmerking"
}
]
}
],
"meldingmodel": "https://beta.api.melding.dev-vlaanderen.be/api/v1/meldingmodellen/GRB",
"referentieMelder": "Mijn referentie"
}