Ontwikkeling Terugmelding API voor bronhouders

Op dit moment wordt er hard gewerkt aan de ontwikkeling van de Terugmelding Bronhouder API. Deze API is een aanvulling op de al bestaande Terugmelding API, waarmee gebruikers al terugmeldingen kunnen doen en lezen vanuit een externe applicatie.

De nieuwe Terugmelding Bronhouder API maakt het mogelijk voor bronhouders om vanuit een eigen applicatie terugmeldingen in te lezen en te wijzigen (bijvoorbeeld van status). Bij het inlezen kunnen ook de gevoeligere velden van een terugmelding zoals e-mailadres en bijlagen bekeken worden. Vandaar dat een bronhouder alleen de terugmeldingen kan zien die aan diegene zijn toegewezen en de API beveiligd wordt via Oauth.

Net als de Terugmelding API werkt deze API generiek voor o.a. de BAG, BGT en BRT.

Afgelopen BGT ketendemo zijn er in de tweede helft van de sessie meer details over deze nieuwe API bekendgemaakt. Je kan de slides of de opname terugkijken via: DiS Online: BGT ketendemo | Publicatie | Geobasisregistraties

Binnenkort (verwachting: oktober) zullen we de documentatie en de acceptatietestomgeving beschikbaar maken. Heb je interesse om actief mee te testen? Stuur dan een mailtje naar terugmeldingapi@kadaster.nl
Eind dit jaar zal de API naar verwachting in productie worden genomen.

Heb je vragen of opmerkingen? Laat het ons weten!

In de API beschrijving 1.1.2 zie ik dat meldingen kunnen opgevraagd op basis van hun status. Wat ik niet terugvind is een mogelijkheid om vervolgens deze status te kunnen updaten zodat de meldingen kunnen worden afgemeld.

Hoi Rene, dit klopt. Met de huidige openbare API, de ‘Terugmelding API’, kan je geen statuswijzigingen doorvoeren.

Hier komt een nieuwe tweede API bij, de ‘Terugmelding Bronhouder API’ waarmee dit wel kan. De documentatie hiervoor is nog niet gepubliceerd.

Bij deze de eerste versie van de documentatie van de Terugmelding bronhouder API. Via de volgende link kunt u de specificatie vinden:

Terugmelding bronhouder API OAS3

Er wordt nog gewerkt aan een website waarin u de specificatie visueel kan bekijken inclusief aanvullende uitleg en een aanmeldformulier. Voorlopig kunt u deze specificatie alvast bekijken in uw eigen tool of bijvoorbeeld via Swagger UI.

Heeft u vragen? Laat dit weten via e-mail op terugmeldingapi@kadaster.nl

De nieuwe versie 1.0.1 van de Terugmelding bronhouder API is nu actief op de acceptatie omgeving. Er is een kleine wijziging doorgevoerd bij het doorsturen van een terugmelding naar een andere registratie, zie verder de change log in de Terugmelding bronhouder API OAS3.

Heeft u interesse om deel te nemen in het test traject met uw eigen applicatie? U kunt uw applicatie nu registreren via Aanvragen oAuth. U dient dan te kiezen voor de “Acceptatieomgeving”.

De documentatie is nu ook gepubliceerd op de PDOK website: Introductie - PDOK
Vragen? We horen het graag!

In het document:
https://api.acceptatie.kadaster.nl/tms/v1/terugmeldingbronhouder-instructies
wordt in stap 2 “Authorization token opvragen” een voorbeeld URL getoond. In deze URL is de client secret opgenomen. Is het wel de bedoeling dat de client secret in een URL wordt opgenomen?

Alleen in de aanvraag van het access token (stap 3) dient de client secret in de body van het POST request te staan.

Beste Rene,

Scherp gezien, dit staat inderdaad niet juist vermeld in de instructies. Dit wordt aangepast in de volgende versie. Bedankt voor het doorgeven!

Wat is het nut van de status Doorgestuurd? Eenmaal doorgestuurd naar een andere bronhouder zie ik deze melding niet meer. En het lijkt me dat de melding voor de andere bronhouder de status NIeuw moet hebben?

In de api-doc worden de volgende statussen genoemd:
NIEUW,IN_ONDERZOEK,GOEDGEKEURD,GEPARKEERD,DOORGESTUURD,AFGEWEZEN,AFGEROND

In de gebruikers interface worden de volgende statussen getoond:
Nieuw, In onderzoek, Goedgekeurd, Doorgestuurd, Afgewezen, Afgerond, Spam

Conclusie: GEPARKEERD = Spam ?

Doorsturen is niet wat je er van zou verwachten. Het is eigenlijk kopieren. Had verwacht dat een eenmaal doorgestuurde melding niet meer beschikbaar is voor de betreffende registratie, maar dat is niet zo. Er wordt een kopie gemaakt en vervolgens kan je er gewoon weer mee doorwerken.

Het zou handig zijn als in de API documentatie ook de 412 responses worden beschreven.
Bijvoorbeeld bij een PATCH request waarin de statusCode van een melding op GOEDGEKEURD wordt gezet krijg ik een http 412 met als content: reden: Aangeboden wijziging is al verwerkt. (wat is het nut hiervan?)

Zijn er nog andere waarmee ik rekening moet houden?

Goed punt: in de documentatie ontbreekt de status Spam. Dit is wel een andere status dan de status Geparkeerd.

  • Geparkeerd is een extra status voor alleen de BRT om aan te geven dat de terugmelding niet verder onderzocht kan worden totdat nieuw bronmateriaal (luchtfoto) beschikbaar is.
  • Spam is een status die er voor zorgt dat de terugmelding direct verwijderd wordt. Vandaar dat je deze status niet kan ‘GET-en’, maar wel PATCH-en. We gaan dit in de beschrijving toevoegen.

Bij een doorgestuurde melding wordt er automatisch een nieuwe terugmelding aangemaakt voor de andere registratie waar het naar toegestuurd is. ‘Doorgestuurd naar andere basisregistratie’ is net als ‘afgerond’ en ‘afgewezen’ een eindstatus: deze blijven een tijdje zichtbaar zodat de terugmelder kan zien wat er mee gebeurd is, maar verdwijnen dan. Technisch wordt inderdaad niet afgdwongen dat een eindstatus niet meer gewijzigd mag worden.

Oeps… deze ontbreekt inderdaad in de documentatie en gaan we toevoegen. Overigens zit hier ook nog een bugje in (zie ook de ‘let op’ in documentatie): Deze foutmelding treedt nu op bij dubbele én niet verwerkbare (ongeldige) berichten. Dit laatste gaan we nog aanpassen met (vermoedelijk) een http statuscode 422 (Unprocessable Entity). Mogelijk dus dat er een foutje in het bericht zit als deze niet al een keer ingeschoten is.

Bedankt voor de feedback!

In de werkwijze die wij willen gaan hanteren worden alle nieuwe meldingen beoordeeld in de online beheerapplicatie bij kadaster. Meldingen die we gaan oppakken krijgen de status goedgekeurd. Goedgekeurde meldingen worden opgepakt door onze software via de API en krijgen uiteindelijk de status Afgehandeld.
Wat ik mis in de online beheerapplicatie is een filter op status zodat je snel een overzicht kan krijgen van bijvoorbeeld alleen de nieuwe meldingen.

In de beheerapplicatie zitten blijkbaar al wat gedachten over hoe ik hiermee moet omgaan. Zo mag ik een status niet terug op Nieuw zetten. Waarom niet ? Wat voor beperkingen zitten er allemaal in?

De registratie waar een melding voor wordt aangemaakt is afhankelijk van het zoomniveau? Gaat de gemiddelde gebruiker dat begrijpen. Waarom niet expliciet aangeven voor welke registratie het is?

Filterfunctionaliteit op status zal toegevoegd worden aan de beheerapplicatie en beschikbaar zijn bij livegang.

De API dwingt inderdaad nu technisch geen bepaalde status flow af. Betekent natuurlijk niet dat er geen logische flow is. Een bronhouder is wettelijk verplicht om een terugmelding binnen enkele werkdagen in onderzoek te nemen. Status ‘Nieuw’ impliceert dat de bronhouder nog niet naar de terugmelding gekeken heeft. Het is daarom niet logisch dat een bronhouder een terugmelding van bijvoorbeeld ‘in onderzoek’ naar ‘nieuw’ zet en daarom hebben we dit ook niet mogelijk gemaakt in de beheerapplicatie.

Ik gok dat je het hier hebt over Verbeter de Kaart? Via de API moet je expliciet aangeven voor welke registratie je meldt. Bij Verbeter de Kaart wordt die voor de gebruiker als service voor je ingevuld, afhankelijk van op welke kaart je meldt. Juist met het idee dat een gemiddelde gebruiker niet hoeft te weten of ie op de BRT of BGT meldt (en wat een BGT of BRT precies is): je ziet iets op de kaart wat niet klopt en je meldt het direct om dat te verbeteren. En ja, dat werkt al meer dan vijf jaar prima :slight_smile:

Vandaag is versie 1.0.2 van de Terugmelding bronhouder API verschenen. In deze versie is header veld API-Version voortaan niet meer nodig, zie verder de change log bij PDOK.

Verder is de documentatie bijgewerkt: een kleine wijziging in de instructies en er is extra toelichting opgenomen bij de PATCH voorbeelden in de OAS3 inclusief een uitleg van de statusCode SPAM. Tenslotte is de response HTTP 412 nu beschreven bij een PATCH.

Update: de extra toelichting bij de PATCH voorbeelden is door technische redenen helaas (nog) niet te zien op de PDOK site. Dit is wel te zien door de OAS3 te bekijken met uw eigen tool of Swagger UI.

1 like

Vandaag is versie 1.0.3 van de Terugmelding bronhouder API verschenen. In deze versie wordt bij een niet verwerkbaar bericht bij een PATCH voortaan een andere statuscode terug gegeven namelijk 422 Unprocessable Entity.

Voor meer informatie zie de PDOK site.

De documentatie van de Terugmelding bronhouder API is voortaan alleen te bekijken op de hier boven genoemde PDOK site (of eventueel direct via OAS3).

De eerder genoemde (tijdelijke) documentatie links in de oude berichten die beginnen met https://api.acceptatie.kadaster.nl werken niet meer.

De acceptietest voor de Terugmelding bronhouder API is succesvol afgesloten. Hartelijk dank voor de input!
Bij deze kunnen we aankondigen dat de Terugmelding bronhouder API op 15 februari in productie zal gaan.

Meer informatie kunt u hier vinden.

Indien u nog input en/of bevindingen heeft voor de Terugmelding bronhouder API, dan kunt u die uiteraard blijven geven via dit forum of het eerder aangegeven e-mail adres.

1 like