Saltar para o conteúdo

Calendar

A sua agenda, páginas de marcação e serviços.

Abrir Calendar
Verificado com o painel em 19 de novembro de 2026

O Calendar tem métodos públicos para os dois lados de uma reserva. Alguns atuam por si, o proprietário, e levam a sua chave de API: leem a sua configuração e as suas reservas, configuram recursos, serviços e páginas, retêm e confirmam uma hora, cancelam e alteram o plano. Outros são os que uma página de reservas faz por um visitante. Não precisam de chave, apenas da chave da página.

A partilha de calendários com outras pessoas, as vistas, as tarefas, os eventos do dia e as Configurações do Calendário fazem-se no dashboard. Hoje não têm método público.

Envie um pedido a um método com a sua chave:

curl -s https://xuda.ai/cpi/get_calendar_setup \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID"}'
const res = await fetch('https://xuda.ai/cpi/get_calendar_setup', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/get_calendar_setup',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
    },
)

Uma boa resposta tem code 1. Uma alteração que o seu plano não inclui é recusada com code -62 e uma frase em data, por exemplo que as sessões de grupo precisam do Growth ou que o seu plano comporta um número de páginas de reservas. Para atuar no calendário de uma conta que o partilhou consigo ao nível de edição, passe o seu share_id aos métodos que o aceitam.

Ler a sua configuração e reservas

  • get_calendar_setup responde, numa só chamada, a tudo o que os ecrãs do Calendar desenham: as pessoas e salas reserváveis com os seus horários, os serviços e as páginas de reservas publicadas com os seus endereços públicos.
  • get_calendar_bookings lista reservas, as próximas por omissão. Passe past como true para as que já aconteceram, a mais recente primeiro, e limit para quantas. Cada linha traz a hora no fuso do recurso, os dados do convidado e tudo o que ele disse ao reservar.
  • get_calendar_slots lista as horas reserváveis de um serviço num recurso entre from_ts e to_ts (milissegundos desde a época), sem tudo o que já está ocupado.

Configurar o que pode ser reservado

  • save_calendar_resource cria ou atualiza algo que pode ser reservado: uma pessoa, uma sala, uma cadeira ou um dispositivo. Precisa de um timezone, um fuso IANA como Asia/Jerusalem, e o seu horário é lido nesse fuso. Omita resource_id para criar um novo.
  • save_calendar_service cria ou atualiza o que as pessoas podem reservar: a sua duração, margens, antecedência, com quanta antecedência pode ser reservado, lugares, onde decorre (meeting_kind) e, com price_cents, currency e checkout, quanto custa e se é pago na reserva. Mais do que um lugar exige um plano que inclua sessões de grupo, e receber pagamentos exige um plano que inclua pagamentos.
  • save_calendar_page cria ou atualiza uma página de reservas: o seu title, intro, os service_ids que oferece, se está enabled, a sua cor accent, show_host, se os visitantes podem alterar a sua reserva (visitor_changes, change_hours, refund_percent) e a conta financeira para onde é paga (finance_account_id). Criar uma página além do limite de páginas do seu plano é recusado.
  • delete_calendar_item remove um recurso, um serviço ou uma página por item_id. As reservas nunca são eliminadas desta forma: são canceladas.

Reservar uma hora você mesmo

Reservar a partir do seu próprio código são dois passos, para que uma hora nunca seja vendida duas vezes.

Retenha a hora

hold_calendar_slot reserva uma hora durante alguns minutos. Passe resource_id, service_id e start_utc (milissegundos desde a época). Uma boa resposta tem data com occ_id, hold_token e expires_at. Envie uma idem_key para que uma repetição da chamada devolva a mesma retenção em vez de ocupar um segundo lugar.

Confirme-a

confirm_calendar_booking transforma a retenção numa reserva. Passe o occ_id e o hold_token da retenção, e o name, email, phone e note do convidado. Uma retenção que já não existe perdeu a hora e é recusada.

curl -s https://xuda.ai/cpi/hold_calendar_slot \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID","resource_id":"RESOURCE_ID","service_id":"SERVICE_ID","start_utc":1793000000000}'
const res = await fetch('https://xuda.ai/cpi/hold_calendar_slot', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
    resource_id: 'RESOURCE_ID',
    service_id: 'SERVICE_ID',
    start_utc: 1793000000000,
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/hold_calendar_slot',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
        'resource_id': 'RESOURCE_ID',
        'service_id': 'SERVICE_ID',
        'start_utc': 1793000000000,
    },
)

Alterar uma reserva

  • cancel_calendar_booking cancela por booking_id e devolve a hora à grelha pública. É seguro chamá-lo duas vezes. Só liberta a hora: não envia email ao convidado nem reembolsa um pagamento, o que o Cancelar compromisso do dashboard faz para um convidado que reservou através da sua página.
  • notify_calendar_guests envia email a todos os convidados de uma reserva, uma mensagem a cada um, com o convite de calendário anexado e uma message opcional até 2000 carateres. kind é invite para uma nova marcação e update para uma alteração, que é o valor por omissão. O email sai da sua própria caixa de correio num plano que a inclui, e do endereço de reservas da Xuda caso contrário, com o seu endereço como resposta.
  • create_booking_room cria a sala Xuda Meet de uma reserva de vídeo confirmada que não tem nenhuma, e envia a cada convidado a ligação.

O que uma página de reservas chama

Uma página de reservas funciona com a sua chave de página, <uid>.<page_id>, e sem conta.

  • get_booking_bootstrap responde ao que uma página precisa para se desenhar: o seu título, os seus serviços e um novo token anti-bot.
  • get_public_booking_slots lista as horas que um visitante pode escolher, cada uma com um início, um fim e uma contagem de lugares. Nunca diz quem ocupa os outros lugares.
  • public_book_slot aceita uma reserva de um visitante. Passe o page_key, service_id, start_utc, o token, e o name e email do visitante. Acrescente uma idem_key para que um duplo clique não reserve duas vezes. company_website é uma armadilha para bots: deixe-o vazio.
  • Para um serviço pago na reserva, public_start_paid_booking retém a hora e inicia o pagamento, start_booking_payment envia uma hora retida para o Stripe, e public_confirm_paid_booking e confirm_paid_booking reservam-na quando o pagamento foi concluído. O pagamento é lido de volta do Stripe antes de qualquer reserva.
  • Um visitante gere uma reserva a partir da ligação privada no seu email. get_public_booking, public_cancel_booking e public_reschedule_booking recebem a chave da página e o valor manage dessa ligação. Seguem as regras da página: se os visitantes podem alterar uma reserva e até quantas horas antes de começar. Uma reserva paga é primeiro reembolsada, pela percentagem de reembolso da página.

O plano

get_calendar_plans responde com os quatro níveis, com os seus preços e o que cada um inclui, em que plano está e se o Calendar está ativo. calendar_set_plan ativa-o, altera o nível ou desativa-o: passe plan_id como calendar_free, calendar_starter, calendar_growth ou calendar_business, ou defina deactivate como true. Consulte Planos e faturação.

Todos os métodos

Que tal está este guia?

Última atualização em 16 de novembro de 2026