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"
}
}
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
| Nome | Tipo | Obrigatório | Descrição |
|---|
| service_id | uuid | sim | Serviço, como veio em /business. |
| date | AAAA-MM-DD | não | Primeiro dia, no fuso do negócio. Padrão: hoje. |
| days | integer | não | Quantos dias a partir de date (1 a 14). Padrão: 1. |
| professional_id | uuid | não | Só 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.
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
| Nome | Tipo | Obrigatório | Descrição |
|---|
| Idempotency-Key | string | não | 8 a 100 caracteres (letras, números, _ . : -). A mesma chave devolve o mesmo agendamento, sem criar outro. |
Corpo (JSON)
| Nome | Tipo | Obrigatório | Descrição |
|---|
| service_id | uuid | sim | Serviço, como veio em /business. |
| starts_at | ISO 8601 | sim | Início com fuso, como veio em /slots. Ex.: 2026-11-20T17:00:00+00:00. |
| customer_name | string | sim | Nome do cliente (2 a 80 caracteres). |
| customer_phone | string | não | Celular com DDD. Número brasileiro sem +55 é aceito; fica guardado como +55DDDNÚMERO. |
| customer_email | string | não | E-mail do cliente. |
| professional_id | uuid | não | Profissional escolhido pelo cliente. |
| notes | string | não | Observação para o negócio (até 500 caracteres). O cliente não vê. |
| idempotency_key | string | não | Alternativa 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
| Nome | Tipo | Obrigatório | Descrição |
|---|
| customer_phone | string | não | Celular do cliente com DDD. |
| from | ISO 8601 | não | Início do período, inclusive. |
| to | ISO 8601 | não | Fim do período, exclusivo. |
| status | string | não | confirmed ou cancelled. Sem ele, os dois. |
| professional_id | uuid | não | Só agendamentos deste profissional. |
| limit | integer | não | Itens por página. Padrão 50, máximo 100. |
| offset | integer | não | Quantos 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
| Nome | Tipo | Obrigatório | Descrição |
|---|
| id | string | sim | Id (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
| Nome | Tipo | Obrigatório | Descrição |
|---|
| id | string | sim | Id (uuid) ou código curto do agendamento, ex.: A1B2C3D4. |
Corpo (JSON)
| Nome | Tipo | Obrigatório | Descrição |
|---|
| starts_at | ISO 8601 | sim | Novo início, como veio em /slots. |
| professional_id | uuid | não | Novo profissional. Sem ele, mantém o atual. |
| force | boolean | não | true 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
| Nome | Tipo | Obrigatório | Descrição |
|---|
| id | string | sim | Id (uuid) ou código curto do agendamento, ex.: A1B2C3D4. |
Corpo (JSON)
| Nome | Tipo | Obrigatório | Descrição |
|---|
| force | boolean | não | true 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
| Nome | Tipo | Obrigatório | Descrição |
|---|
| id | string | sim | Id (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.