Documentação da API e do MCP

Sua empresa já tem um bot que conversa com os clientes no WhatsApp? Conecte esse bot ao Calendsk e ele passa a consultar horários e agendar direto na agenda do negócio. O bot cuida da conversa; o Calendsk guarda os agendamentos, impede dois clientes no mesmo horário e, se você quiser, manda o lembrete.

Servidor MCP

https://calendsk.com.br/api/mcp

API REST

https://calendsk.com.br/api/v1
  • Dois caminhos, as mesmas operações: agentes de IA usam o servidor MCP; qualquer outro sistema usa a API REST.
  • Requisições e respostas em JSON, com campos em snake_case.
  • Sucesso: { "success": true, "data": { … } }. Erro: { "success": false, "code": "…", "message": "…" }.
  • Cada API key pertence a um negócio e só enxerga a agenda dele.

Começo rápido

  • Crie uma conta no Calendsk e cadastre serviços, profissionais e horários de atendimento.
  • No painel, abra Ajustes → API e MCP para bots e crie uma API key. Ela aparece uma única vez: copie na hora.
  • Faça as três chamadas abaixo (ou conecte o agente pelo MCP).
bash
export CALENDSK_URL="https://calendsk.com.br"
export CALENDSK_API_KEY="csk_SUA_API_KEY"

# 1. Serviços, profissionais, fuso e data de hoje
curl "$CALENDSK_URL/api/v1/business" -H "Authorization: Bearer $CALENDSK_API_KEY"

# 2. Horários livres do serviço nos próximos 3 dias
curl "$CALENDSK_URL/api/v1/slots?service_id=ID_DO_SERVICO&days=3" \
  -H "Authorization: Bearer $CALENDSK_API_KEY"

# 3. Agendar no horário que o cliente escolheu
curl -X POST "$CALENDSK_URL/api/v1/bookings" \
  -H "Authorization: Bearer $CALENDSK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conversa-8842-pedido-1" \
  -d '{
    "service_id": "ID_DO_SERVICO",
    "starts_at": "STARTS_AT_DO_HORARIO",
    "customer_name": "Pedro Lima",
    "customer_phone": "+5581999990000"
  }'

Autenticação

Há dois jeitos de entrar. Os dois dão acesso à agenda de um único negócio.

JeitoOnde valeQuando usar
API keyAPI REST e MCPBot que roda no seu servidor (WhatsApp, n8n, script). Você cria a key e cola na configuração do bot.
Login por OAuthMCPAgente com tela de conexão (Claude, ChatGPT, OpenClaw, Hermes). Você entra na sua conta e autoriza, sem copiar chave.

API key

A key vai no cabeçalho Authorization: Bearer csk_… (ou em X-API-Key). Ela tem o formato csk_[A-Za-z0-9_-]{43} e o Calendsk guarda só o hash dela.

PermissãoO que pode fazer
readLer o negócio, os horários livres e os agendamentos.
writeTudo de read, mais criar, remarcar, cancelar e confirmar agendamentos.
  • Só o dono do negócio cria e revoga keys. Cada negócio pode ter até 10 keys ativas.
  • Revogar vale na hora: a próxima chamada com a key devolve 401 UNAUTHORIZED.
  • Key com permissão read em operação de escrita devolve 403 SCOPE_REQUIRED.
A API key dá acesso aos dados dos clientes do negócio (nome, celular, e-mail). Guarde no servidor do bot, nunca em aplicativo, página ou repositório. Se vazar, revogue e crie outra.

Login por OAuth

No MCP, o agente também pode entrar sem API key. Ele abre uma tela do Calendsk, o dono do negócio entra na conta e autoriza, e o agente recebe um token próprio. É o padrão OAuth 2.1 dos servidores MCP: quem conecta não precisa configurar nada além do endereço https://calendsk.com.br/api/mcp.

  • Descoberta automática: sem token, o MCP responde 401 apontando para /.well-known/oauth-protected-resource, que informa o servidor de login. O agente se registra sozinho (registro dinâmico de cliente) e usa PKCE.
  • O agente age como o usuário que autorizou, no negócio dele, com permissão de leitura e escrita.
  • A tela de autorização mostra o nome do agente e o que ele poderá fazer. Só autorize agentes que você mesmo configurou.
  • Para desconectar, abra Ajustes → API e MCP para bots → Agentes conectados por login. O token para de funcionar na hora.
  • A API REST (/api/v1) aceita só API key.

Datas, fuso e limites

  • Instantes (starts_at, from, to) são ISO 8601 com fuso, ex.: 2026-11-20T14:00:00-03:00. Sem fuso a requisição é recusada.
  • Hora para falar ao cliente: use local_time e starts_at_local, que já estão no fuso do negócio (timezone).
  • Datas (date) são AAAA-MM-DD no fuso do negócio. GET /business devolve a data de hoje em now.local_date.
  • Limite mensal: cada negócio tem um limite de agendamentos por mês, definido pelo plano. Agendamentos criados pelo bot contam nesse limite, como os da página pública e do painel. Quando acaba: 402 QUOTA_EXCEEDED.
  • Limite de requisições: 120 por minuto por API key, somando API e MCP. Acima disso: 429 RATE_LIMITED com Retry-After.
  • Prazo do cliente: o negócio define até quantas horas antes o cliente pode cancelar ou remarcar (cancel_window_hours). A API respeita esse prazo; force: true ignora e deve ser usado só quando o negócio autorizou.
  • Lembrete: por padrão o Calendsk manda um lembrete por WhatsApp até 24 h antes, também para agendamentos criados pelo bot (com celular válido). Se o seu bot já manda o próprio lembrete, desligue em Ajustes → API e MCP para bots. GET /business informa o estado em sends_reminders.
  • Horários: até 14 dias por consulta, em passos de 15 minutos, só no futuro.

Idempotência

Rede cai, bot repete. Para a repetição não virar dois agendamentos, envie uma chave única por pedido do cliente em Idempotency-Key (ou idempotency_key no corpo e no MCP). A mesma chave devolve o agendamento original, com 200, Idempotent-Replayed: true e idempotent_replay: true, sem consumir o limite do mês de novo.

  • Formato: 8 a 100 caracteres, com letras, números e _ . : -.
  • A chave vale para o negócio inteiro e não expira. Use algo como id da conversa + horário escolhido.
  • Sem chave, cada chamada cria um agendamento novo (se o horário ainda estiver livre).

Erros

Todo erro tem um code estável. Decida o próximo passo do bot pelo código, não pelo texto de message. No MCP, o mesmo JSON vem como texto do resultado da ferramenta, com isError: true.

json
{
  "success": false,
  "code": "SLOT_TAKEN",
  "message": "Este horário acabou de ser ocupado. Escolha outro horário.",
  "error": "Este horário acabou de ser ocupado. Escolha outro horário."
}
CódigoHTTPO que aconteceuO que o bot faz
VALIDATION_ERROR400Dados inválidos.Corrija o campo indicado em message e envie de novo.
UNAUTHORIZED401API key ausente, inválida ou revogada.Confira a key em Ajustes → API e MCP. Não adianta repetir.
SCOPE_REQUIRED403Esta operação exige uma API key com permissão write.Crie uma key com permissão de escrita.
NOT_FOUND404Registro não encontrado.Confira o id ou o código do agendamento.
QUOTA_EXCEEDED402Limite mensal de agendamentos atingido.Avise o cliente que a agenda online está fechada neste mês; retry_after diz quando o limite renova.
SLOT_TAKEN409Este horário acabou de ser ocupado.Busque os horários de novo e ofereça outro.
SLOT_IN_PAST422Este horário já passou.Ofereça um horário futuro.
OUTSIDE_AVAILABILITY422Horário fora da disponibilidade do profissional.Use só horários devolvidos pela consulta de horários livres.
SERVICE_UNAVAILABLE422Este serviço não está disponível.Leia a lista de serviços de novo.
PROFESSIONAL_UNAVAILABLE422Este profissional não está disponível.Escolha outro profissional ou não informe nenhum.
WINDOW_CLOSED409O prazo para o cliente alterar este agendamento já passou.Peça para o cliente falar com o negócio; force só vale quando o negócio autorizou.
ALREADY_CANCELLED409Este agendamento já foi cancelado.Não repita; crie um novo agendamento se o cliente quiser.
RATE_LIMITED429Muitas requisições. Aguarde e tente novamente.Espere retry_after segundos.
INTERNAL_ERROR500Erro interno. Tente novamente em instantes.Repita com a mesma chave de idempotência.
  • retry_after (segundos) acompanha RATE_LIMITED e QUOTA_EXCEEDED; na API REST também vem no cabeçalho Retry-After.
  • details traz dados extras quando existem: campos inválidos em VALIDATION_ERROR, prazo em WINDOW_CLOSED, uso e limite em QUOTA_EXCEEDED.

Servidor MCP

O Calendsk tem um servidor MCP remoto (Streamable HTTP) em https://calendsk.com.br/api/mcp. Um agente de IA conectado a ele enxerga a agenda como ferramentas: não precisa escrever chamadas HTTP nem ler esta página inteira.

  • Autenticação: a mesma API key da API REST, em Authorization: Bearer csk_….
  • As ferramentas chamam as mesmas funções da API REST: regras, limites e erros são iguais.
  • Sem API key? O agente pode entrar por login (OAuth).

Conectar o agente

Todo agente precisa de duas coisas: o endereço https://calendsk.com.br/api/mcp e um jeito de entrar (API key no cabeçalho Authorization ou login por OAuth). O que muda de um agente para outro é onde isso é escrito.

OpenClaw

  • A configuração fica em ~/.openclaw/openclaw.json, na chave mcp.servers.
  • Informe transport: "streamable-http". Sem esse campo o OpenClaw tenta SSE, que o Calendsk não oferece.
  • Guarde a key numa variável de ambiente (CALENDSK_API_KEY) e use ${CALENDSK_API_KEY} na configuração.
  • Para entrar por login em vez de API key, use auth: "oauth" e rode openclaw mcp login calendsk. Com auth: "oauth", o cabeçalho Authorization fixo é ignorado.
  • Confira a conexão com openclaw mcp doctor calendsk --probe.

Com API key

json5 · ~/.openclaw/openclaw.json
{
  mcp: {
    servers: {
      calendsk: {
        url: "https://calendsk.com.br/api/mcp",
        transport: "streamable-http",
        headers: { Authorization: "Bearer ${CALENDSK_API_KEY}" },
      },
    },
  },
}

Com login (OAuth)

bash
openclaw mcp set calendsk '{"url":"https://calendsk.com.br/api/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login calendsk

Conferido na documentação oficial: docs.openclaw.ai · MCP transports. Se o seu agente estiver em outra versão, vale o que a documentação dele disser.

Hermes Agent

  • A configuração fica em ~/.hermes/config.yaml, na chave mcp_servers.
  • Guarde a key em ~/.hermes/.env (CALENDSK_API_KEY=csk_...) e use ${CALENDSK_API_KEY} na configuração.
  • Para entrar por login em vez de API key, troque headers por auth: oauth e rode hermes mcp login calendsk.
  • Depois de salvar, rode /reload-mcp na conversa.
  • As ferramentas aparecem com o prefixo do servidor: mcp__calendsk__get_business, mcp__calendsk__create_booking etc.
  • Para um bot que só consulta, liste as ferramentas permitidas em tools.include.

Com API key

yaml · ~/.hermes/config.yaml
mcp_servers:
  calendsk:
    url: "https://calendsk.com.br/api/mcp"
    headers:
      Authorization: "Bearer ${CALENDSK_API_KEY}"

Com login (OAuth)

yaml · ~/.hermes/config.yaml
mcp_servers:
  calendsk:
    url: "https://calendsk.com.br/api/mcp"
    auth: oauth

Conferido na documentação oficial: hermes-agent.nousresearch.com · MCP config reference. Se o seu agente estiver em outra versão, vale o que a documentação dele disser.

Claude e ChatGPT

  • Adicione um conector personalizado (servidor MCP remoto) com o endereço abaixo.
  • Não precisa de API key: o aplicativo abre a tela do Calendsk, você entra na sua conta e autoriza.
  • Para desconectar depois, vá em Ajustes → API e MCP para bots → Agentes conectados por login.

Com login (OAuth)

endereço do conector
https://calendsk.com.br/api/mcp

Claude Code

  • Um comando registra o servidor. Com o cabeçalho, entra por API key; sem ele, rode /mcp dentro do Claude Code para entrar por login.

Com API key

bash
claude mcp add --transport http calendsk https://calendsk.com.br/api/mcp \
  --header "Authorization: Bearer csk_SUA_API_KEY"

Com login (OAuth)

bash
claude mcp add --transport http calendsk https://calendsk.com.br/api/mcp

OpenDots, Cursor, n8n e outros

  • Qualquer agente que aceite servidor MCP remoto (Streamable HTTP) conecta. A maioria usa o formato mcpServers abaixo; o nome dos campos pode mudar um pouco de um agente para outro.
  • Se o agente só aceita servidor MCP local (um comando), use a ponte mcp-remote, que roda no seu computador e repassa as chamadas.

Com API key

json
{
  "mcpServers": {
    "calendsk": {
      "url": "https://calendsk.com.br/api/mcp",
      "headers": { "Authorization": "Bearer csk_SUA_API_KEY" }
    }
  }
}

Agente sem MCP remoto

json · ponte local para agentes sem MCP remoto
{
  "mcpServers": {
    "calendsk": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://calendsk.com.br/api/mcp", "--header", "Authorization: Bearer csk_SUA_API_KEY"]
    }
  }
}
Dica para o prompt do seu bot: peça para ele chamar get_business no começo, oferecer só horários que vieram de get_available_slots e confirmar com o cliente antes de create_booking. O playbook atender_agendamento já traz esse passo a passo.

Ferramentas

FerramentaPermissãoO que faz
get_businessreadNegócio, serviços, profissionais, fuso, data de hoje e limite do mês. Chame no começo da conversa.
get_available_slotsreadHorários livres de um serviço, dia a dia (até 14 dias por chamada).
create_bookingwriteCria o agendamento; devolve o código e o link de gestão para o cliente.
list_bookingsreadLista agendamentos; com customer_phone, acha os de quem está na conversa.
get_bookingreadDetalhes de um agendamento pelo id ou pelo código.
reschedule_bookingwriteMuda o horário (e o profissional) do mesmo agendamento.
cancel_bookingwriteCancela e libera o horário, respeitando o prazo do negócio.
confirm_bookingwriteRegistra que o cliente confirmou presença.

Os campos de cada ferramenta são os mesmos dos endpoints abaixo. Nas ferramentas que recebem um agendamento, o campo se chama booking e aceita o id ou o código curto.

Playbooks

Prompts prontos que o servidor oferece ao agente, com o passo a passo de cada rotina:

PromptArgumentosPara quê
atender_agendamentotelefone, nome (opcionais)Passo a passo para atender um cliente que quer agendar, remarcar ou cancelar.
confirmar_agenda_do_diadata (opcional; padrão: amanhã)Passo a passo para pedir a confirmação de presença dos clientes de um dia.

Negócio

O que o bot precisa saber antes de conversar: serviços, profissionais, fuso e limite do mês.

GET/api/v1/businesspermissão: read

Negócio, serviços e profissionais

Devolve o negócio dono da API key. Chame no começo da conversa: é daqui que saem os ids de serviço e profissional, o fuso e a data de hoje.

  • now traz a data e a hora de agora no fuso do negócio: use para entender "amanhã" ou "sexta".
  • accepting = false significa que o limite do mês acabou: não ofereça horários.
  • price_cents é o preço em centavos; null quando o negócio não informou preço.
  • sends_reminders diz se o Calendsk manda o lembrete por WhatsApp para agendamentos criados pelo bot. O negócio liga e desliga em Ajustes; com false, o lembrete é do bot.

Exemplo de resposta (200)

json
{
  "success": true,
  "data": {
    "id": "3f1c…",
    "name": "Estúdio Marina",
    "slug": "estudio-marina",
    "booking_url": "https://calendsk.app/estudio-marina",
    "timezone": "America/Recife",
    "now": { "utc": "2026-11-13T15:00:00.000Z", "local_date": "2026-11-13", "local_time": "12:00", "weekday": 5 },
    "cancel_window_hours": 2,
    "accepting": true,
    "sends_reminders": true,
    "quota": { "used": 3, "limit": 10, "remaining": 7, "resets_at": "2026-12-01T03:00:00+00:00" },
    "services": [{ "id": "5d2f…", "name": "Corte", "duration_minutes": 30, "price_cents": 5000 }],
    "professionals": [{ "id": "9a41…", "name": "Marina", "service_ids": ["5d2f…"] }]
  }
}
GET/api/v1/usagepermissão: read

Uso do limite mensal

Quantos agendamentos o negócio já criou neste mês (por qualquer origem) e quando o limite renova.

Exemplo de resposta (200)

json
{
  "success": true,
  "data": {
    "bookings": { "used": 3, "limit": 10, "remaining": 7, "resets_at": "2026-12-01T03:00:00+00:00" },
    "accepting": true,
    "timezone": "America/Recife"
  }
}

Horários

Horários livres para oferecer ao cliente.

GET/api/v1/slotspermissão: read

Horários livres de um serviço

Horários livres dia a dia, já descontando agendamentos, folgas e o intervalo de cada profissional. Só horários que ainda não passaram.

  • Use o starts_at devolvido aqui, sem alterar, para criar ou remarcar.
  • local_time é a hora no fuso do negócio: é ela que o bot fala para o cliente.
  • Dia sem horário vem com slots vazio.

Parâmetros da consulta

NomeTipoObrigatórioDescrição
service_iduuidsimServiço, como veio em /business.
dateAAAA-MM-DDnãoPrimeiro dia, no fuso do negócio. Padrão: hoje.
daysintegernãoQuantos dias a partir de date (1 a 14). Padrão: 1.
professional_iduuidnãoSó horários deste profissional. Sem ele, qualquer profissional que atenda o serviço.

Exemplo de requisição

bash
curl "$CALENDSK_URL/api/v1/slots?service_id=5d2f…&date=2026-11-20&days=2" \
  -H "Authorization: Bearer $CALENDSK_API_KEY"

Exemplo de resposta (200)

json
{
  "success": true,
  "data": {
    "service_id": "5d2f…",
    "professional_id": null,
    "timezone": "America/Recife",
    "days": [
      {
        "date": "2026-11-20",
        "weekday": 5,
        "slots": [
          { "starts_at": "2026-11-20T17:00:00+00:00", "local_time": "14:00", "professional_ids": ["9a41…"] },
          { "starts_at": "2026-11-20T17:15:00+00:00", "local_time": "14:15", "professional_ids": ["9a41…"] }
        ]
      },
      { "date": "2026-11-21", "weekday": 6, "slots": [] }
    ]
  }
}

Erros desta operação: VALIDATION_ERROR, SERVICE_UNAVAILABLE, PROFESSIONAL_UNAVAILABLE.

Agendamentos

Criar, consultar, remarcar, cancelar e confirmar presença.

POST/api/v1/bookingspermissão: write

Criar agendamento

Cria um agendamento confirmado na agenda do negócio. O banco garante que dois clientes nunca ficam no mesmo horário com o mesmo profissional.

  • Consome 1 do limite mensal do negócio.
  • Informe customer_phone ou customer_email (pelo menos um).
  • Sem professional_id, o Calendsk escolhe um profissional livre que atenda o serviço.
  • manage_url é um link para o cliente ver, remarcar ou cancelar sozinho. Só vem na resposta da criação.
  • Com celular válido e sends_reminders ligado (veja /business), o Calendsk manda o lembrete por WhatsApp até 24 h antes do horário.
  • Repetição com a mesma chave de idempotência devolve 200 e o cabeçalho Idempotent-Replayed: true.

Cabeçalhos

NomeTipoObrigatórioDescrição
Idempotency-Keystringnão8 a 100 caracteres (letras, números, _ . : -). A mesma chave devolve o mesmo agendamento, sem criar outro.

Corpo (JSON)

NomeTipoObrigatórioDescrição
service_iduuidsimServiço, como veio em /business.
starts_atISO 8601simInício com fuso, como veio em /slots. Ex.: 2026-11-20T17:00:00+00:00.
customer_namestringsimNome do cliente (2 a 80 caracteres).
customer_phonestringnãoCelular com DDD. Número brasileiro sem +55 é aceito; fica guardado como +55DDDNÚMERO.
customer_emailstringnãoE-mail do cliente.
professional_iduuidnãoProfissional escolhido pelo cliente.
notesstringnãoObservação para o negócio (até 500 caracteres). O cliente não vê.
idempotency_keystringnãoAlternativa ao cabeçalho Idempotency-Key.

Exemplo de requisição

bash
curl -X POST "$CALENDSK_URL/api/v1/bookings" \
  -H "Authorization: Bearer $CALENDSK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conversa-8842-2026-11-20T17:00" \
  -d '{
    "service_id": "5d2f…",
    "starts_at": "2026-11-20T17:00:00+00:00",
    "customer_name": "Pedro Lima",
    "customer_phone": "+5581999990000",
    "notes": "Prefere máquina 2"
  }'

Exemplo de resposta (201)

json
{
  "success": true,
  "data": {
    "id": "0b6c2f0e-6f1a-4d59-9a53-6f0c1c7d2a11",
    "code": "A1B2C3D4",
    "status": "confirmed",
    "source": "api",
    "starts_at": "2026-11-20T17:00:00+00:00",
    "ends_at": "2026-11-20T17:30:00+00:00",
    "starts_at_local": "2026-11-20T14:00",
    "timezone": "America/Recife",
    "service": { "id": "5d2f…", "name": "Corte", "duration_minutes": 30 },
    "professional": { "id": "9a41…", "name": "Marina" },
    "customer": { "id": "c7e0…", "name": "Pedro Lima", "phone": "+5581999990000", "email": null },
    "notes": "Prefere máquina 2",
    "customer_confirmed_at": null,
    "reminder_sent_at": null,
    "can_modify": true,
    "created_at": "2026-11-13T15:02:11+00:00",
    "cancelled_at": null,
    "manage_url": "https://calendsk.app/manage#Jk3…",
    "quota": { "used": 4, "limit": 10 }
  }
}

Erros desta operação: VALIDATION_ERROR, SCOPE_REQUIRED, QUOTA_EXCEEDED, SLOT_TAKEN, SLOT_IN_PAST, OUTSIDE_AVAILABILITY, SERVICE_UNAVAILABLE, PROFESSIONAL_UNAVAILABLE.

GET/api/v1/bookingspermissão: read

Listar agendamentos

Agendamentos do negócio em ordem de horário. Com customer_phone, o bot acha os agendamentos de quem está falando com ele.

  • Sem from, a lista começa do agendamento mais antigo: informe from sempre que quiser só os próximos.
  • has_more = true: peça a próxima página com offset = next_offset.

Parâmetros da consulta

NomeTipoObrigatórioDescrição
customer_phonestringnãoCelular do cliente com DDD.
fromISO 8601nãoInício do período, inclusive.
toISO 8601nãoFim do período, exclusivo.
statusstringnãoconfirmed ou cancelled. Sem ele, os dois.
professional_iduuidnãoSó agendamentos deste profissional.
limitintegernãoItens por página. Padrão 50, máximo 100.
offsetintegernãoQuantos itens pular. Padrão: 0.

Exemplo de requisição

bash
curl "$CALENDSK_URL/api/v1/bookings?customer_phone=%2B5581999990000&status=confirmed&from=2026-11-13T15:00:00Z" \
  -H "Authorization: Bearer $CALENDSK_API_KEY"

Exemplo de resposta (200)

json
{
  "success": true,
  "data": {
    "bookings": [ { "id": "0b6c…", "code": "A1B2C3D4", "status": "confirmed", "starts_at_local": "2026-11-20T14:00", "…": "…" } ],
    "has_more": false,
    "limit": 50,
    "offset": 0,
    "next_offset": null
  }
}

Erros desta operação: VALIDATION_ERROR.

GET/api/v1/bookings/{id}permissão: read

Ver agendamento

Um agendamento pelo id ou pelo código curto que o cliente recebeu.

  • can_modify diz se o cliente ainda está no prazo do negócio para cancelar ou remarcar.

Parâmetros do caminho

NomeTipoObrigatórioDescrição
idstringsimId (uuid) ou código curto do agendamento, ex.: A1B2C3D4.

Exemplo de resposta (200)

json
{
  "success": true,
  "data": {
    "id": "0b6c2f0e-6f1a-4d59-9a53-6f0c1c7d2a11",
    "code": "A1B2C3D4",
    "status": "confirmed",
    "source": "api",
    "starts_at": "2026-11-20T17:00:00+00:00",
    "ends_at": "2026-11-20T17:30:00+00:00",
    "starts_at_local": "2026-11-20T14:00",
    "timezone": "America/Recife",
    "service": { "id": "5d2f…", "name": "Corte", "duration_minutes": 30 },
    "professional": { "id": "9a41…", "name": "Marina" },
    "customer": { "id": "c7e0…", "name": "Pedro Lima", "phone": "+5581999990000", "email": null },
    "notes": "Prefere máquina 2",
    "customer_confirmed_at": null,
    "reminder_sent_at": null,
    "can_modify": true,
    "created_at": "2026-11-13T15:02:11+00:00",
    "cancelled_at": null,
    "manage_url": "https://calendsk.app/manage#Jk3…",
    "quota": { "used": 4, "limit": 10 }
  }
}

Erros desta operação: NOT_FOUND.

POST/api/v1/bookings/{id}/reschedulepermissão: write

Remarcar agendamento

Muda o horário e, se quiser, o profissional. É o mesmo agendamento: o código não muda e o limite mensal não é consumido de novo.

  • Por padrão vale o prazo do negócio (cancel_window_hours). Fora dele: WINDOW_CLOSED.
  • Nunca remarca para o passado, nem com force.

Parâmetros do caminho

NomeTipoObrigatórioDescrição
idstringsimId (uuid) ou código curto do agendamento, ex.: A1B2C3D4.

Corpo (JSON)

NomeTipoObrigatórioDescrição
starts_atISO 8601simNovo início, como veio em /slots.
professional_iduuidnãoNovo profissional. Sem ele, mantém o atual.
forcebooleannãotrue ignora o prazo de cancelamento/remarcação do negócio. Padrão: false.

Exemplo de requisição

bash
curl -X POST "$CALENDSK_URL/api/v1/bookings/A1B2C3D4/reschedule" \
  -H "Authorization: Bearer $CALENDSK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "starts_at": "2026-11-21T13:00:00+00:00" }'

Exemplo de resposta (200)

json
{
  "success": true,
  "data": {
    "id": "0b6c2f0e-6f1a-4d59-9a53-6f0c1c7d2a11",
    "code": "A1B2C3D4",
    "status": "confirmed",
    "source": "api",
    "starts_at": "2026-11-20T17:00:00+00:00",
    "ends_at": "2026-11-20T17:30:00+00:00",
    "starts_at_local": "2026-11-20T14:00",
    "timezone": "America/Recife",
    "service": { "id": "5d2f…", "name": "Corte", "duration_minutes": 30 },
    "professional": { "id": "9a41…", "name": "Marina" },
    "customer": { "id": "c7e0…", "name": "Pedro Lima", "phone": "+5581999990000", "email": null },
    "notes": "Prefere máquina 2",
    "customer_confirmed_at": null,
    "reminder_sent_at": null,
    "can_modify": true,
    "created_at": "2026-11-13T15:02:11+00:00",
    "cancelled_at": null,
    "manage_url": "https://calendsk.app/manage#Jk3…",
    "quota": { "used": 4, "limit": 10 }
  }
}

Erros desta operação: VALIDATION_ERROR, SCOPE_REQUIRED, NOT_FOUND, SLOT_TAKEN, SLOT_IN_PAST, OUTSIDE_AVAILABILITY, PROFESSIONAL_UNAVAILABLE, WINDOW_CLOSED, ALREADY_CANCELLED.

POST/api/v1/bookings/{id}/cancelpermissão: write

Cancelar agendamento

Cancela e libera o horário. Não dá para desfazer: se o cliente mudar de ideia, crie um novo agendamento.

  • Por padrão vale o prazo do negócio (cancel_window_hours). Fora dele: WINDOW_CLOSED.
  • O corpo é opcional.
  • O cancelamento não devolve o agendamento ao limite mensal.

Parâmetros do caminho

NomeTipoObrigatórioDescrição
idstringsimId (uuid) ou código curto do agendamento, ex.: A1B2C3D4.

Corpo (JSON)

NomeTipoObrigatórioDescrição
forcebooleannãotrue ignora o prazo de cancelamento/remarcação do negócio. Padrão: false.

Exemplo de resposta (200)

json
{
  "success": true,
  "data": { "id": "0b6c…", "code": "A1B2C3D4", "status": "cancelled", "cancelled_at": "2026-11-14T12:30:00+00:00", "can_modify": false, "…": "…" }
}

Erros desta operação: VALIDATION_ERROR, SCOPE_REQUIRED, NOT_FOUND, WINDOW_CLOSED, ALREADY_CANCELLED.

POST/api/v1/bookings/{id}/confirmpermissão: write

Confirmar presença

Registra que o cliente confirmou que vai comparecer. O negócio vê a confirmação na agenda.

  • Repetir não muda nada.
  • Não vale para agendamento cancelado nem para horário que já passou.

Parâmetros do caminho

NomeTipoObrigatórioDescrição
idstringsimId (uuid) ou código curto do agendamento, ex.: A1B2C3D4.

Exemplo de resposta (200)

json
{
  "success": true,
  "data": { "id": "0b6c…", "code": "A1B2C3D4", "status": "confirmed", "customer_confirmed_at": "2026-11-19T18:40:00+00:00", "…": "…" }
}

Erros desta operação: SCOPE_REQUIRED, NOT_FOUND, SLOT_IN_PAST, ALREADY_CANCELLED.

OpenAPI e llms.txt

  • Especificação OpenAPI 3.1, pública e sem API key: /api/v1/openapi.json. Importe no Postman, no n8n ou gere um cliente a partir dela.
  • Resumo em texto simples para assistentes de IA: /llms.txt.
  • Visão geral para quem decide: Calendsk para bots.