L’API Qouh

Premiers pas

1. Créez une clé dans Configuration → Intégrations (sur Starter, Pro et pendant l’essai). Les clés commencent par qh_ et ne sont affichées qu’une fois.
2. Testez-la : GET /v1/me répond avec le nom de votre organisation.
3. Appuyez-vous sur la référence ci-dessous, ou connectez Zapier sans écrire de code.

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

Clés et autorisations

Envoyez la clé dans l’en-tête Authorization: Bearer de chaque requête, en https. Une clé ne peut faire que ce que vous avez autorisé en la créant :

• bookings:read: Voir les rendez-vous et les créneaux libres
• bookings:write: Créer, déplacer et annuler des rendez-vous
• customers:read: Voir les clients
• customers:write: Ajouter et modifier des clients
• webhooks:manage: Configurer des webhooks (pour Zapier)

Chaque clé peut faire 120 requêtes par minute ; au-delà, l’API répond 429 avec un en-tête Retry-After. Une clé révoquée sur la page Intégrations cesse aussitôt de fonctionner.

Heures et pages

Les heures sont au format ISO 8601 en UTC. Les listes arrivent page par page : passez le nextCursor de la réponse comme cursor jusqu’à ce qu’il soit null.

Erreurs

Une erreur répond avec un statut HTTP et un corps contenant un code stable et un message lisible :

{
  "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).

Réessayer sans risque

Les écritures acceptent un en-tête facultatif Idempotency-Key (un UUID, par exemple). La même clé renvoyée dans les 24 heures obtient la première réponse, marquée Idempotent-Replayed: true : un nouvel essai ne réserve jamais deux fois.

Webhooks

Ajoutez un endpoint dans Configuration → Intégrations, ou abonnez-vous via l’API, pour suivre les rendez-vous et les clients au fil de leurs changements. Chaque événement est envoyé en POST au format JSON avec ces en-têtes. Une livraison échouée est réessayée pendant environ un jour ; un endpoint qui échoue pendant 3 jours est désactivé et les propriétaires reçoivent un e-mail.

Vérifiez la signature (Standard Webhooks) avant de faire confiance à un événement, refusez les horodatages décalés de plus de 5 minutes, et utilisez webhook-id pour ignorer les doublons. En 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

Notre application Zapier est privée pour l’instant : demandez-nous une invitation via la page de contact. Connectez-la avec une clé « Accès complet ». Les Zaps peuvent démarrer quand un rendez-vous est pris, modifié ou annulé ou qu’un client est ajouté, et peuvent ajouter ou mettre à jour un client, trouver un client et réserver le premier créneau libre.