Pular para o conteúdo principal

Bookings

A Bookings API dá às integrações acesso de leitura aos bookings e tipos de booking (tipos de evento) do seu workspace. Ela funciona em conjunto com webhooks de saída que notificam seus sistemas sempre que um booking muda — criado, confirmado, cancelado, reagendado, recusado, reatribuído ou marcado como no-show.

Os endpoints de leitura são limitados ao workspace do seu token: você nunca consegue ler os bookings de outro 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"

Disponível em​

Public APICLIMCPCopera AI
✅ Somente leitura———

Os endpoints de leitura estão disponíveis na Public API. Bookings ainda não são expostos pela CLI, pelo servidor MCP hospedado ou pelo assistente Copera AI dentro do app.

informação

Os endpoints de Bookings ainda não estão na API Reference ativa — a produção ainda não publicou a superfície OpenAPI deles. Até lá, este guia é a referência; use os formatos de requisição abaixo com a Public API.

Superfície somente leitura​

A Public API expõe três endpoints GET. Não há endpoints de criar, cancelar, confirmar, recusar ou reagendar — os bookings são gerenciados dentro do app Copera e lidos pela API.

List bookings​

GET /public/v1/bookings retorna os bookings do workspace, do mais recente para o mais antigo, com keyset pagination. Parâmetros de query (todos opcionais):

  • status — PENDING, CONFIRMED, DECLINED, CANCELLED ou COMPLETED.
  • bookingTypeId — restringe a um único tipo de booking.
  • from / to — date-times ISO-8601; filtra pelo horário de início do booking.
  • limit — 1–100 (padrão 25).
  • cursor — o nextCursor de uma resposta anterior.
curl -X GET "https://api.copera.ai/public/v1/bookings?status=CONFIRMED&limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

A resposta usa keyset pagination:

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

Get a booking​

GET /public/v1/bookings/{uid} retorna um único booking pelo seu uid público.

List booking types​

GET /public/v1/booking-types retorna os tipos de booking (tipos de evento) do workspace. Não aceita parâmetros e retorna todos eles, inclusive os ocultos e inativos (cada um traz as flags hidden e active para que você possa filtrar no lado do cliente).

O que um booking contém​

Um objeto de booking inclui seu uid, status, o bookingTypeId e bookingTypeTitle, start / end / durationMinutes, timezoneAtBooking, os hosts (cada um { userId, role }), o booker (name, email, phone opcional, timezone, locale), guests, as answers do formulário e a location. Como esses são os dados do seu próprio workspace, os dados de contato do booker estão incluídos; handles internos como o manage token e a idempotency key nunca são expostos.

Um tipo de booking inclui seu _id, title, slug e description opcionais, kind, durationMinutes, color opcional, as flags hidden e active, e timestamps.

Webhooks​

Além de ler bookings, você pode receber webhooks de saída que notificam seus sistemas sempre que um booking muda. Veja Booking Webhooks para a lista de eventos, o payload assinado, os headers, a verificação de assinatura e o contrato de entrega/retry.

Autenticação e escopo​

Os endpoints de Bookings aceitam um Personal Access Token completo (cp_pat_) ou uma integration API key (cp_key_) com o escopo access_bookings. Um token sem o escopo recebe um 403. Veja Autenticação.

Referência​

  • Booking Webhooks — a lista de eventos, o payload assinado, os headers, a verificação de assinatura e o contrato de entrega/retry.
  • Autenticação e Paginação — escopos de token e o modelo de keyset cursor usado por list bookings.