Beschikbaar — REST API v1

REST API v1

Programmatische toegang tot Boekbaar-data voor automatisering, rapportages en integraties met Make, Zapier, n8n, Google Sheets of eigen software.

API-sleutels beheren Integrations Hub

1. Overzicht

De Boekbaar REST API v1 is een JSON API met Bearer-authenticatie. Elke API-sleutel hoort bij één organisatie — tenant-isolatie is ingebouwd. Gebruik webhooks voor push-events en de REST API voor opvragen en wijzigingen.

2. Base URL

https://app.boekbaar.nu/api/v1

Alle endpoints hieronder zijn relatief aan deze base URL.

3. Authenticatie

Authorization: Bearer bk_live_xxxxx

Belangrijk

API-sleutels worden slechts één keer getoond bij aanmaken.
Bewaar sleutels veilig in een secrets manager.
Gebruik API-sleutels nooit in frontend-code of publieke repositories.

4. API-sleutel aanmaken

Dashboard → Ontwikkelaars → API-sleutels
Klik op Nieuwe API-sleutel
Kies scopes en optionele vervaldatum
Kopieer de sleutel direct — daarna niet meer zichtbaar

Directe link: /dashboard/developers/api-keys

5. Scopes

Elke API-sleutel heeft een set scopes. Ontbrekende scope geeft HTTP 403 met code missing_scope.

Scope	Gebruikt door	Toegang	Voorbeeld
organization:read	Rapportages, sync	Organisatie en vestigingen lezen	GET /organization
organization:write	Setup-automatisering	Organisatievelden bijwerken	PATCH /organization
customers:read	CRM, Sheets	Klanten ophalen	GET /customers
customers:write	CRM-import	Klanten aanmaken/bijwerken	POST /customers
appointments:read	Agenda-sync	Afspraken ophalen	GET /appointments
appointments:write	Status-updates	Afspraken wijzigen (geen POST)	PATCH /appointments/{id}
services:read	Catalogus-sync	Diensten lezen	GET /services
services:write	Prijzenbeheer	Diensten aanmaken/bijwerken	POST /services
staff:read	Planning	Medewerkers lezen	GET /staff
staff:write	HR-sync	Medewerkers beheren	POST /staff
packages:read	Credits	Pakketten lezen	GET /packages
packages:write	Credits (dashboard)	Pakketten toewijzen	Dashboard
benefits:read	Loyalty	Voordelen lezen	GET /benefits
benefits:write	Loyalty (dashboard)	Voordelen beheren	Dashboard
reviews:read	Reputatie	Reviews lezen	GET /reviews
reviews:write	Review-workflows	Reviews bijwerken	PATCH /reviews/{id}
trust:read	Trust-profiel	Trust-data lezen	GET /trust-profile
trust:write	Trust-workflows	Trust-profiel bijwerken	PATCH /trust-profile
widgets:read	Marketing	Widgets en events lezen	GET /widgets/events
analytics:read	BI, dashboards	Statistieken ophalen	GET /analytics
subscription:read	Billing-sync	Abonnement lezen	GET /subscription
webhooks:manage	Dashboard	Webhooks configureren	Dashboard
api_keys:manage	Dashboard	API-sleutels beheren	Dashboard

6. Endpoints

Methode	Pad	Scope	Beschrijving
GET	/organization	organization:read	Organisatiegegevens ophalen
PATCH	/organization	organization:write	Veilige organisatievelden bijwerken
GET	/customers	customers:read	Klantenlijst (cursor-paginering)
POST	/customers	customers:write	Nieuwe klant aanmaken
GET	/customers/{id}	customers:read	Klantdetails ophalen
PATCH	/customers/{id}	customers:write	Klant bijwerken
GET	/appointments	appointments:read	Afspraken filteren en ophalen
GET	/appointments/{id}	appointments:read	Afspraakdetails ophalen
PATCH	/appointments/{id}	appointments:write	Afspraakstatus of velden wijzigen
GET	/services	services:read	Diensten ophalen
POST	/services	services:write	Dienst aanmaken
GET	/services/{id}	services:read	Dienst ophalen
PATCH	/services/{id}	services:write	Dienst bijwerken
GET	/staff	staff:read	Medewerkers ophalen
POST	/staff	staff:write	Medewerker aanmaken
GET	/staff/{id}	staff:read	Medewerker ophalen
PATCH	/staff/{id}	staff:write	Medewerker bijwerken
GET	/packages	packages:read	Pakketten ophalen
GET	/benefits	benefits:read	Klantvoordelen ophalen
GET	/reviews	reviews:read	Reviews ophalen
PATCH	/reviews/{id}	reviews:write	Review publiceren, verbergen of beantwoorden
GET	/trust-profile	trust:read	Trust-profiel ophalen
PATCH	/trust-profile	trust:write	Trust-profiel bijwerken
GET	/widgets	widgets:read	Widget-configuratie ophalen
GET	/widgets/events	widgets:read	Widget-events ophalen
GET	/analytics	analytics:read	Geaggregeerde statistieken
GET	/analytics/advanced	analytics:read	Analytics+ statistieken
GET	/subscription	subscription:read	Abonnementsstatus (alleen-lezen)
GET	/locations	organization:read	Vestigingen ophalen
GET	/locations/{id}	organization:read	Vestiging ophalen
GET	/openapi.json	—	OpenAPI 3-specificatie (publiek)

Nieuwe afspraken aanmaken via API is bewust beperkt; gebruik de publieke boekingsflow om conflictcontrole en beschikbaarheid te behouden. Er is geen POST /appointments.

7. Paginering

Lijst-endpoints gebruiken cursor-paginering:

limit — standaard 50, maximum 100
cursor — ID van laatst geziene item
Response bevat pagination.nextCursor voor de volgende pagina

Voorbeeld

GET https://app.boekbaar.nu/api/v1/customers?limit=50&cursor=clx123

8. Filtering

Veel lijst-endpoints ondersteunen query-parameters. Voorbeelden:

GET /appointments?status=CONFIRMED&from=2026-06-01
GET /appointments?customerId=…&staffId=…
GET /analytics?preset=last30

Zie OpenAPI voor het volledige filteroverzicht per resource.

9. Idempotency

Stuur header Idempotency-Key mee bij POST, PATCH en DELETE:

Header

Idempotency-Key: unique-key-123

Zelfde key + zelfde body → zelfde response (24 uur geldig)
Zelfde key + andere body → HTTP 409 idempotency_conflict

10. Rate limits

Per API-sleutel: 120 verzoeken per minuut en 10.000 per dag. Bij overschrijding: HTTP 429 met code rate_limited.

11. Foutcodes

HTTP	Code	Betekenis	Actie
401	invalid_api_key	Ongeldige of ingetrokken sleutel	Controleer Authorization header; maak een nieuwe sleutel aan indien nodig.
403	missing_scope	Scope ontbreekt op API-sleutel	Voeg de vereiste scope toe in API-sleutels.
403	feature_not_available	API add-on niet actief	Activeer de Developer/API add-on voor je organisatie.
404	not_found	Resource bestaat niet	Controleer ID en tenant-isolatie (org komt uit sleutel).
400	validation_error	Ongeldige invoer	Lees error.details en corrigeer het request body.
409	idempotency_conflict	Zelfde Idempotency-Key, andere body	Gebruik een nieuwe key of dezelfde body.
429	rate_limited	Rate limit bereikt	Wacht en retry met backoff; respecteer 120/min en 10.000/dag.
500	internal_error	Serverfout	Retry later; neem contact op bij herhaald falen.
405	method_not_allowed	HTTP-methode niet ondersteund	Controleer endpoint en methode in deze documentatie.

12. OpenAPI

OpenAPI 3 JSON-specificatie:

/api/v1/openapi.json

Open OpenAPI Webhook-documentatie

Importeer /api/v1/openapi.json in Postman, Insomnia, Make (HTTP-module) of n8n (OpenAPI-import) voor request-voorbeelden.

13. cURL-voorbeelden

Organisatie ophalen

curl -H "Authorization: Bearer bk_live_xxxxx" \
  https://app.boekbaar.nu/api/v1/organization

Klantenlijst

curl -H "Authorization: Bearer bk_live_xxxxx" \
  "https://app.boekbaar.nu/api/v1/customers?limit=50"

Klant aanmaken

curl -X POST -H "Authorization: Bearer bk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-customer-001" \
  -d '{"name":"Voorbeeld Klant","email":"klant@voorbeeld.nl"}' \
  https://app.boekbaar.nu/api/v1/customers

Afspraken ophalen (filter)

curl -H "Authorization: Bearer bk_live_xxxxx" \
  "https://app.boekbaar.nu/api/v1/appointments?status=CONFIRMED&limit=25"

Afspraakstatus wijzigen

curl -X PATCH -H "Authorization: Bearer bk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status":"COMPLETED"}' \
  https://app.boekbaar.nu/api/v1/appointments/clx123example

Dienst aanmaken

curl -X POST -H "Authorization: Bearer bk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Intake","durationMinutes":60,"priceCents":7500}' \
  https://app.boekbaar.nu/api/v1/services

Vestigingen ophalen

curl -H "Authorization: Bearer bk_live_xxxxx" \
  https://app.boekbaar.nu/api/v1/locations

Analytics ophalen

curl -H "Authorization: Bearer bk_live_xxxxx" \
  "https://app.boekbaar.nu/api/v1/analytics?preset=last30"

14. JSON-voorbeelden

Organisatie (200)

{
  "data": {
    "id": "org_example",
    "name": "Voorbeeld Salon",
    "slug": "voorbeeld-salon",
    "timezone": "Europe/Amsterdam",
    "country": "NL"
  }
}

Klant (200)

{
  "data": {
    "id": "cus_example",
    "name": "Voorbeeld Klant",
    "email": "klant@voorbeeld.nl",
    "phone": null,
    "createdAt": "2026-06-01T10:00:00.000Z"
  }
}

Afspraak (200)

{
  "data": {
    "id": "apt_example",
    "status": "CONFIRMED",
    "startsAt": "2026-06-15T09:00:00.000Z",
    "endsAt": "2026-06-15T10:00:00.000Z",
    "customerId": "cus_example",
    "serviceId": "svc_example",
    "staffId": "stf_example"
  }
}

Paginering (200)

{
  "data": [
    { "id": "cus_001", "name": "Klant A" },
    { "id": "cus_002", "name": "Klant B" }
  ],
  "pagination": {
    "limit": 50,
    "cursor": null,
    "nextCursor": "cus_002"
  }
}

Fout (403 missing_scope)

{
  "error": {
    "code": "missing_scope",
    "message": "Missing required scope: customers:write."
  }
}

15. Automatisering

Make: Webhook → Boekbaar API → boekhoudpakket

Maak een webhook-endpoint in Make als trigger.
Configureer een Boekbaar webhook voor appointment.completed.
Voeg een HTTP-module toe met GET /customers/{id} of GET /appointments.
Map velden naar je boekhoud- of CRM-module (HTTP Request).

Er is nog geen officiële Make-app. Gebruik Webhooks + HTTP Request modules.

Zapier: Webhook → Boekbaar API → Google Sheets

Gebruik Webhooks by Zapier als trigger (Catch Hook).
Stel Boekbaar in op customer.created of appointment.created.
Voeg een Webhooks POST/GET stap toe naar de Boekbaar API.
Schrijf rijen naar Google Sheets met Zapier Formatter.

Er is nog geen officiële Zapier-app. Gebruik Webhooks + Webhooks by Zapier.

n8n: Boekbaar webhook → HTTP Request → accounting

Start met een Webhook-node (POST) of poll Boekbaar via Schedule + HTTP Request.
Verifieer X-Boekbaar-Signature in een Function-node.
Haal extra data op via HTTP Request naar /api/v1/appointments/{id}.
Stuur naar je boekhoudpakket via HTTP Request of e-mail.

Er is nog geen officiële n8n-node. Gebruik HTTP Request + Webhook nodes.

16. Huidige beperkingen

Nieuwe afspraken aanmaken via API is bewust beperkt; gebruik de publieke boekingsflow om conflictcontrole en beschikbaarheid te behouden.
POST /appointments bestaat niet in API v1 — alleen GET en PATCH op bestaande afspraken.
Tenant-isolatie: organizationId komt altijd uit de API-sleutel, nooit uit query of body.
Geen officiële SDK's — gebruik REST, OpenAPI en standaard HTTP-clients.
packages:write en benefits:write zijn primair dashboard-scopes; controleer scopes per endpoint.

17. Versioning

Huidige versie: v1 onder /api/v1. Breaking changes krijgen een nieuw major pad; v1 blijft ondersteund zolang gedocumenteerd.

18. Beveiliging

API-sleutels worden één keer getoond bij aanmaken. Sla ze veilig op in een secrets manager.
Gebruik API-sleutels nooit in frontend-code, mobiele apps of publieke repositories.
Beperk scopes tot het minimum dat je automatisering nodig heeft.
Trek sleutels in zodra een integratie wordt stopgezet.
Gebruik HTTPS voor alle verzoeken; de base URL is altijd https://app.boekbaar.nu/api/v1.

← Alle integraties