Agendamentos (appointments)

Agendamentos ligam um cliente a um horário de uma agenda. O módulo é agendamentos; os escopos são appointments:read e appointments:write.

Método	Endpoint	Operação
GET	/v1/appointments	Listar
GET	/v1/appointments/{id}	Consultar
POST	/v1/appointments	Criar
PATCH	/v1/appointments/{id}	Editar ou remarcar
POST	/v1/appointments/{id}/cancel	Cancelar com motivo
DELETE	/v1/appointments/{id}	Desativar

Criar

Consulte primeiro a agenda e seus horários. O corpo mínimo de criação tem os campos abaixo; substitua os UUIDs pelos seus registros.

{
  "customer_id": "4d2f8a91-6b3e-47c0-9d55-e1a2b3c4d5e6",
  "calendar_id": "f0882c42-04f9-43e7-baf5-982f99377643",
  "appointment_date": "2026-10-20",
  "start_time": "09:00",
  "end_time": "10:00"
}

Também é possível informar tipo de evento, responsável, modalidade (in_person ou online), observações e tag_ids. Todos os vínculos devem ser da mesma equipe. Use Idempotency-Key para preservar a operação em novas tentativas.

Remarcar e cancelar

Envie data e horários novos em PATCH. A verificação de disponibilidade usa a mesma regra da criação e desconsidera a ocupação do próprio registro. Para cancelar, envie cancellation_reason ao endpoint /cancel. Uma reativação (is_active: true) verifica novamente a capacidade.

A escrita do agendamento e de suas tags é transacional. Duas integrações concorrentes não podem ultrapassar a capacidade configurada. Se outra gravação ocupar o horário antes da sua, a API responde 409 appointment_conflict. Consulte novamente os horários e escolha outra vaga.

Consultar

As listas usam limit (1 a 100, padrão 20), cursor, fields e filtros por appointment_date, status, customer_id, is_active, calendar_id, event_type_id e assigned_to_user_id. Ordene por created_at, updated_at ou appointment_date; o padrão é -created_at.

Veja os schemas completos na Referência e o formato dos Erros.