Open API 2.0

Open API Deze documentatie beschrijft de werking van Open API 2.0 van BinnenBeter. Deze API biedt een gestandaardiseerde manier voor gemeenten en andere gebruikers om meldingen, melders, bestanden, workflowstatussen en masterdata op te halen en te beheren binnen BinnenBeter.API toegang en endpoint informatieDe API is toegankelijk via:Productiehttps://openapi.binnenbeter.nl/apiPilothttps://openapipilot.binnenbeter.nl/apiSwagger documentatie:Productie:https://openapi.binnenbeter.nl/api/swagger-ui/index.htmlPilot:https://openapipilot.binnenbeter.nl/api/swagger-ui/index.htmlDe Swagger UI biedt een interactieve omgeving waarin beschikbare endpoints, parameters, request- en responseformaten bekeken en getest kunnen worden.Let op:Nieuwe functionaliteiten verschijnen vaak eerst op pilot.Test integraties altijd op pilot voordat deze richting productie gaan.Endpoints kunnen afhankelijk zijn van rechten en API-rollen. Belangrijke functies van de APIDe Open API ondersteunt onder andere:AuthenticatieAuthenticatie via JWT tokens.Meldingen ophalenMeldingen filteren op status, categorie, datum, locatie enzovoort.Meldingen aanmakenNieuwe meldingen kunnen extern worden geregistreerd.Workflow uitvoerenWorkflowacties uitvoeren zoals afhandelen of doorzetten.Bestanden beherenBestanden uploaden, downloaden, verwijderen en zichtbaar maken.Melderinformatie ophalenContactgegevens van melders opvragen.Masterdata ophalenCategorieën, workflowstatussen, meldbronnen en objecten ophalen.Objectinformatie koppelenSpatial/BOR-objecten koppelen aan meldingen.SCIP integratiesOndersteuning voor SCIP notificaties. 1. AuthenticatieDe BinnenBeter API vereist authenticatie via:POST /v1/loginNa succesvolle authenticatie ontvang je een JWT-token.1.1 Verkrijgen van inloggegevensGemeenten kunnen API toegang aanvragen via de BinnenBeter servicedesk.De servicedesk verstrekt:gebruikersnaamwachtwoordtenantnaamAPI-rol(len)1.2 Inloggen via /v1/loginVerzoek:{ "tenant": "gemeente", "username": "gebruikersnaam", "password": "wachtwoord" }1.3 Succesvolle authenticatieBij succesvolle authenticatie ontvang je:{ "token":"...", "tokenType":"Bearer", "expiresIn":3600 }1.4 Gebruik JWT tokenBij vervolgverzoeken:Authorization: Bearer {JWT_TOKEN}1.5 FoutmeldingenStatusOmschrijving400Ongeldig verzoek401Onjuiste gegevens403Geen toegang500Serverfout1.6 VeiligheidsadviesBewaar tokens veiligDeel tokens nooitGebruik HTTPSVerander wachtwoorden regelmatig2. Meldingen ophalenDe API ondersteunt meerdere manieren om meldingen op te halen.2.1 Get all reportsEndpoint:GET /v1/reportsHiermee haal je meerdere meldingen op.Ondersteunde filters:FilterOmschrijvingpagePaginanummersizeRecords per paginafromReportIdMeldingen vanaf IDfromLastModifiedGewijzigd na datumentryDateStartStartdatumentryDateEndEinddatummainCategoriesHoofdcategoriesubCategoriesSubcategoriereportStatusesHoofdstatusworkflowStatusesWorkflowstatusresidencesWoonplaatshasSpatialObjectAlleen gekoppelde objectentimezoneUTC of NLResultaten worden standaard gesorteerd op nieuwste melding eerst. 2.2 Get report by IDEndpoint:GET /v1/reports/{id}Haalt één melding inclusief details op.Parameters:ParameterVerplichtidJatimezoneNeeMogelijke statussen:StatusBetekenis200Gevonden401Geen toegang403Geen rechten404Niet gevonden2.3 Overzicht meldingveldenRespons kan bevatten:reportIddescriptionstatusworkflowStatuscategorieslocatiemeldingsdatumplanningbehandelaarcoordinatorinspecteuraannemercustomFieldsspatialObjectbestandenafbeeldingenmeldwijzegekoppelde meldingen2.4 Tijden ophalen in gewenste tijdzoneOndersteund:timezone=NL timezone=UTCToepasbaar op:GET /v1/reports GET /v1/reports/{id}3. Meldingen aanmakenNieuwe meldingen kunnen extern geregistreerd worden.Endpoint:POST /v1/reportsVerplicht:VeldcategoryIdlocationreportSourceIdOptioneel:descriptionreportercreatedDateobjectIdVoorbeeld:{ "categoryId":10, "location":{ "latitude":52.1, "longitude":5.1 }, "description":"Kapotte lichtmast", "reportSourceId":1 }4. Workflow acties4.1 Beschikbare acties ophalenEndpoint:GET /v1/reports/{id}/actionsGeeft mogelijke workflowacties terug.Bijvoorbeeld:AfhandelenDoorzettenInplannenHeropenen4.2 Workflow uitvoerenEndpoint:PUT /v1/reports/{id}/actionsOndersteunt:solveDescriptionsolveDatecommentsbestanden4.3 Workflowstatus wijzigenEndpoint:PUT /v1/reports/{id}/workflowstatus/{wfsId}Workflowstatussen ophalen:GET /v1/masterdata/workflowstatuses5. Interne opmerkingen toevoegenEndpoint:POST /v1/reports/{id}/commentsVoegt interne opmerkingen toe aan meldingen.6. Bestanden beheren6.1 Bestanden ophalenGET /v1/reports/{id}/files6.2 Bestand uploadenPOST /v1/reports/{id}/filesTypes:INCIDENTSOLUTIONOTHER6.3 Bestand downloadenGET /v1/reports/files/{id}6.4 Bestand verwijderenDELETE /v1/reports/files/{id}6.5 Bestand zichtbaarheid aanpassenPUT /v1/reports/files/{id}/visibilityInstellingen:zichtbaar voor melderzichtbaar voor externe partij7. Assets downloadenEndpoint:GET /v1/assets/{id}Ondersteunde bestanden:PDFDOCXPNGJPGGIFoverige bijlagen8. Melderinformatie ophalenEndpoint:GET /v1/reports/{id}/reportersBeschikbaar:naamtelefoone-mailnotificatiescontact toegestaanLet op AVG-regelgeving.9. Masterdata ophalenBeschikbare endpoints:Hoofdcategorieën:GET /v1/masterdata/category/mainSubcategorieën:GET /v1/masterdata/category/subWorkflowstatussen:GET /v1/masterdata/workflowstatusesMeldbronnen:GET /v1/masterdata/reportsourcesCustom velden:GET /v1/masterdata/categories/sub-categories/{id}/customfields10. Spatial objecten ophalenSpatial/BOR objecten ophalen rondom locatie.Endpoint:GET /v1/masterdata/object-types/{id}/objectsVerplicht:lonlatobjecttypeObjecten binnen 200 meter worden teruggegeven.OndersteuningVoor API toegang, vragen of technische ondersteuning kan contact worden opgenomen met de BinnenBeter servicedesk.Wij adviseren om altijd eerst de Swagger-documentatie te raadplegen voor de meest actuele endpoints en parameters.