Bookings

3 endpoints

get/v1/bookings

Lister les rendez-vous de l'agenda

Retourne la liste paginée (curseur v2) des rendez-vous de l'agenda du compte de la clé : tous ses calendriers, tous ses hôtes. Les rendez-vous archivés depuis le tableau de bord sont exclus. Tri stable start_datetime DESC, id DESC — les rendez-vous les plus lointains d'abord, puis l'historique.

Filtres

?from (ISO 8601) — start_datetime >= from
?to (ISO 8601) — start_datetime <= to
?status — confirmed, cancelled, completed ou no_show
?event_type_id — un calendrier du compte
?contact_id — une fiche du compte

Un filtre illisible est refusé 400 validation_error avec le champ et la raison (invalid_datetime, invalid_value, invalid_format) ; un curseur ou une limite invalide, 400 invalid_request. Un event_type_id ou un contact_id d'un autre compte rend une liste vide.

Scopes requis: bookings:read

Paramètres de requête

Nom	Type	Obligatoire	Description
`from`	`string`	optionnel	Uniquement les rendez-vous dont `start_datetime >= from`.
`to`	`string`	optionnel	Uniquement les rendez-vous dont `start_datetime <= to`.
`status`	`string`	optionnel	Filtre exact sur le statut.
`event_type_id`	`string`	optionnel	Uniquement les rendez-vous de ce calendrier.
`contact_id`	`string`	optionnel	Uniquement les rendez-vous de cette fiche.

Responses

Statut	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://api.capturia.io/v1/bookings' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'

post/v1/bookings

Réserver un rendez-vous

Réserve un rendez-vous dans l'agenda du compte, sur un de ses calendriers, par le même service que la page de réservation et le tableau de bord. Les règles du calendrier s'appliquent : ses hôtes actifs, leurs heures et leur agenda Google, la fenêtre de réservation, la cadence des créneaux, le maximum par jour, les séances de groupe, les questions requises, la règle d'accès et un seul rendez-vous à venir par fiche sur ce calendrier. L'heure demandée est tenue ou refusée avec sa raison — jamais remplacée par une autre. La durée est celle du calendrier ; l'hôte reçoit son avis et l'événement est posé dans son agenda comme pour toute réservation.

Chaque appel réussi crée un rendez-vous : ne rejoue pas un appel qui a abouti.

Refus

Le champ details.reason dit pourquoi, de façon stable :

Statut	`code`	`details.reason`
400	`validation_error`	`slot_in_past`, `outside_window`, `off_cadence` (`details.field = "start_datetime"`), `contact_or_guest_required`, `contact_without_email`, ou le code de la question en défaut (`details.field = "form_responses.<id>"`, `details.questions` : les questions du calendrier)
404	`resource_not_found`	— (`details.field` : `event_type_id`, `contact_id` ou `host_id`)
409	`duplicate_resource`	`already_booked` (`details.existing_booking_id`)
422	`business_rule_violation`	`calendar_without_hosts`, `host_not_on_calendar`, `host_unavailable` (`details.causes`), `slot_unavailable`, `contact_archived`, `lead_not_qualified`
503	`service_unavailable`	— (réessaie après `Retry-After`)

Une erreur de format d'un champ (400 validation_error) porte details sous forme de liste [{ field, reason }].

Scopes requis: bookings:write

Corps de requête

Propriété	Type	Obligatoire	Description
`event_type_id`	`string`	obligatoire	Calendrier actif du compte. Un calendrier inconnu, inactif ou d'un autre compte est refusé `404 resource_not_found` (`details.field = "event_type_id"`).
`start_datetime`	`string`	obligatoire	Début du rendez-vous, ISO 8601. Le décalage est facultatif : sans décalage, l'heure est lue en UTC. Préfère un décalage explicite (`2026-11-10T10:00:00-05:00`).
`contact_id`	`string`	optionnel	Fiche existante du compte. Une fiche inconnue ou d'un autre compte est refusée `404 resource_not_found` (`details.field = "contact_id"`) ; une fiche archivée, `422` (`contact_archived`) ; une fiche sans courriel et sans `guest_email`, `400` (`contact_without_email`).
`guest_name`	`string`	optionnel	Nom complet de l'invité. Obligatoire sans `contact_id`.
`guest_email`	`string`	optionnel	Courriel de l'invité. Obligatoire sans `contact_id`.
`guest_phone`	`string \| null`	optionnel	Téléphone de l'invité (E.164 recommandé). Pris en compte avec `guest_name` + `guest_email`.
`host_id`	`string`	optionnel	Membre de l'équipe qui doit tenir le rendez-vous. L'hôte demandé est tenu ou refusé avec sa raison, jamais remplacé : inconnu du compte, `404 resource_not_found` (`details.field = "host_id"`) ; pas hôte de ce calendrier, `422 host_not_on_calendar` ; occupé ou hors de ses heures, `422 host_unavailable`. Sans `host_id` : le vendeur de la fiche s'il peut tenir le créneau, sinon la rotation du calendrier.
`timezone`	`string \| null`	optionnel	Fuseau horaire IANA de l'invité (ex `America/Montreal`). Absent : celui de la fiche, sinon celui du calendrier. Un fuseau inconnu ou un décalage nu (`-04:00`) est refusé : `400 validation_error`, raison `invalid_timezone`.
`notes`	`string \| null`	optionnel	Notes libres.
`form_responses`	`object`	optionnel	Réponses au formulaire du calendrier : une entrée par question, sous l'identifiant de la question, de la forme `{ "value": ... }`. `value` est un texte, un nombre pour une question numérique, une des options pour une question à choix, ou une liste d'options pour une question à choix multiple. Un calendrier dont une question est requise refuse un rendez-vous sans sa réponse : `400 validation_error`, `details.field = "form_responses.<id>"`. Tout refus de formulaire porte `details.questions`, les questions du calendrier (`id`, `label`, `type`, `required`, `options`).

Responses

Statut	Description
`201`	Rendez-vous réservé.
`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).
`409`	Le lead a déjà un rendez-vous à venir sur ce calendrier (`duplicate_resource`, raison `already_booked`, avec `details.existing_booking_id`).
`415`	Le header `Content-Type` est manquant ou non supporté pour cet endpoint.
`422`	L'heure ou l'hôte demandé ne peut pas être tenu : calendrier sans hôte actif (`calendar_without_hosts`), hôte qui n'est pas hôte de ce calendrier (`host_not_on_calendar`), hôte indisponible (`host_unavailable`, causes dans `details.causes` : `outside_window`, `outside_hours`, `other_booking`, `blocked_time`, `google_busy`, `daily_max`), créneau pris ou complet (`slot_unavailable`), fiche archivée (`contact_archived`), lead écarté par la règle d'accès du calendrier ou disqualifié (`lead_not_qualified`).
`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.
`503`	Service temporairement indisponible (maintenance, dépendance externe down, infra dégradée). Le client devrait retry avec backoff exponentiel.

Exemple de requête

curl -X POST 'https://api.capturia.io/v1/bookings' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "event_type_id": "2b3c4d5e-6f7a-4b9c-8d1e-2f3a4b5c6d7e",
  "start_datetime": "2026-11-10T10:00:00-05:00",
  "contact_id": "0a1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d",
  "notes": "Premier rendez-vous découverte"
}'

delete/v1/bookings/{id}

Annuler un rendez-vous

Annulation douce — le rendez-vous n'est pas supprimé : son status passe à cancelled et cancelled_at est horodaté, comme une annulation faite au tableau de bord. L'événement est retiré de l'agenda de l'hôte, l'hôte est avisé, et l'annulation est tracée comme faite par une intégration de ton équipe. La réponse 200 retourne ces 3 champs (et non 204 No Content).

Seul un rendez-vous confirmed s'annule. Un rendez-vous déjà annulé retourne 422 business_rule_violation (raison already_cancelled) ; un rendez-vous tenu ou marqué absent, 422 (raison booking_not_cancellable). Un rendez-vous d'un autre compte est introuvable (404).

Pour changer d'heure, annule puis réserve de nouveau, ou replanifie depuis le tableau de bord — il n'y a pas de PATCH.

Scopes requis: bookings:write

Responses

Statut	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).
`422`	Le rendez-vous est déjà annulé (`already_cancelled`), ou il est tenu ou marqué absent (`booking_not_cancellable`).
`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://api.capturia.io/v1/bookings/{id}' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'