API REST

9.1 Visao Geral

O Voki oferece uma API REST completa para integracao com sistemas externos. A API permite gerenciar chamadas, clientes, departamentos, links de acesso e muito mais de forma programatica.

URL base: https://voki.avanter.com.br/api

Formato: JSON (Content-Type: application/json)

9.2 Autenticacao

Todas as requisicoes autenticadas devem incluir o token JWT no header:

Authorization: Bearer {access_token}

Para obter um token:

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@empresa.com.br",
    "password": "suaSenha",
    "tenant": "nome-da-empresa"
  }'

Resposta:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "user": {
    "id": "uuid",
    "name": "Nome do Usuario",
    "email": "usuario@empresa.com.br",
    "role": "manager"
  }
}

9.3 Endpoints Principais

Autenticacao

Metodo	Endpoint	Descricao
POST	/api/auth/login	Login
POST	/api/auth/refresh	Renovar token
POST	/api/auth/mfa/verify	Verificar codigo MFA
POST	/api/auth/logout	Logout
POST	/api/auth/forgot-password	Solicitar reset de senha
POST	/api/auth/reset-password	Redefinir senha

Usuarios

Metodo	Endpoint	Descricao
GET	/api/v1/users/me	Dados do usuario autenticado
GET	/api/v1/users	Listar usuarios
GET	/api/v1/users/:id	Detalhes de um usuario
POST	/api/v1/users	Criar usuario
PUT	/api/v1/users/:id	Atualizar usuario

Departamentos

Metodo	Endpoint	Descricao
GET	/api/v1/departments	Listar departamentos
GET	/api/v1/departments/:id	Detalhes de um departamento
POST	/api/v1/departments	Criar departamento
PUT	/api/v1/departments/:id	Atualizar departamento
DELETE	/api/v1/departments/:id	Excluir departamento
POST	/api/v1/departments/:id/users	Adicionar atendente ao departamento
DELETE	/api/v1/departments/:id/users/:user_id	Remover atendente do departamento
GET	/api/v1/departments/:id/users	Listar atendentes do departamento

Chamadas

Metodo	Endpoint	Descricao
GET	/api/v1/calls	Listar chamadas
GET	/api/v1/calls/:id	Detalhes de uma chamada
POST	/api/v1/calls/:id/assign	Atribuir chamada a um atendente
POST	/api/v1/calls/:id/start	Iniciar chamada
POST	/api/v1/calls/:id/complete	Completar chamada
POST	/api/v1/calls/:call_id/upload	Upload de arquivo na chamada
GET	/api/v1/calls/:call_id/recording	Obter gravacao
POST	/api/v1/calls/:call_id/recording/upload	Upload de gravacao

Clientes

Metodo	Endpoint	Descricao
GET	/api/v1/customers	Listar clientes
GET	/api/v1/customers/:id	Detalhes de um cliente
POST	/api/v1/customers	Criar cliente
PUT	/api/v1/customers/:id	Atualizar cliente
DELETE	/api/v1/customers/:id	Excluir cliente
POST	/api/v1/customers/merge	Mesclar clientes duplicados

Links de Acesso

Metodo	Endpoint	Descricao
GET	/api/v1/access-links	Listar links
GET	/api/v1/access-links/:id	Detalhes de um link
POST	/api/v1/access-links	Criar link
POST	/api/v1/access-links/batch	Criar links em lote
POST	/api/v1/access-links/:id/cancel	Cancelar link

Agendamentos

Metodo	Endpoint	Descricao
GET	/api/v1/appointments	Listar agendamentos
GET	/api/v1/appointments/:id	Detalhes de um agendamento
POST	/api/v1/appointments	Criar agendamento
PUT	/api/v1/appointments/:id	Atualizar agendamento
GET	/api/v1/appointments/conflicts	Verificar conflitos de horario
POST	/api/v1/appointments/:id/confirm	Confirmar agendamento
POST	/api/v1/appointments/:id/cancel	Cancelar agendamento
POST	/api/v1/appointments/:id/complete	Marcar como completado
POST	/api/v1/appointments/:id/no-show	Marcar como no-show

Tags

Metodo	Endpoint	Descricao
GET	/api/v1/tags	Listar tags
GET	/api/v1/tags/tree	Arvore de tags
POST	/api/v1/tags	Criar tag
PUT	/api/v1/tags/:id	Atualizar tag
DELETE	/api/v1/tags/:id	Excluir tag
GET	/api/v1/calls/:call_id/tags	Tags de uma chamada
POST	/api/v1/calls/:call_id/tags	Aplicar tag a chamada
DELETE	/api/v1/calls/:call_id/tags/:tag_id	Remover tag da chamada

Analytics

Metodo	Endpoint	Descricao
GET	/api/v1/analytics/overview	Visao geral de metricas
GET	/api/v1/analytics/hourly	Metricas por hora
GET	/api/v1/analytics/agents	Metricas por atendente
GET	/api/v1/analytics/trends	Tendencias
POST	/api/v1/analytics/refresh-views	Atualizar materialized views

Webhooks

Metodo	Endpoint	Descricao
GET	/api/v1/webhooks	Listar webhooks
GET	/api/v1/webhooks/:id	Detalhes de um webhook
POST	/api/v1/webhooks	Criar webhook
PUT	/api/v1/webhooks/:id	Atualizar webhook
DELETE	/api/v1/webhooks/:id	Excluir webhook
GET	/api/v1/webhooks/:id/deliveries	Historico de entregas
POST	/api/v1/webhooks/:id/test	Testar webhook

Exportacao

Metodo	Endpoint	Descricao
GET	/api/v1/export/calls.csv	Exportar chamadas em CSV
GET	/api/v1/export/customers.csv	Exportar clientes em CSV
GET	/api/v1/export/links.csv	Exportar links em CSV

Acesso Publico (Clientes)

Metodo	Endpoint	Descricao
GET	/api/v1/call/:token/validate	Validar token de acesso
POST	/api/v1/call/:token/join	Entrar na fila de atendimento
GET	/api/v1/call/status/:call_id	Status da chamada
POST	/api/v1/call/evaluate/:call_id	Enviar avaliacao pos-atendimento

9.4 Rate Limiting

Tipo de Endpoint	Limite	Intervalo
Autenticacao	5 requisicoes	Por minuto
API publica	30 requisicoes	Por minuto

Ao exceder o limite:

• Status HTTP: 429 Too Many Requests
• Header Retry-After: segundos ate poder tentar novamente

9.5 Codigos de Resposta

Codigo	Significado
200	Sucesso
201	Recurso criado com sucesso
400	Requisicao invalida (parametros faltando ou incorretos)
401	Nao autenticado (token ausente ou expirado)
403	Sem permissao (role insuficiente ou limite de plano)
404	Recurso nao encontrado
422	Erro de validacao (dados invalidos)
429	Rate limit excedido
500	Erro interno do servidor

9.6 Documentacao Interativa

A documentacao completa da API com exemplos de requisicao e resposta esta disponivel em:

https://voki.avanter.com.br/docs

---