Technische documentatie meldingen
Op deze pagina is de technische documentatie om meldingen aan te maken binnen het Gebouwen- en Adressenregister te vinden.
Meldingsmodel
Wanneer je een melding aanmaakt, kies je eerst een meldingsmodel. Dit model bepaalt welke informatie nodig is en hoe je melding verder wordt verwerkt.
Aan elk meldingsmodel zijn een databron en een dataset gekoppeld:
De databron geeft aan over welke bron je melding gaat.
De dataset bepaalt welke gegevens je moet invullen om je melding goed te beschrijven en de levensloop van de melding.
Meldingsobjectmodel
Een melding bestaat uit één of meerdere meldingsobjecten. Afhankelijk van het meldingsmodel waarvoor je meldt, kunnen er één of meerdere meldingsobjecten per melding toegestaan zijn. Voor het Gebouwen- en Adressenregister geldt dat een melding altijd precies één meldingsobject bevat.
De meldingsobjecten bevatten de concrete informatie over de gemelde fout of onvolledigheid. De dataset beschrijft welke informatie een meldingsobject kan bevatten, in de vorm van dataseteigenschappen die je moet of kan invullen.
GTMF biedt een endpoint aan waarmee je de beschrijving van een dataset kan opvragen. Voor het Gebouwen- en Adressenregister is deze datasetbeschrijving beschikbaar via het daarvoor voorziene endpoint.
Belangrijke velden per dataseteigenschap zijn:
Velden | Betekenis |
|---|---|
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. Meldingen voor de bron Gebouwen- en Adressenregister zal steeds een nieuwe waarde moeten worden meegegeven. Het is dan aan de behandelaar om het correcte object te selecteren (o.b.v. de meegegeven geometrie) en de melding te analyseren. |
Datatype | Datatype waaraan de waarde voor de dataseteigenschap moet voldoen. Hier kunnen ook codelijsten voorkomen. |
Naast specifieke dataseteigenschappen hebben een terugmelding en onderliggende meldingsobjecten generieke eigenschappen. Eigenschappen die ongeacht de databron waarvoor een terugmelding wordt gemaakt kunnen voorkomen. Voor de bron Gebouwen- en Adressenregister kan een meldingsobject volgende generieke eigenschappen hebben:
Velden | Betekenis |
|---|---|
Geometrie | De geometrie horende bij het meldingsobject. De geometrie dient steeds een polygoon te zijn. |
URL | De URL is de link naar een bijlage. |
Op het niveau van de terugmelding kan een melder volgende meegeven:
Velden | Betekenis |
|---|---|
Referentie melder | Een eigen referentie waarmee de melder de terugmelding later makkelijker kan opzoeken of identificeren. |
Samenvatting | Kan gebruikt worden om de terugmelding en de informatie die eraan gekoppeld is samen te vatten en de behandeling ervan te vergemakkelijken. |
Dataseteigenschappen van het Gebouwen- en Adressenregister
Bij het aanmaken van een Gebouwen- en Adressenregister terugmelding, dient de melder exact één meldingsobject toe te voegen. Via het meldingstype duidt de melder aan of gaat om een fout of een onvolledigheid. De lijst van meldingstypes kan je hier terugvinden. Voor terugmelding voor het Gebouwen- en Adressenregister moet je steeds meldingstype ‘Fout' gebruiken.
De dataseteigenschappen beschreven in de Gebouwen- en Adressenregister dataset vind jehieronder terug. De volledige datasetbeschrijving voor het Gebouwen- en Adressenregister vind je hier terug.
Oorzaak
Dit is verplicht.
De reden waarom je een meldingsobject aanmaakt:
Reden | Betekenis |
|---|---|
Nieuw / Ontbrekend | Er is een nieuw gebouwen- en adressenregisterobject ontstaan. |
Attribuut gewijzigd / foutief | Er is iets gewijzigd aan de codering of attributen dat impact heeft op de opname in het gebouwen- en adressenregister. |
Geometrie gewijzigd / foutief | Er is iets gewijzigd aan de geometrie dat impact heeft op de opname in het gebouwen- en adressenregister. |
Attribuut & geometrie gewijzigd / foutief | Er is iets gewijzigd aan de codering, attributen of geometrie dat impact heeft op de opname in het gebouwen- en adressenregister. |
Verwijderd / Overbodig | Er is iets verdwenen. |
Thema
Dit is verplicht.
De entiteit waar de ‘Oorzaak’ impact op heeft. Er kan uit volgende thema's gekozen worden: Adressen, Straatnamen en gebouweenheden.
OVO-code
Dit is verplicht.
De OVO-code van de stad of gemeente waarvoor de terugmelding is bestemd. Een codelijst wordt voorzien met daarin de OVO-codes van de steden en gemeenten in Vlaanderen.
Opvolgen van de levensloop
Meldingen indienen
Hieronder vind je een voorbeeld van een request om een melding in te dienen.
{
"meldingsapplicatie": {
"id": "LARA"
},
"meldingsorganisatie": {
"id": "OVO002949"
},
"samenvatting": "Mijn melding betreft een probleem met X...",
"heeftDoelwitten": [
{
"heeftOnderwerp": "Leeg te laten wanneer je een ontbrekend object meldt. Of de PURI van het object waar iets mis mee is",
"attributen": [
{
"eigenschap": "https://api.melding.vlaanderen.be/api/v1/datasets/GRAR/eigenschappen/GRAR_Oorzaak",
"voorgesteldeWaarde": "1"
},
{
"eigenschap": "https://api.melding.vlaanderen.be/api/v1/datasets/GRAR/eigenschappen/GRAR_Thema",
"voorgesteldeWaarde": "1"
},
{
"eigenschap": "https://api.melding.vlaanderen.be/api/v1/datasets/GRAR/eigenschappen/GRAR_OvoCode",
"voorgesteldeWaarde": "OVO002067",
"huidigeWaarde": "OVO002067"
}
],
"meldingstype": "https://api.melding.vlaanderen.be/api/v1/meldingstypes/1",
"datumVaststelling": "2023-07-10T10:02:19.441Z",
"gerelateerdeBody": [
{
"geometrie": "POLYGON((87109.71916161124 169895.7096379754,87126.46916161124 169905.7721379754,87130.03166161124 169899.8346379754,87113.09416161124 169889.8971379754,87109.71916161124 169895.7096379754))",
"beschrijving": "Een beschrijving van het probleem",
"url": "https://api.melding.vlaanderen.be/api/v1/uploads/29dfde06-f6c8-4756-8052-34cfe04f5d20"
}
]
}
],
"meldingmodel": "https://api.melding.vlaanderen.be/api/v1/meldingmodellen/GRAR"
}Iedere melding wordt ingediend via een meldingsapplicatie en meldingsorganisatie. Deze waarden zijn afkomstig van de toepassing via waar de melding wordt ingediend en de organisatie die de toepassing beheerd. Alle meldingsobjecten (afgeleid uit het veld <heeftDoelwitten>) dienen te voldoen aan het aangeduide meldingsmodel.
Een melding indienen met bijlage
Voorafgaand aan het aanmaken van uw melding, kan je een bestand uploaden. Dit bestand kan je dan toevoegen als bijlage aan de melding. De ondersteunde bestandstypes zijn: .jpg, .png, .jpeg en .pdf. De maximum bestandsgrootte is 30 MB. Er kan slechts 1 bestand tegelijkertijd geüpload worden.
Een bestand uploaden kan via het endpoint <[POST] /api/v1/upload>. Na het uploaden ontvang je een URL. Deze URL kan je dan meegeven bij het indienen van uw terugmelding.
Meldingen opvragen
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.
De meldingen die een gebruiker te zien krijgt zijn de volgende:
U bent indiener van de melding.
De melding werd ingediend door een medewerker van jouw organisatie.
U bent behandelaar van de melding.
U bent bronhouder van de dataset waartoe de melding behoort.
Ophalen van de lijst van terugmeldingen:
Ophalen van het detail van een terugmelding:
Meldingen behandelen
Meldingsobjecten worden toegekend aan behandelende steden en gemeente. Indien een melding is toegekend aan uw organisatie enbeschikt over de rol behandelaar (zie sectie Authorisatie), dan kan je de terugmelding behandelen door deze van status te veranderen. Bij het wijzigen van de status kan je twee toelichtingen meegeven: één voor de indiener en één voor intern gebruik.
Om de status te wijzigen, kan je een POST request uitvoeren tegen endpoint </api/v1/meldingen/{meldingId}/meldingsobjecten/{meldingsobjectId}/status/{statusCode}>. De mogelijke waarden voor het onderdeel <statusCode> vind je hieronder. Het is de numerieke waarde die je moet gebruiken.
Status | Statuscode |
|---|---|
In onderzoek | 2 |
Afgewezen | 3 |
Opgelost | 4 |
Gesloten | 5 |
De toelichting moet je meegeven in de request body, zie een voorbeeld hieronder.
{
"toelichtingStatusWijzigingMelder": "een toelichting van de statuswijziging richting de indiener van de melding",
"toelichtingIntern": "een interne toelichting gericht aan andere behandelaars en/of bronhouder van de dataset. Niet zichtbaar voor de indiener"
}Authenticatie
De GTMF endpoints zijn beveiligd via ACM/IDM:
Indien je je als gebruiker wenst te authenticeren, kan je de ‘namens een gebruiker’ flow volgen.
Wens je meldingen aan te maken en/of op te volgen via een achtergrond proces, dan kan je terugvallen op de ‘server-naar-server’ flow.
Flow 'Namens een gebruiker'
In het geval dat je je als gebruiker wenst te authenticeren, dan zal je terugvallen op token exchange. Meer informatie over token exchange kan je vinden in de documentatie van ACM/IDM. Hieronder vind je alvast twee interessante links:
Flow 'Server-naar-server'
In het geval dat je je als achtergrond proces wenst te authenticeren, dan zal je terugvallen op de Client Credentials Grant (CCG). Meer informatie over CCG kan je vinden in de documentatie van ACM/IDM. Hieronder vind je alvast een link:
Authorisatie
Eens geauthenticeerd, zal het GTMF endpoint bepalen welke informatie je mag zien en welke acties je mag nemen. Deze logica is gebaseerd op de scopes aanwezig in het access token. De relevante scopes zijn:
Scopes | Betekenis |
|---|---|
Medewerker | U hebt het recht een terugmelding aan te maken. De API zal in dit geval ook de OVO-code en/of KBO-nummer scopes uitlezen om uw organisatie te bepalen. |
GTMF_Beh_GRAR_OVOCODE | Deze scope zal worden toegekend aan behandelende stad- en gemeentemedewerkers. Dit recht staat een medewerker toe om op te treden als behandelaar van een melding. Ook hier zal de API de OVO-code en/of KBO-nummer scopes uitlezen zodat u enkel de meldingen te zien krijgt die bestemd zijn voor uw organisatie. |
GTMF_Bro_GRAR_Alle | Dit recht zal worden toegekend aan de bronhouder. In dit geval medewerkers van de Basisregisters binnen Digitaal Vlaanderen. |
Indien je gebruik maakt van een token exchange, zal je ook steeds onderstaande scopes moeten bevragen.
vo_ovocode
vo_kbonummer
Meer technische documentatie
Meer technische details zijn te vinden op de swagger documentatie van de GTMF API:
Omgeving | URL |
|---|---|
Staging | https://api.melding.staging-vlaanderen.be/swagger/index.html |
Productie |
Een lijst van foutcodes die kunnen voorkomen in de API is hier te vinden.
Uw applicatie aansluiten
De endpoints voor het registreren van een terugmelding zijn beveiligd via ACM/IDM, zie ook meer informatie bij ‘Authenticatie’ en ‘Authorisatie’.
Het GTMF team kent per aansluitende applicatie een uniek Id toe voor de meldingsapplicatie en meldingsorganisatie.
Wens je via uw eigen applicatie meldingen aan te maken voor het Gebouwen- en Adressenregister, gelieve dan contact op te nemen via digitaal.vlaanderen@vlaanderen.be met als onderwerp ‘Meldingen aanmaken voor het Gebouwen- en Adressenregister via mijn eigen applicatie'.
Best Address Anomaly Service
Via de BeSt anomalie service kunnen gebruikers van BeSt fouten in de BeSt-gegevens melden. BOSA stelt hiervoor een API ter beschikking waarbij hun afnemers een ANO rond adressen, straatnamen, postcode en gemeenten kunnen doorsturen naar de gewesten: API. Meer informatie over BeSt kan je hier vinden.
De BeSt anomalie service stuurt de fout per email door naar Digitaal Vlaanderen. Digitaal Vlaanderen zal hiervoor een melding aanmaken en aan de juiste behandelaar (stad of gemeente) koppelen. De behandelaar kan makkelijk de afkomst herkennen in de referentie: BOSA – Anomalie nr.
In de melding vindt de gemeente een omschrijving van de fout en eventueel de correcties die de indiener van de melding/anomalie voorstelt. De melding bevat ook een bijlage van de mail. Hierin zijn de contactgegevens van de indiener mee opgenomen zodat de stad of gemeente de indiener kan contacteren voor eventueel verdere inlichtingen en om te laten weten wanneer de fout werd opgelost.