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 op te halen uit BinnenBeter.

API toegang en endpoint informatie

In de Swagger UI kun je eenvoudig de verschillende beschikbare endpoints ontdekken, evenals de benodigde parameters, request- en responseformaten, en voorbeeldverzoeken. Dit biedt een interactieve manier om de API te verkennen, en biedt gedetailleerde informatie over hoe je verzoeken kunt uitvoeren.

Belangrijke functies van de API

  • Authenticatie: Om de API te gebruiken, moeten gebruikers zich eerst authentiseren met een JWT-token.
  • Meldingen ophalen: De API biedt de mogelijkheid om meldingen op te halen op basis van filters zoals status, datum, locatie en meer.
  • Afbeeldingen downloaden: Meldingen kunnen afbeeldingen bevatten die via de API kunnen worden gedownload.

 Wij raden aan om de volledige swagger-documentatie door te nemen voor gedetailleerde informatie over de beschikbare functionaliteiten, de structuur van de API-aanroepen en de vereiste parameters.

Als je toegang nodig hebt tot de API, kun je een login verkrijgen via de servicedesk van BinnenBeter. De servicedesk verstrekt inloggegevens en verdere ondersteuning bij het integreren van de API.

Voor verdere vragen of technische ondersteuning, neem contact op met de BinnenBeter servicedesk.

1. Authenticatie

De BinnenBeter API vereist dat gebruikers zich authentiseren via het /v1/login endpoint. Na succesvolle authenticatie ontvang je een JWT-token (JSON Web Token), dat bij vervolgverzoeken moet worden meegestuurd als bewijs van toegang.

1. Verkrijgen van inloggegevens

Gemeenten die toegang willen tot de BinnenBeter API kunnen inloggegevens aanvragen via de servicedesk van BinnenBeter. De servicedesk verstrekt de benodigde gebruikersnaam en wachtwoord.

2. Inloggen via het /v1/login endpoint

Om in te loggen en een JWT-token te verkrijgen, stuur je een POST-verzoek naar het /v1/login endpoint met de volgende gegevens:

Header

Waarde

Authorization

Bearer <jouw-JWT-token>


3. Succesvolle Authenticatie

Als de inloggegevens correct zijn, krijg je een 200 OK-response met een JWT-token.

4. Gebruik van het JWT-token

Bij elk vervolgverzoek naar de API moet je het JWT-token meesturen in de Authorization header:

5. Foutmeldingen bij inloggen

Bij een incorrecte login ontvang je een foutmelding. Hieronder enkele veelvoorkomende foutmeldingen:

HTTP Statuscode

Foutmelding

Oplossing

400 Bad Request

Ongeldig verzoek

Controleer of alle velden correct zijn ingevuld.

401 Unauthorized

Ongeldige gebruikersnaam of wachtwoord

Controleer je inloggegevens en probeer opnieuw.

403 Forbidden

Toegang geweigerd

Zorg ervoor dat je account geautoriseerd is. Neem contact op met de servicedesk.


6. Veiligheidsadvies

  • Bewaar je JWT-token en inloggegevens veilig.
  • Verander je wachtwoord regelmatig.
  • Zorg dat de JWT-token alleen gebruikt wordt door geautoriseerde toepassingen.

 2. Meldingen ophalen

De API biedt twee verschillende endpoints om meldingen op te halen. Elk endpoint heeft een specifiek doel en toepassing:

1. Get all reports

  • Endpoint: /v1/reports
  • HTTP Methode: GET
  • Beschrijving:
    Dit endpoint wordt gebruikt om alle meldingen op te halen, eventueel met filters en paginering. Het is handig wanneer je een overzicht wilt van meerdere meldingen, bijvoorbeeld alle meldingen die in een bepaalde periode zijn ingediend of die een specifieke status hebben.
  • Gebruik:
    • Wanneer je een lijst met meldingen wilt ophalen.
    • Wanneer je meldingen wilt filteren op basis van specifieke criteria
    • Wanneer je gegevens nodig hebt om een dashboard of rapportage te vullen.

2. Get report by ID

  • Endpoint: /v1/reports/{id}
  • HTTP Methode: GET
  • Beschrijving:
    Dit endpoint wordt gebruikt om één specifieke melding op te halen op basis van het unieke ID van die melding. Het is handig wanneer je gedetailleerde informatie over één melding nodig hebt, bijvoorbeeld om de status, locatie of bijgevoegde afbeeldingen te bekijken.
  • Gebruik:
    • Wanneer je de details van een specifieke melding wilt opvragen.
    • Wanneer je een melding wilt openen voor verdere verwerking, zoals het oplossen of wijzigen van de status.

 Samenvatting van het verschil

Kenmerk

Get all reports

Get report by ID

Endpoint

/v1/reports

/v1/reports/{id}

Doel

Lijst met meerdere meldingen ophalen.

Gedetailleerde informatie van één melding ophalen.

Input

Optionele filters (datum, categorie, status).

Melding ID (verplicht).

Output

Pagina met meerdere meldingen.

Eén specifieke melding.

Gebruik

Voor overzicht en rapportage.

Voor gedetailleerde informatie en verwerking.


 2.1 Get all reports

Dit hoofdstuk beschrijft hoe je via de endpoint /v1/reports meldingen kunt ophalen uit BinnenBeter. Je kunt diverse filters toepassen om de zoekresultaten te verfijnen. Standaard worden de resultaten gesorteerd op reportId in aflopende volgorde (nieuwste meldingen eerst).

Beschikbare filters

Onderstaande filters kunnen worden gebruikt om de lijst met meldingen te filteren. Je kunt één of meerdere filters combineren.

Filter

Beschrijving

Type

Voorbeeldwaarde

Page

Het paginanummer van de resultaten (beginnend bij 0).

Integer

page=1

size

Het aantal meldingen per pagina (maximaal 100).

Integer

size=10

fromReportId

Haalt meldingen op met een hoger meldingsnummer dan deze waarde (nieuwere meldingen).

Integer

fromReportId=1000

fromLastModified

Haalt meldingen op die na een specifieke datum en tijd zijn gewijzigd.

DateTime (ISO)

fromLastModified=2024-11-01T00:00:00Z

entryDateStart

Begin van de datumrange voor de datum binnenkomst van meldingen.

DateTime (ISO)

entryDateStart=2024-10-01T00:00:00Z

entryDateEnd

Einde van de datumrange voor de datum binnenkomst van meldingen.

DateTime (ISO)

entryDateEnd=2024-10-31T23:59:59Z

mainCategories

Filteren op de hoofdcategorie van meldingen. Er kunnen meerdere waarden worden opgegeven.

Array (String)

mainCategories=Verkeer

subCategories

Filteren op de subcategorie van meldingen. Er kunnen meerdere waarden worden opgegeven.

Array (String)

subCategories=Kapotte straatverlichting

reportStatuses

Filteren op de hoofdstatus van meldingen (“Nieuw”, “In behandeling” of “Afgehandeld”). Er kunnen meerdere waarden worden opgegeven.

Array (String)

reportStatuses=In behandeling

workflowStatuses

Filteren op de workflow status van meldingen. Er kunnen meerdere waarden worden opgegeven.

Array (String)

workflowStatuses= Ingepland

residences

Filteren op de woonplaats van meldingen. Er kunnen meerdere waarden worden opgegeven.

Array (String)

residences=Eindhoven &residences=Helmond

hasSpatialObject

Alleen meldingen ophalen die een object gekoppeld hebben.

Boolean

hasSpatialObject=true

timezone

Tijdzone waarin datumvelden worden teruggegeven

Enum (UTC, NL)

timezone=UTC

 


2.2 Get report by ID

Dit hoofdstuk beschrijft hoe je via de endpoint /v1/reports/{id} informatie van één melding kunt ophalen uit BinnenBeter. Het endpoint biedt gedetailleerde informatie over een specifieke melding op basis van het unieke ID. Dit is nuttig wanneer je bijvoorbeeld de status, locatie, of andere relevante details van een melding wilt bekijken.

Parameters

Parameter

Type

Verplicht

 

Beschrijving

id

Integer

Ja

 

Het unieke ID van de melding die je wilt opvragen.


Respons

De respons bevat alle beschikbare details van de melding, zoals omschrijving, locatie, status, en eventuele bijgevoegde afbeeldingen.

Mogelijke HTTP-statuscodes

Statuscode

Betekenis

Omschrijving

200 OK

Succesvol

De melding is gevonden en geretourneerd.

404 Not Found

Niet gevonden

Er is geen melding gevonden met het opgegeven ID.

401 Unauthorized

Niet geautoriseerd

Geen geldige authenticatie token verstrekt.

403 Forbidden

Toegang geweigerd

De gebruiker heeft geen rechten om deze melding te bekijken.


2.3 Overzicht van melding velden

Veldnaam

Type

Beschrijving

reportId

Integer

Meldingsnummer.

parentReportId

Integer

Dit veld wordt alleen ingevuld wanneer de melding gekoppeld is aan een hoofdmelding. Het bevat het meldingsnummer van de hoofdmelding, wat aangeeft dat deze melding een schaduwmelding is.

childReportIds

Array

Dit veld wordt alleen ingevuld als de melding een hoofdmelding is met gekoppelde schaduwmeldingen. Het bevat een lijst met de meldingsnummers van deze schaduwmeldingen.

description

String

Omschrijving van de melding.

solveDescription

String

Omschrijving afhandeling van de melding.

status

String

Hoofdstatus van de melding (nieuw, in behandeling of afgehandeld).

workflowStatus

String

Workflow status van de melding

mainCategory

String

Hoofdcategorie van de melding.

subCategory

String

Subcategorie van de melding.

tender

String

Bestek dat aan de melding is gekoppeld.

residence

String

Woonplaats van de melding.

area

String

Wijk van de melding.

neighbourhood

String

Buurt van de melding.

street

String

Straat van de melding.

locationDescription

String

Gedetailleerde beschrijving van de locatie.

longitude

Number

Lengtegraad (coördinaat) van de locatie.

latitude

Number

Breedtegraad (coördinaat) van de locatie.

entry

DateTime

Datum en tijd waarop de melding is aangemaakt.

solveBefore

DateTime

Uiterlijke datum waarop het melding opgelost moet zijn.

finishedOn

DateTime

Datum en tijd waarop het melding is afgehandeld.

plannedOn

DateTime

Geplande datum en tijd voor het oplossen van de melding.

highPriority

Boolean

Geeft aan of de melding een hoge prioriteit heeft.

assignmentDescription

String

Opdracht omschrijving van de melding.

contractorAssignedOn

DateTime

Datum en tijd waarop de aannemer is toegewezen.

workStartBefore

DateTime

Datum en tijd waarop de aannemer het werk uiterlijk moet starten.

workStartedOn

DateTime

Datum en tijd waarop de aannemer het werk is begonnen.

workFinishedOn

DateTime

Datum en tijd waarop de aannemer het werk heeft voltooid.

Source

String

Meldwijze van de melding

cause

String

Oorzaak van de melding.

contractor

String

Naam van de aannemer van de melding.

caretaker

String

Naam van de behandelaar van de melding

coordinator

String

Naam van de coördinator van de melding.

inspector

String

Naam van de inspecteur van de melding

reportImages

Array

Lijst met meldingsafbeeldingen

solvedImages

Array

Lijst met afbeeldingen van de opgeloste situatie

reportFiles

Array

Lijst met andere bijlagen van de melding

workAreas

Array

Lijst met werkgebieden waar de melding binnen valt.

departments

Array

Afdeling(en) die aan de melding zijn toegewezen

spatialObject

Object

Lijst met informatie over het aan de melding gekoppelde object

customFields

Array

Lijst van custom velden van de melding

modified

DateTime

Datum en tijd waarop de melding voor het laatst is aangepast.

2.4 Tijden ophalen in gewenste tijdzone

Voor de meeste endpoints met datum- en tijdvelden kun je aangeven of je deze in UTC-tijd of in Nederlandse tijd (NL) terug wilt ontvangen. Dit stel je in via de timezone queryparameter.

Beschikbare opties:

Waarde

Uitleg

NL (standaard)

Datum/tijd wordt weergegeven in Nederlandse tijd

UTC

Datum/tijd wordt weergegeven in UTC-tijd (bijv. voor systemen die internationaal werken)

Toepasbaar op:

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

 

3. Assets  downloaden

Het ReportAsset-endpoint stelt je in staat om afbeeldingen of andere bijlagen op te halen die gekoppeld zijn aan een specifieke melding via het GET /v1/assets/{id} endpoint. Zorg ervoor dat je de juiste assetId gebruikt die gekoppeld is aan de melding. Dit assetId kun je ophalen via het Get report by ID-endpoint, waarin de lijst met beschikbare assets voor de melding wordt weergegeven.

Parameters

Parameter

Type

Verplicht

Beschrijving

id

Integer

Ja

Het unieke ID van de asset die je wilt downloaden. Dit ID kun je vinden in de meldingdetails onder het veld reportImages, solvedImages en/of reportFiles.


Respons

De respons bevat de assetdata in een van de ondersteunde formaten zoals PDF, DOCX, JPEG, PNG of GIF.

Mogelijke HTTP-statuscodes

Statuscode

Betekenis

Omschrijving

200 OK

Succesvol

De asset is gevonden en succesvol gedownload.

404 Not Found

Niet gevonden

Er is geen asset gevonden met het opgegeven ID.

401 Unauthorized

Niet geautoriseerd

Geen geldige authenticatie token verstrekt.

403 Forbidden

Toegang geweigerd

De gebruiker heeft geen rechten om de asset te downloaden.


4. Masterdata: categorieën ophalen

Met de onderstaande endpoints kun je de actuele hoofdcategorieën en subcategorieën van meldingen ophalen. Dit is handig als je dynamisch filters wilt aanbieden of validatie inbouwt in je applicatie.

  • GET /v1/masterdata/category/main haalt alle hoofdcategorieën op.
  • GET /v1/masterdata/category/sub haalt alle subcategorieën op, inclusief verwijzing naar de hoofdcategorie.
  • GET /v1/masterdata/category/main/{mainCategoryName}/sub haalt de subcategorieën op voor één specifieke hoofdcategorie.