Agendamentos

Gerenciamento de agendamentos de chamadas. Permite agendar videochamadas com data e hora definidas. Requer papel de attendant ou superior.

Endpoints

Método	Endpoint	Descrição	Role Mínimo
GET	/api/v1/appointments	Listar agendamentos	attendant
POST	/api/v1/appointments	Criar agendamento	attendant
GET	/api/v1/appointments/:id	Buscar agendamento	attendant
PUT	/api/v1/appointments/:id	Atualizar agendamento	attendant
GET	/api/v1/appointments/conflicts	Verificar conflitos	attendant
POST	/api/v1/appointments/:id/confirm	Confirmar agendamento	attendant
POST	/api/v1/appointments/:id/cancel	Cancelar agendamento	attendant
POST	/api/v1/appointments/:id/complete	Marcar como concluído	attendant
POST	/api/v1/appointments/:id/no-show	Marcar como no-show	attendant

---

Listar Agendamentos

GET /api/v1/appointments

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página
page_size	integer	20	Itens por página
sort_by	string	scheduled_at	Campo para ordenação
sort_order	string	asc	Direção da ordenação
status	string	-	Filtro: scheduled, confirmed, completed, cancelled, no_show
date_from	string	-	Data início (ISO 8601)
date_to	string	-	Data fim (ISO 8601)
user_id	uuid	-	Filtro por atendente
department_id	uuid	-	Filtro por departamento

Exemplo de Request

curl -X GET "https://voki.avanter.com.br/api/v1/appointments?date_from=2026-02-18&status=scheduled" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": [
    {
      "id": "4c5d6e7f-8a9b-0123-defg-456789012345",
      "title": "Consulta de acompanhamento",
      "description": "Retorno sobre tratamento iniciado em janeiro",
      "status": "scheduled",
      "scheduled_at": "2026-02-20T10:00:00Z",
      "duration_minutes": 30,
      "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "department_name": "Suporte Técnico",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_name": "João Silva",
      "customer_id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
      "customer_name": "Carlos Ferreira",
      "customer_email": "carlos@email.com",
      "customer_phone": "+5511999998888",
      "notes": null,
      "inserted_at": "2026-02-15T10:00:00Z",
      "updated_at": "2026-02-15T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

---

Criar Agendamento

POST /api/v1/appointments

Request Body

Campo	Tipo	Obrigatório	Descrição
title	string	Sim	Título do agendamento
description	string	Não	Descrição detalhada
scheduled_at	string	Sim	Data e hora (ISO 8601, futuro)
duration_minutes	integer	Não	Duração em minutos (padrão: 30)
department_id	uuid	Sim	ID do departamento
user_id	uuid	Não	ID do atendente (padrão: usuário autenticado)
customer_id	uuid	Não	ID do cliente existente
customer_name	string	Sim*	Nome do cliente (se customer_id não fornecido)
customer_email	string	Não	Email do cliente
customer_phone	string	Não	Telefone do cliente
notes	string	Não	Observações

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/appointments \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment": {
      "title": "Reunião de apresentação",
      "scheduled_at": "2026-02-25T14:00:00Z",
      "duration_minutes": 45,
      "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "customer_name": "Roberto Lima",
      "customer_email": "roberto@email.com",
      "customer_phone": "+5511966665544"
    }
  }'

Resposta de Sucesso (201)

{
  "data": {
    "id": "5d6e7f8a-9b0c-1234-efgh-567890123456",
    "title": "Reunião de apresentação",
    "status": "scheduled",
    "scheduled_at": "2026-02-25T14:00:00Z",
    "duration_minutes": 45,
    "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
    "department_name": "Suporte Técnico",
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_name": "João Silva",
    "customer_id": "6e7f8a9b-0c1d-2345-fghi-678901234567",
    "customer_name": "Roberto Lima",
    "customer_email": "roberto@email.com",
    "customer_phone": "+5511966665544",
    "inserted_at": "2026-02-18T16:00:00Z",
    "updated_at": "2026-02-18T16:00:00Z"
  }
}

---

Verificar Conflitos

Verifica se há conflitos de horário para um atendente.

GET /api/v1/appointments/conflicts

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
user_id	uuid	Sim	ID do atendente
scheduled_at	string	Sim	Data e hora a verificar
duration_minutes	integer	Não	Duração em minutos (padrão: 30)
exclude_id	uuid	Não	ID de agendamento a excluir da verificação

Exemplo de Request

curl -X GET "https://voki.avanter.com.br/api/v1/appointments/conflicts?user_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&scheduled_at=2026-02-25T14:00:00Z&duration_minutes=45" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Resposta de Sucesso (200)

{
  "data": {
    "has_conflicts": false,
    "conflicts": []
  }
}

---

Confirmar Agendamento

POST /api/v1/appointments/:id/confirm

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/appointments/4c5d6e7f-8a9b-0123-defg-456789012345/confirm \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Cancelar Agendamento

POST /api/v1/appointments/:id/cancel

Request Body (opcional)

Campo	Tipo	Obrigatório	Descrição
reason	string	Não	Motivo do cancelamento

Exemplo de Request

curl -X POST https://voki.avanter.com.br/api/v1/appointments/4c5d6e7f-8a9b-0123-defg-456789012345/cancel \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Cliente solicitou reagendamento"
  }'

---

Marcar como Concluído

POST /api/v1/appointments/:id/complete

---

Marcar como No-Show

POST /api/v1/appointments/:id/no-show

---

Status do Agendamento

Status	Descrição
scheduled	Agendado, aguardando confirmação
confirmed	Confirmado pelo atendente ou cliente
completed	Chamada realizada
cancelled	Cancelado
no_show	Cliente não compareceu