Ontwikkelaarsportaal — API

Koppel externe systemen aan het ZwemExpert / ExpertSwimCamp-platform via onze REST API: kampen, inschrijvingen, betalingen, klanten en meer — plus uitgaande webhooks voor realtime updates.

Basis-URL

https://zwemexpert-website.mike-6ba.workers.dev/api/public/v1

Authenticatie

Elke aanvraag vereist een API-sleutel via de Authorization: Bearer …-header (of X-API-Key). Sleutels worden door een beheerder aangemaakt en zijn per merk en per scope beperkt.

curl -H "Authorization: Bearer ze_live_…" \
  "https://zwemexpert-website.mike-6ba.workers.dev/api/public/v1/camps?limit=10&locale=nl"

Conventies

Antwoorden zijn JSON; lijsten hebben de vorm { object:"list", data:[…], pagination:{…} }.
Paginatie: cursor (starting_after, limit) of offset (page, per_page).
Taal via ?locale=nl|en; vertaalbare velden volgen de taal.
Filteren/sorteren/uitbreiden: ?status=…, ?sort=startdatum:asc, ?expand=coaches, ?fields=id,naam.
Rate limit per sleutel; zie X-RateLimit-*.

Scopes

`camps:read`	Kampen en beschikbaarheid lezen
`coaches:read`	Coaches lezen
`registrations:read`	Inschrijvingen lezen
`registrations:write`	Inschrijvingen aanmaken/wijzigen
`participants:read`	Deelnemers (kinderen) lezen
`customers:read`	Klanten (ouders) lezen
`payments:read`	Betalingen lezen
`waitlist:read`	Wachtlijst lezen
`waitlist:write`	Wachtlijst-aanmeldingen toevoegen
`stats:read`	Kerncijfers lezen
`webhooks:manage`	Webhooks beheren

Fouten

Fouten hebben een stabiele error.code en een gelokaliseerde error.message.

`authentication_error`	401	Ongeldige/ontbrekende sleutel
`permission_error`	403	Scope of merk niet toegestaan
`invalid_request_error`	400/422	Ongeldige invoer
`not_found`	404	Resource bestaat niet
`rate_limit_error`	429	Te veel verzoeken
`idempotency_error`	409	Idempotency-conflict
`api_error`	500	Interne fout

Webhooks

Abonneer je op events; wij leveren een POST met een HMAC-SHA256-handtekening (header X-ZE-Signature: t=…,v1=…, ondertekend over `${t}.${body}` met het webhook-secret).

Beschikbare events: registration.created, registration.updated, registration.status_changed, registration.cancelled, payment.paid, payment.failed, payment.refunded, camp.published, camp.updated, camp.full, waitlist.created.

POST https://jouw-systeem.nl/webhook
X-ZE-Event: registration.created
X-ZE-Signature: t=1736531200,v1=

{ "id": "evt_…", "type": "registration.created",
  "created": "2026-07-11T12:00:00Z", "brand": "zwemexpert",
  "data": { "object": { "object": "registration", "id": 123, … } } }

Endpoint-overzicht

Volledige machine-leesbare spec: openapi.json (importeerbaar in Postman, Insomnia of Redoc).

Endpoints laden…