Bookings

3 endpoints

get/v1/bookings

Lister les rendez-vous

Retourne la liste paginée des rendez-vous (cursor v2). Tri stable start_datetime DESC, id DESC — les rendez-vous à venir apparaissent d'abord, puis l'historique.

L'isolation tenant est appliquée via une résolution préalable des projets autorisés : si le client n'a aucun projet, la liste retournée est vide (pas d'erreur).

Filtres

?from (ISO 8601) — start_datetime >= from
?to (ISO 8601) — start_datetime <= to
?status — filtre exact (confirmed, cancelled, etc.)
?project_id — filtre exact ; un project_id qui n'appartient pas au client retourne une liste vide (pas une erreur).

Scopes requis: bookings:read

Paramètres de requête

Nom	Type	obligatoire	Description
`from`	`string`	optionnel	Filtre — uniquement les rendez-vous dont `start_datetime >= from`.
`to`	`string`	optionnel	Filtre — uniquement les rendez-vous dont `start_datetime <= to`.
`status`	`string`	optionnel	Filtre exact sur le statut (`confirmed`, `cancelled`, etc.).
`project_id`	`string`	optionnel	Filtre par projet client. Un `project_id` hors du client retourne une liste vide.

Responses

Status	Description
`200`	Liste paginée des rendez-vous.
`400`	La requête est mal formée (header manquant, JSON invalide, paramètre invalide).
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X GET 'https://app.capturia.io/api/v1/bookings' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

post/v1/bookings

Créer un rendez-vous

Crée un rendez-vous dans le projet ciblé. Le project_id doit appartenir au client appelant — sinon 404 resource_not_found. S'il est fourni, event_type_id doit référencer un type d'événement actif du catalogue Capturia — sinon 404 resource_not_found, sans création.

Les champs status et source ne sont pas acceptés du caller : forcés à confirmed / api côté serveur. Pour annuler un rendez-vous, utiliser DELETE /v1/bookings/{id} (soft cancel).

Format des dates

Aucune validation côté serveur du format ISO 8601 sur start_datetime / end_datetime — les valeurs sont transmises telles quelles à Postgres qui rejettera un format invalide (500 internal_error). Préférer ISO 8601 UTC (...Z) pour éviter les ambiguïtés de fuseau.

Scopes requis: bookings:write

Corps de requête

#/components/schemas/BookingCreate

Responses

Status	Description
`201`	Rendez-vous créé.
`400`	Validation des paramètres ou du body a échoué.
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`415`	Le header `Content-Type` est manquant ou non supporté pour cet endpoint.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X POST 'https://app.capturia.io/api/v1/bookings' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "guest_name": "Alex Tremblay",
  "guest_email": "[email protected]",
  "guest_phone": "+15145551234",
  "start_datetime": "2026-05-10T14:00:00.000Z",
  "end_datetime": "2026-05-10T15:00:00.000Z",
  "timezone": "America/Montreal",
  "notes": "Premier rendez-vous découverte"
}'

delete/v1/bookings/{id}

Annuler un rendez-vous (soft cancel)

Soft cancel — le rendez-vous n'est pas supprimé physiquement : son status passe à cancelled et cancelled_at est horodaté. La réponse 200 retourne ces 3 champs (et non 204 No Content).

Un second DELETE sur un rendez-vous déjà annulé retourne 409 already_cancelled — l'opération n'est pas idempotente côté statut HTTP.

Pour modifier un rendez-vous existant (changement d'horaire, de notes), il faut l'annuler et en créer un nouveau — il n'y a pas de méthode PATCH sur cet endpoint.

Scopes requis: bookings:write

Responses

Status	Description
`200`	Rendez-vous annulé. Retourne le statut et l'horodatage de l'annulation.
`401`	Clé API inconnue ou format invalide.
`403`	Refus d'autorisation. Deux causes, distinguées par `code` : `insufficient_scope` (la clé ne possède pas le scope requis — `details.required_scope`) ou `feature_not_available` (l'API publique ou le module visé n'est pas inclus dans le forfait du compte — `details.feature` nomme la fonctionnalité, ex. `public_api`, `quotes`). Un refus de forfait est définitif pour la clé : inutile de réessayer, le compte doit changer de forfait.
`404`	La ressource demandée n'existe pas (ou pas dans le scope du tenant).
`409`	La requête est syntaxiquement valide mais viole une règle métier.
`429`	Le quota de requêtes par fenêtre est dépassé pour cette clé API ou cet endpoint.
`500`	Erreur serveur inattendue. Toujours fournir le `request_id` au support.

Exemple de requête

curl -X DELETE 'https://app.capturia.io/api/v1/bookings/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'