Parking Manager API — Documentatie

Overzicht

Met de Parking Manager API kan een extern systeem de dagelijkse toegangstaken uitvoeren die uw team nu handmatig doet — meestal het tijdelijk toevoegen van een kenteken voor een bezoeker.

De aanbevolen manier om tijdelijke toegang te verlenen is een bezoekersboeking: een kenteken dat alleen geldig is tussen een start- en eindtijd en daarna automatisch vervalt. U kunt ook een kenteken permanent toevoegen, de live bezetting uitlezen en beschikbare tijdvakken controleren vóór het boeken.

Base URL

Alle onderstaande paden zijn relatief aan uw instance, bijv. https://uw-instance.revtek.nl/chatbot/api/v1. De exacte hostnaam voor uw locatie ontvangt u samen met uw API-key.

Conventies

Alle requests en responses gebruiken application/json.
Elke response bevat een "status"-veld: "success", "partial" of "error".
Kentekens worden automatisch genormaliseerd naar hoofdletters en getrimd.
Elke geauthenticeerde request moet een tenant benoemen — zie Tenants & scope.

Authenticatie

Elk endpoint vereist een API-key, behalve de publieke endpoints /health en /webhooks/event-types.

Geef uw key mee in een van beide headers bij elke request:

Request headers

X-API-Key: uw_api_key_hier
# — of —
Authorization: Bearer uw_api_key_hier

Omgaan met keys

Keys worden gehasht opgeslagen en kunnen een vervaldatum krijgen. Behandel uw key als een wachtwoord — verstuur hem alleen over HTTPS en zet hem nooit in client-side code. Neem contact met ons op om een key te roteren of in te trekken.

Voorbeeld — een volledige request met curl

curl https://uw-instance.revtek.nl/chatbot/api/v1/occupancy?tenant_name=Silverflow \
  -H "X-API-Key: uw_api_key_hier"

Tenants & scope

Een tenant is uw organisatie op een gedeelde parkeerlocatie. Elke request handelt namens één tenant, en uw key raakt alleen uw eigen tenant.

Neem tenant_name op in de request body (bij POST/PUT) of als query-parameter (bij GET/DELETE). Naamherkenning is soepel — exact, hoofdletterongevoelig, dan gedeeltelijk — zodat kleine variaties toch matchen. Uw key is gebonden aan uw tenant en kan geen data van andere bedrijven op dezelfde locatie lezen of wijzigen.

Let op

Omdat uw key tenant-gebonden is, geeft u tenant_name nog steeds mee voor de duidelijkheid, maar u kunt alleen op uw eigen tenant handelen.

Datum & tijd

Alle tijdstippen zijn ISO 8601-strings.

Stuur tijden in UTC met een afsluitende Z — bijv. 2026-07-10T14:00:00Z — of met een expliciete offset.
Een tijdstip zonder tijdzone wordt geïnterpreteerd als Midden-Europese tijd (Amsterdam).
Alle tijdstippen in responses worden teruggegeven in UTC.

Fouten

Fouten geven een non-2xx statuscode terug en een JSON-body met een leesbare melding.

Code	Betekenis	Typische oorzaak
200 / 201	Succes	Request voltooid.
400	Bad request	Ontbrekend of ongeldig veld (bijv. geen `plate_number`).
401	Unauthorized	Ontbrekende, ongeldige of verlopen API-key.
403	Forbidden	Bezoekersparkeren niet ingeschakeld, of kenteken hoort bij een andere tenant.
404	Not found	Tenant of resource bestaat niet.
409	Conflict	Kenteken bestaat al, of geen bezoekersplekken vrij.
500	Server error	Onverwachte fout aan onze kant.

Foutbody

{
  "status": "error",
  "message": "plate_number is required"
}

Bezoekersboekingen

De belangrijkste manier om tijdelijke toegang te verlenen. Een boeking maakt een kenteken alleen geldig tussen start_time en end_time, en telt mee voor uw bezoekerscapaciteit.

post /visitors API-key

Maak een bezoekersboeking aan. Optioneel herhalend — zie Herhaling.

Veld	Type		Beschrijving
tenant_name	string	verplicht	Uw tenant.
visitor_name	string	verplicht	Naam van de bezoeker.
start_time	ISO 8601	verplicht	Wanneer toegang begint.
end_time	ISO 8601	optioneel	Wanneer toegang eindigt. Standaard `start_time` + 1 uur.
plate_number	string	optioneel	Kenteken van de bezoeker. Weggelaten? Dan wordt de plek gereserveerd en kan het kenteken later worden ingevuld.
recurrence_rule	string	optioneel	`weekly`, `biweekly` of `monthly`. Weglaten voor eenmalig.
recurrence_weekdays	int[]	optioneel	Ma=0 … Zo=6. Alleen weekly/biweekly; elke dag wordt een eigen reeks.
recurrence_end_date	ISO 8601	optioneel	Stop met herhalen na deze datum.

Request

POST /chatbot/api/v1/visitors
{
  "tenant_name": "Silverflow",
  "visitor_name": "Jan Jansen",
  "plate_number": "12ABC3",
  "start_time": "2026-07-10T09:00:00Z",
  "end_time": "2026-07-10T17:00:00Z"
}

Response · 201

{
  "status": "success",
  "message": "Visitor booking created",
  "booking": {
    "id": 142,
    "plate_number": "12ABC3",
    "visitor_name": "Jan Jansen",
    "start_time": "2026-07-10T09:00:00+00:00",
    "end_time": "2026-07-10T17:00:00+00:00",
    "status": "active"
  }
}

Als de locatie vol is

Zijn er geen bezoekersplekken vrij voor dat tijdvak, dan is de response 409 met een alternative_slots-array die tot drie nabijgelegen vrije tijdvakken voorstelt. Bij een meerdaagse herhalende request komen dagen die niet passen in een skipped-array, terwijl de rest wel wordt aangemaakt ("status": "partial").

get /visitors API-key

Haal bezoekersboekingen voor uw tenant op.

Query-param	Type	Beschrijving
tenant_name	string	Uw tenant. verplicht
status	string	Filter: `active`, `arrived`, `completed`, `cancelled`.
from_date	ISO 8601	Begin van het venster. Standaard: nu.
to_date	ISO 8601	Einde van het venster. Standaard: over 7 dagen.
recurring_only	bool	`true` — alleen hoofdboekingen van herhalingen.
include_occurrences	bool	`true` — inclusief automatisch gegenereerde kopieën van herhalende boekingen.

Response · 200

{
  "status": "success",
  "count": 1,
  "bookings": [{
    "id": 142,
    "plate_number": "12ABC3",
    "visitor_name": "Jan Jansen",
    "start_time": "2026-07-10T09:00:00+00:00",
    "end_time": "2026-07-10T17:00:00+00:00",
    "status": "active",
    "recurrence_rule": null,
    "is_recurring_copy": false
  }]
}

put /visitors/{id} API-key

Wijzig een boeking. Alle body-velden zijn optioneel; stuur alleen wat u wilt veranderen.

Veld	Type	Beschrijving
plate_number	string	Nieuw kenteken voor de bezoeker.
visitor_name	string	Nieuwe naam van de bezoeker.
start_time	ISO 8601	Nieuwe starttijd.
end_time	ISO 8601	Nieuwe eindtijd.
recurrence_end_date	ISO 8601	Wijzig wanneer een herhalende reeks stopt (alleen hoofdboeking).

Request

PUT /chatbot/api/v1/visitors/142
{
  "tenant_name": "Silverflow",
  "plate_number": "99XYZ9"
}

delete /visitors/{id} API-key

Annuleer een boeking.

Query-param	Type	Beschrijving
tenant_name	string	Uw tenant. verplicht
cancel_series	bool	`true` — annuleer alle toekomstige herhalingen in een reeks, of u nu de hoofdboeking of een kopie meegeeft. Verleden herhalingen blijven ongemoeid.

Request

DELETE /chatbot/api/v1/visitors/142?tenant_name=Silverflow

post /visitors/create-with-invitation API-key

Maak een boeking aan én ontvang een zelfregistratielink. Stuur de link naar de bezoeker; die opent hem om zijn eigen kenteken te registreren. De uitnodiging vervalt op end_time. Accepteert dezelfde velden als POST /visitors (inclusief herhaling — één link per weekdagreeks).

Response · 201 (vorm)

{
  "status": "success",
  "booking": { "id": 143, /* … */ },
  "invitation_url": "https://uw-instance.revtek.nl/invite/<token>"
}

Herhaling

Boekingen kunnen zich herhalen. Voeg de herhalingsvelden toe aan POST /visitors en het systeem maakt toekomstige herhalingen automatisch aan.

weekly — elke 7 dagen.
biweekly — elke 14 dagen.
monthly — dezelfde datum elke maand.

Bij weekly/biweekly wordt elke weekdag in recurrence_weekdays een eigen onafhankelijke reeks. Nieuwe herhalingen worden automatisch gegenereerd zodra eerdere hun einde naderen, tot aan recurrence_end_date (of onbeperkt als die ontbreekt). Gebruik GET /visitors?recurring_only=true om de hoofdboekingen te zien en include_occurrences=true voor de gegenereerde kopieën.

Request — weekdagen ma/wo/vr, tot maart

POST /chatbot/api/v1/visitors
{
  "tenant_name": "Silverflow",
  "visitor_name": "Contractor",
  "start_time": "2026-07-13T08:00:00Z",
  "end_time": "2026-07-13T18:00:00Z",
  "recurrence_rule": "weekly",
  "recurrence_weekdays": [0, 2, 4],
  "recurrence_end_date": "2026-03-01T00:00:00Z"
}

Kentekens

Voor kentekens met permanente toegang in plaats van een tijdgebonden boeking. Voor tijdelijke bezoekerstoegang gebruikt u liever bezoekersboekingen.

post /plates API-key

Voeg een permanent kenteken toe aan uw tenant.

Veld	Type		Beschrijving
tenant_name	string	verplicht	Uw tenant.
plate_number	string	verplicht	Het toe te voegen kenteken.
person_name	string	optioneel	Van wie het kenteken is.

Request

POST /chatbot/api/v1/plates
{
  "tenant_name": "Silverflow",
  "plate_number": "12ABC3",
  "person_name": "Rogier de Vries"
}

Response · 201

{
  "status": "success",
  "message": "License plate added",
  "plate": { "id": 57, "plate_number": "12ABC3", "tenant_name": "Silverflow" }
}

Dubbele kentekens

Bestaat het kenteken al ergens in het systeem, dan is de response 409.

get /plates API-key

Haal alle kentekens voor uw tenant op. Query-param: tenant_name.

Response · 200

{
  "status": "success",
  "count": 1,
  "plates": [{
    "id": 57,
    "plate_number": "12ABC3",
    "person_name": "Rogier de Vries",
    "is_vip": false,
    "expiry_date": null
  }]
}

put /plates/{id} API-key

Wijzig het kenteken of de naam. Body accepteert plate_number en/of person_name, plus tenant_name.

PUT /chatbot/api/v1/plates/57
{ "tenant_name": "Silverflow", "person_name": "R. de Vries" }

delete /plates/{id} API-key

Verwijder een kenteken permanent uit uw tenant. Query-param: tenant_name.

DELETE /chatbot/api/v1/plates/57?tenant_name=Silverflow

Beschikbaarheid & bezetting

Alleen-lezen endpoints om de capaciteit te controleren vóór u boekt.

get /occupancy API-key

Live bezetting voor uw tenant — reguliere, VIP- en bezoekersplekken met huidige aantallen en limieten. Query-param: tenant_name.

Response · 200

{
  "status": "success",
  "tenant": "Silverflow",
  "occupancy": [{
    "parking_object": "Willem Fenengastraat",
    "visitor_occupancy": 2,
    "visitor_limit": 5,
    "available_visitor_slots": 3
  }],
  "summary": { "total_occupancy": 2, "available_slots": 3 }
}

get /timeslots API-key

Beschikbare bezoekerstijdvakken voor een dag (per uur, 08:00–20:00).

Query-param	Type	Beschrijving
tenant_name	string	Uw tenant. verplicht
date	ISO-datum	Dag om te controleren. Standaard: vandaag.
duration_hours	int	Lengte van elk tijdvak. Standaard: 4.

Response · 200

{
  "status": "success",
  "date": "2026-07-10",
  "duration_hours": 4,
  "available_timeslots": [{
    "start_time": "2026-07-10T08:00:00+00:00",
    "end_time": "2026-07-10T12:00:00+00:00",
    "available_slots": 3, "total_slots": 5
  }]
}

get /tenants API-key

Toon de tenants waarop uw API-key mag handelen. Bij een tenant-gebonden key is dat alleen uw eigen tenant — handig om de exacte naam voor andere calls te bevestigen.

Webhooks

Optioneel. Registreer een URL, dan sturen wij een POST zodra er parkeergebeurtenissen plaatsvinden — zo reageren uw systemen realtime in plaats van te pollen.

post /webhooks API-key

Registreer een webhook.

Veld	Type		Beschrijving
name	string	verplicht	Een label voor deze webhook.
url	string	verplicht	Waarheen wij de gebeurtenis POST'en.
event_type	string	verplicht	Een van de onderstaande event-types.
secret	string	optioneel	HMAC-SHA256 signing secret; payloads worden ondertekend als deze is ingesteld.
tenant_name	string	optioneel	Alleen vuren voor deze tenant.

Event-types

visitor.arrivedHet kenteken van een geboekte bezoeker rijdt binnen.

visitor.departedEen bezoekerssessie eindigt.

plate.entryEen willekeurig kenteken rijdt binnen.

plate.exitEen willekeurig kenteken rijdt uit.

Overige webhook-endpoints: GET /webhooks (toon die van u), DELETE /webhooks/{id} (verwijder er één) en GET /webhooks/event-types (toon geldige types — geen auth nodig).

get /health Geen auth

Publieke health check. Handig voor uptime-monitoring.

{ "status": "ok", "service": "Parking Manager Chatbot API", "version": "1.0.0" }