Vai al contenuto principale

Bookings

La Bookings API dà alle integrazioni accesso in lettura ai booking e ai booking type (event type) del workspace. Si abbina a webhook outbound che notificano i tuoi sistemi ogni volta che un booking cambia — creato, confirmed, cancelled, rescheduled, declined, reassigned o segnalato come no-show.

Gli endpoint di lettura sono scopati al workspace del token: non puoi mai leggere i booking di un altro workspace.

Quick Start​

# 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"

Disponibile in​

Public APICLIMCPCopera AI
✅ Read-only———

Gli endpoint di lettura sono disponibili sulla Public API. I Bookings non sono ancora esposti tramite la CLI, l'MCP server hostato o l'assistente Copera AI in-app.

informazione

Gli endpoint Bookings non sono ancora nel API Reference live — la produzione non ha ancora spedito la superficie OpenAPI per essi. Fino ad allora, questa guida è il riferimento; usa le forme di request sotto con la Public API.

Superficie read-only​

La Public API espone tre endpoint GET. Non ci sono endpoint create, cancel, confirm, decline o reschedule — i booking si gestiscono nell'app Copera e si leggono tramite l'API.

List bookings​

GET /public/v1/bookings restituisce i booking del workspace, più recenti prima, con paginazione keyset. Query parameter (tutti opzionali):

  • status — PENDING, CONFIRMED, DECLINED, CANCELLED o COMPLETED.
  • bookingTypeId — restringi a un singolo booking type.
  • from / to — date-time ISO-8601; filtra per l'ora di start del booking.
  • limit — 1–100 (default 25).
  • cursor — il nextCursor da una response precedente.
curl -X GET "https://api.copera.ai/public/v1/bookings?status=CONFIRMED&limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

La response è paginata keyset:

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

Get a booking​

GET /public/v1/bookings/{uid} restituisce un singolo booking per il suo public uid. Il path parameter accetta anche l'_id 24-hex del booking — l'identificatore che i webhook consegnano come data.id — così un receiver di webhook può recuperare il booking di cui è stato notificato senza conoscere l'uid.

List booking types​

GET /public/v1/booking-types restituisce i booking type (event type) del workspace. Non prende parametri e li restituisce tutti, inclusi quelli hidden e inactive (ciascuno porta i flag hidden e active così puoi filtrare client-side).

Cosa contiene un booking​

Un oggetto booking include il suo uid, status, il bookingTypeId e bookingTypeTitle, start / end / durationMinutes, timezoneAtBooking, gli hosts (ciascuno { userId, role }), il booker (name, email, phone opzionale, timezone, locale), guests, le form answers e la location. Poiché questi sono i dati del tuo workspace, i dettagli di contatto del booker sono inclusi; handle interni come manage token e idempotency key non vengono mai esposti.

Un booking type include il suo _id, title, slug e description opzionali, kind, durationMinutes, color opzionale, i flag hidden e active e i timestamp.

Webhook​

Oltre a leggere i booking, puoi ricevere webhook outbound che notificano i tuoi sistemi ogni volta che un booking cambia. Vedi Booking Webhooks per l'elenco eventi, il payload firmato, gli header, la verifica della signature e il contratto di delivery/retry.

Autenticazione e scope​

Gli endpoint Bookings accettano un Personal Access Token completo (cp_pat_) o un'integration API key (cp_key_) con lo scope access_bookings. Un token senza lo scope ottiene un 403. Vedi Autenticazione.

Riferimento​

  • Booking Webhooks — elenco eventi, payload firmato, header, verifica della signature e contratto di delivery/retry.
  • Autenticazione e Paginazione — scope dei token e modello cursor keyset usato da list bookings.