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 informatie

De API is toegankelijk via:

Productie

https://openapi.binnenbeter.nl/api

Pilot

https://openapipilot.binnenbeter.nl/api

Swagger documentatie:

Productie:

https://openapi.binnenbeter.nl/api/swagger-ui/index.html

Pilot:

https://openapipilot.binnenbeter.nl/api/swagger-ui/index.html

De 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 API

De Open API ondersteunt onder andere:

Authenticatie

Authenticatie via JWT tokens.

Meldingen ophalen

Meldingen filteren op status, categorie, datum, locatie enzovoort.

Meldingen aanmaken

Nieuwe meldingen kunnen extern worden geregistreerd.

Workflow uitvoeren

Workflowacties uitvoeren zoals afhandelen of doorzetten.

Bestanden beheren

Bestanden uploaden, downloaden, verwijderen en zichtbaar maken.

Melderinformatie ophalen

Contactgegevens van melders opvragen.

Masterdata ophalen

Categorieën, workflowstatussen, meldbronnen en objecten ophalen.

Objectinformatie koppelen

Spatial/BOR-objecten koppelen aan meldingen.

SCIP integraties

Ondersteuning voor SCIP notificaties. 

1. Authenticatie

De BinnenBeter API vereist authenticatie via:

POST /v1/login

Na succesvolle authenticatie ontvang je een JWT-token.

1.1 Verkrijgen van inloggegevens

Gemeenten kunnen API toegang aanvragen via de BinnenBeter servicedesk.

De servicedesk verstrekt:

• gebruikersnaam
• wachtwoord
• tenantnaam
• API-rol(len)

1.2 Inloggen via /v1/login

Verzoek:

{
  "tenant": "gemeente",
  "username": "gebruikersnaam",
  "password": "wachtwoord"
}

1.3 Succesvolle authenticatie

Bij succesvolle authenticatie ontvang je:

{
  "token":"...",
  "tokenType":"Bearer",
  "expiresIn":3600
}

1.4 Gebruik JWT token

Bij vervolgverzoeken:

Authorization: Bearer {JWT_TOKEN}

1.5 Foutmeldingen

1.6 Veiligheidsadvies

• Bewaar tokens veilig
• Deel tokens nooit
• Gebruik HTTPS
• Verander wachtwoorden regelmatig

2. Meldingen ophalen

De API ondersteunt meerdere manieren om meldingen op te halen.

2.1 Get all reports

Endpoint:

GET /v1/reports

Hiermee haal je meerdere meldingen op.

Ondersteunde filters:

Resultaten worden standaard gesorteerd op nieuwste melding eerst. 

2.2 Get report by ID

Endpoint:

GET /v1/reports/{id}

Haalt één melding inclusief details op.

Parameters:

Mogelijke statussen:

2.3 Overzicht meldingvelden

Respons kan bevatten:

• reportId
• description
• status
• workflowStatus
• categories
• locatie
• meldingsdatum
• planning
• behandelaar
• coordinator
• inspecteur
• aannemer
• customFields
• spatialObject
• bestanden
• afbeeldingen
• meldwijze
• gekoppelde meldingen

2.4 Tijden ophalen in gewenste tijdzone

Ondersteund:

timezone=NL
timezone=UTC

Toepasbaar op:

GET /v1/reports
GET /v1/reports/{id}

3. Meldingen aanmaken

Nieuwe meldingen kunnen extern geregistreerd worden.

Endpoint:

POST /v1/reports

Verplicht:

Optioneel:

• description
• reporter
• createdDate
• objectId

Voorbeeld:

{
 "categoryId":10,
 "location":{
   "latitude":52.1,
   "longitude":5.1
 },
 "description":"Kapotte lichtmast",
 "reportSourceId":1
}

4. Workflow acties

4.1 Beschikbare acties ophalen

Endpoint:

GET /v1/reports/{id}/actions

Geeft mogelijke workflowacties terug.

Bijvoorbeeld:

• Afhandelen
• Doorzetten
• Inplannen
• Heropenen

4.2 Workflow uitvoeren

Endpoint:

PUT /v1/reports/{id}/actions

Ondersteunt:

• solveDescription
• solveDate
• comments
• bestanden

4.3 Workflowstatus wijzigen

Endpoint:

PUT /v1/reports/{id}/workflowstatus/{wfsId}

Workflowstatussen ophalen:

GET /v1/masterdata/workflowstatuses

5. Interne opmerkingen toevoegen

Endpoint:

POST /v1/reports/{id}/comments

Voegt interne opmerkingen toe aan meldingen.

6. Bestanden beheren

6.1 Bestanden ophalen

GET /v1/reports/{id}/files

6.2 Bestand uploaden

POST /v1/reports/{id}/files

Types:

• INCIDENT
• SOLUTION
• OTHER

6.3 Bestand downloaden

GET /v1/reports/files/{id}

6.4 Bestand verwijderen

DELETE /v1/reports/files/{id}

6.5 Bestand zichtbaarheid aanpassen

PUT /v1/reports/files/{id}/visibility

Instellingen:

• zichtbaar voor melder
• zichtbaar voor externe partij

7. Assets downloaden

Endpoint:

GET /v1/assets/{id}

Ondersteunde bestanden:

• PDF
• DOCX
• PNG
• JPG
• GIF
• overige bijlagen

8. Melderinformatie ophalen

Endpoint:

GET /v1/reports/{id}/reporters

Beschikbaar:

• naam
• telefoon
• e-mail
• notificaties
• contact toegestaan

Let op AVG-regelgeving.

9. Masterdata ophalen

Beschikbare endpoints:

Hoofdcategorieën:

GET /v1/masterdata/category/main

Subcategorieën:

GET /v1/masterdata/category/sub

Workflowstatussen:

GET /v1/masterdata/workflowstatuses

Meldbronnen:

GET /v1/masterdata/reportsources

Custom velden:

GET /v1/masterdata/categories/sub-categories/{id}/customfields

10. Spatial objecten ophalen

Spatial/BOR objecten ophalen rondom locatie.

Endpoint:

GET /v1/masterdata/object-types/{id}/objects

Verplicht:

• lon
• lat
• objecttype

Objecten binnen 200 meter worden teruggegeven.

Ondersteuning

Voor 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.