De API van Qouh

Aan de slag

1. Maak een sleutel aan via Instellen → Integraties (op Starter, Pro en tijdens de proefperiode). Sleutels beginnen met qh_ en worden één keer getoond.
2. Test hem: GET /v1/me antwoordt met de naam van je organisatie.
3. Bouw verder met de naslag hieronder, of koppel Zapier zonder code te schrijven.

curl "https://qouh.com/api/v1/me" \
  -H "Authorization: Bearer $ROUTE_TRIM_KEY"

Sleutels en rechten

Stuur de sleutel mee in de header Authorization: Bearer van elk verzoek, via https. Een sleutel kan alleen wat je toestond toen je hem maakte:

• bookings:read: Afspraken en vrije tijden bekijken
• bookings:write: Afspraken maken, verplaatsen en annuleren
• customers:read: Klanten bekijken
• customers:write: Klanten toevoegen en bijwerken
• webhooks:manage: Webhooks instellen (voor Zapier)

Elke sleutel mag 120 verzoeken per minuut doen; daarboven antwoordt de API met 429 en een header Retry-After. Een sleutel die je intrekt op de pagina Integraties werkt meteen niet meer.

Tijden en pagina’s

Tijden zijn ISO 8601 in UTC. Lijsten komen per pagina: geef de nextCursor uit het antwoord mee als cursor tot die null is.

Fouten

Een fout antwoordt met een HTTP-status en een body met een vaste code en een leesbare message:

{
  "error": {
    "code": "slot_unavailable",
    "message": "This time is not offered (any more). Pick one from GET /v1/slots."
  }
}

• 400 The query or body is not valid (invalid_request).
• 401 No key, or a key that is not valid or was revoked (unauthorized).
• 403 The plan has no API (plan_required) or the key lacks the permission (insufficient_scope).
• 404 Not found, or it belongs to another organization (not_found).
• 409 The time is not offered (slot_unavailable), the booking is cancelled or has started (not_changeable), another customer has the email (email_taken), the webhook limit is reached (limit_reached), or a request with this Idempotency-Key is still running (idempotency_in_progress).
• 422 The address could not be found (address_not_found), or the Idempotency-Key was used for another request (idempotency_key_reused).
• 429 More than 120 requests a minute with this key (rate_limited); see Retry-After.
• 503 Address lookup or routing is unavailable for a moment (unavailable).

Veilig opnieuw proberen

Schrijfverzoeken nemen een optionele header Idempotency-Key (bijvoorbeeld een UUID). Dezelfde sleutel opnieuw binnen 24 uur krijgt het eerste antwoord terug, gemarkeerd met Idempotent-Replayed: true, zodat een nieuwe poging nooit twee keer boekt.

Webhooks

Voeg een endpoint toe via Instellen → Integraties, of abonneer via de API, om afspraken en klanten te volgen terwijl ze veranderen. Elke gebeurtenis wordt als JSON gePOST met deze headers. Een mislukte levering wordt ongeveer een dag opnieuw geprobeerd; een endpoint dat 3 dagen blijft falen wordt uitgezet en de eigenaars krijgen een e-mail.

Controleer de handtekening (Standard Webhooks) voor je een gebeurtenis vertrouwt, weiger tijdstempels die meer dan 5 minuten afwijken, en gebruik webhook-id om herhalingen over te slaan. In Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto'

// secret: the whsec_… shown when you added the endpoint
// rawBody: the request body exactly as received, before parsing
function verify(secret, headers, rawBody) {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64')
  const expected = Buffer.from(
    createHmac('sha256', key).update(id + '.' + timestamp + '.' + rawBody).digest('base64'),
  )
  return headers['webhook-signature'].split(' ').some((part) => {
    const given = Buffer.from(part.slice('v1,'.length))
    return part.startsWith('v1,') && given.length === expected.length && timingSafeEqual(given, expected)
  })
}

Zapier

Onze Zapier-app is voorlopig privé: vraag ons een uitnodiging via de contactpagina. Koppel hem met een sleutel met “Volledige toegang”. Zaps kunnen starten bij een nieuwe, gewijzigde of geannuleerde afspraak of een nieuwe klant, en kunnen een klant toevoegen of bijwerken, een klant zoeken en de eerste vrije tijd boeken.