API voor afspraken

Met deze API kunnen externe informatiesystemen en AI-agents namens klanten afspraken inplannen bij Ceder Verwarming. Alle verzoeken via HTTPS.

Authenticatie

Elk verzoek heeft een API-sleutel nodig in de HTTP-header:

X-Api-Key: <uw-sleutel>

Heeft u nog geen sleutel? Vraag er hieronder een aan. Vul uw bedrijfsnaam, contactgegevens en een korte omschrijving van het gebruik in. Na goedkeuring door Ceder Verwarming ontvangt u de sleutel per e-mail. Deel uw sleutel niet publiek.

Bedrijfsnaam* Contactpersoon* E-mailadres* Telefoonnummer Adres Postcode Plaats

Waarvoor gaat u de API gebruiken?*

Sleutel aanvragen

Basis-URL

https://cederverwarming.nl/wp-json/ceder/v1

Tijdblokken

De aankomsttijd is een venster van 2 uur. Afspraken kunnen op alle dagen. Let op: het avondblok (18:00-20:00) en het hele weekend (za + zo) zijn uitsluitend beschikbaar voor service: "storing" (storing verhelpen).

block	aankomst tussen	alleen storing
0800-1000	08:00 - 10:00	nee
0900-1100	09:00 - 11:00	nee
1000-1200	10:00 - 12:00	nee
1230-1430	12:30 - 14:30	nee
1330-1530	13:30 - 15:30	nee
1430-1630	14:30 - 16:30	nee
1800-2000	18:00 - 20:00	ja (avond)

Avond-, weekend- en spoedtarief

Voor avond-, weekend- en spoedafspraken geldt een tarief (informatief; de API rekent geen bedragen). Tarieven stapelen niet, het hoogste percentage geldt:

moment	tarief
spoed (op de dag zelf geboekt)	150%
doordeweekse avond (18:00-20:00)	150%
zaterdag	150%
zondag	200%

Bij GET /availability en in het antwoord van POST /appointments staan de velden storing_only en surcharge_pct per slot.

Endpoints

GET /blocks

Geeft de vaste tijdblokken terug.

GET /availability

Geeft vrije slots terug. Optionele query-parameters from en to (formaat YYYY-MM-DD) en service (bijv. storing). Met service krijgt u alleen slots waarin die dienst geboekt mag worden (zonder service komen alle boekbare slots terug, met de vlag storing_only).

curl -H "X-Api-Key: UW_SLEUTEL" \
  "https://cederverwarming.nl/wp-json/ceder/v1/availability?from=2026-07-01&to=2026-07-15"

Antwoord:

{
  "count": 42,
  "window_until": "2026-07-26",
  "available_slots": [
    { "date": "2026-07-01", "block": "0800-1000",
      "label": "08:00 - 10:00", "arrival_from": "08:00", "arrival_to": "10:00" }
  ]
}

POST /appointments

Plant een afspraak namens een klant. Body in JSON.

veld	verplicht	omschrijving
customer.name	ja	naam van de klant
customer.email	ja	e-mailadres (klant krijgt bevestiging)
customer.phone	nee	telefoonnummer
customer.address	ja	bezoekadres (moet binnen 40 km rijden van Amsterdam liggen)
customer.company	nee	bedrijfsnaam (zakelijke klant)
customer.kvk	nee	KvK-nummer
customer.invoice_address	nee	afwijkend factuuradres
customer.invoice_email	nee	factuur-e-mailadres (alleen voor de administratie)
date	ja	datum YYYY-MM-DD (werkdag)
block	ja	tijdblok, bijv. 1000-1200
service	nee	onderhoud, storing, vervangen of anders. Voor weekend- of avondslots is alleen storing toegestaan.
notes	nee	toelichting

curl -X POST "https://cederverwarming.nl/wp-json/ceder/v1/appointments" \
  -H "X-Api-Key: UW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Jan Jansen", "email": "jan@voorbeeld.nl",
                  "phone": "020 244 2926", "address": "Silvoldestraat 94, Amsterdam" },
    "date": "2026-07-02", "block": "1000-1200",
    "service": "onderhoud", "notes": "CV-ketel Nefit"
  }'

Antwoord (201):

{
  "status": "ok",
  "appointment": {
    "id": 12, "date": "2026-07-02", "block": "1000-1200",
    "label": "10:00 - 12:00", "service": "Boiler or ventilation maintenance",
    "customer": { "name": "Jan Jansen", "email": "jan@voorbeeld.nl" }
  },
  "message": "Appointment scheduled. The customer receives a confirmation by email."
}

Foutcodes

status	betekenis
400	verplichte velden ontbreken of ongeldig
401	API-sleutel ontbreekt of is ongeldig
403	e-mailadres niet toegestaan
409	tijdslot niet beschikbaar of net bezet
422	adres ligt buiten het werkgebied (meer dan 40 km)

Een afspraak via de API is direct definitief (geen e-mailverificatie nodig); de klant ontvangt wel een bevestigingsmail.