Aller au contenu principal

Bookings

L'API Bookings donne aux intégrations un accès en lecture aux bookings et types de booking (types d'événements) de votre workspace. Elle s'associe à des webhooks sortants qui notifient vos systèmes chaque fois qu'un booking change — créé, confirmé, annulé, replanifié, refusé, réassigné, ou signalé comme no-show.

Les endpoints de lecture sont scopés au workspace de votre token : vous ne pouvez jamais lire les bookings d'un autre workspace.

Démarrage rapide​

# List bookings (newest first, keyset pagination)
curl -X GET "https://api.copera.ai/public/v1/bookings?status=CONFIRMED&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a single booking by its public uid
curl -X GET https://api.copera.ai/public/v1/bookings/BOOKING_UID \
  -H "Authorization: Bearer YOUR_API_KEY"

# List booking types (event types)
curl -X GET https://api.copera.ai/public/v1/booking-types \
  -H "Authorization: Bearer YOUR_API_KEY"

Disponible dans​

Public APICLIMCPCopera AI
✅ Lecture seule———

Les endpoints de lecture sont disponibles via la Public API. Les Bookings ne sont pas encore exposés via la CLI, le serveur MCP hébergé, ou l'assistant Copera AI intégré à l'app.

info

Les endpoints Bookings ne sont pas encore dans la Référence de l'API en direct — la production n'a pas encore livré la surface OpenAPI pour eux. En attendant, ce guide fait office de référence ; utilisez les formes de requête ci-dessous avec la Public API.

Surface en lecture seule​

La Public API expose trois endpoints GET. Il n'y a pas d'endpoints create, cancel, confirm, decline ou reschedule — les bookings sont gérés dans l'app Copera et lus via l'API.

Lister les bookings​

GET /public/v1/bookings renvoie les bookings du workspace, les plus récents en premier, avec pagination keyset. Paramètres de requête (tous optionnels) :

  • status — PENDING, CONFIRMED, DECLINED, CANCELLED ou COMPLETED.
  • bookingTypeId — restreindre à un seul type de booking.
  • from / to — date-heures ISO-8601 ; filtrer par l'heure de début du booking.
  • limit — 1–100 (défaut 25).
  • cursor — le nextCursor d'une réponse précédente.
curl -X GET "https://api.copera.ai/public/v1/bookings?status=CONFIRMED&limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

La réponse est paginée par keyset :

{ "bookings": [ /* … */ ], "nextCursor": "…", "hasMore": true }

Obtenir un booking​

GET /public/v1/bookings/{uid} renvoie un booking unique par son uid public. Le paramètre de chemin accepte aussi le _id 24-hex du booking — l'identifiant que les webhooks livrent comme data.id — afin qu'un récepteur de webhook puisse récupérer le booking dont il a été notifié sans connaître l'uid.

Lister les types de booking​

GET /public/v1/booking-types renvoie les types de booking (types d'événements) du workspace. Il ne prend aucun paramètre et les renvoie tous, y compris les cachés et inactifs (chacun porte des flags hidden et active pour filtrer côté client).

Ce qu'un booking contient​

Un objet booking inclut son uid, status, le bookingTypeId et bookingTypeTitle, start / end / durationMinutes, timezoneAtBooking, les hosts (chacun { userId, role }), le booker (name, email, phone optionnel, timezone, locale), guests, les answers du formulaire, et le location. Comme ce sont les données de votre propre workspace, les coordonnées du booker sont incluses ; les handles internes comme le token de gestion et la clé d'idempotence ne sont jamais exposés.

Un type de booking inclut son _id, title, slug et description optionnels, kind, durationMinutes, color optionnel, les flags hidden et active, et des horodatages.

Webhooks​

Au-delà de la lecture des bookings, vous pouvez recevoir des webhooks sortants qui notifient vos systèmes chaque fois qu'un booking change. Voir Webhooks de bookings pour la liste des événements, la charge utile signée, les en-têtes, la vérification de signature, et le contrat de livraison/retry.

Authentification et scope​

Les endpoints bookings acceptent un Personal Access Token complet (cp_pat_) ou une Integration API Key (cp_key_) avec le scope access_bookings. Un token sans ce scope obtient un 403. Voir Authentification.

Référence​

  • Webhooks de bookings — la liste des événements, la charge utile signée, les en-têtes, la vérification de signature, et le contrat de livraison/retry.
  • Authentification et Pagination — scopes de tokens et le modèle de curseur keyset utilisé par list bookings.