API REST

9.1 Vision General

Voki ofrece una API REST completa para la integracion con sistemas externos. La API permite gestionar llamadas, clientes, departamentos, enlaces de acceso y mucho mas de forma programatica.

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

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

9.2 Autenticacion

Todas las solicitudes autenticadas deben incluir el token JWT en el encabezado:

Authorization: Bearer {access_token}

Para obtener un token:

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

Respuesta:

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

9.3 Endpoints Principales

Autenticacion

Metodo	Endpoint	Descripcion
POST	/api/auth/login	Inicio de sesion
POST	/api/auth/refresh	Renovar token
POST	/api/auth/mfa/verify	Verificar codigo MFA
POST	/api/auth/logout	Cerrar sesion
POST	/api/auth/forgot-password	Solicitar restablecimiento de contrasena
POST	/api/auth/reset-password	Restablecer contrasena

Usuarios

Metodo	Endpoint	Descripcion
GET	/api/v1/users/me	Datos del usuario autenticado
GET	/api/v1/users	Listar usuarios
GET	/api/v1/users/:id	Detalles de un usuario
POST	/api/v1/users	Crear usuario
PUT	/api/v1/users/:id	Actualizar usuario

Departamentos

Metodo	Endpoint	Descripcion
GET	/api/v1/departments	Listar departamentos
GET	/api/v1/departments/:id	Detalles de un departamento
POST	/api/v1/departments	Crear departamento
PUT	/api/v1/departments/:id	Actualizar departamento
DELETE	/api/v1/departments/:id	Eliminar departamento
POST	/api/v1/departments/:id/users	Agregar agente al departamento
DELETE	/api/v1/departments/:id/users/:user_id	Remover agente del departamento
GET	/api/v1/departments/:id/users	Listar agentes del departamento

Llamadas

Metodo	Endpoint	Descripcion
GET	/api/v1/calls	Listar llamadas
GET	/api/v1/calls/:id	Detalles de una llamada
POST	/api/v1/calls/:id/assign	Asignar llamada a un agente
POST	/api/v1/calls/:id/start	Iniciar llamada
POST	/api/v1/calls/:id/complete	Completar llamada
POST	/api/v1/calls/:call_id/upload	Subir archivo a la llamada
GET	/api/v1/calls/:call_id/recording	Obtener grabacion
POST	/api/v1/calls/:call_id/recording/upload	Subir grabacion

Clientes

Metodo	Endpoint	Descripcion
GET	/api/v1/customers	Listar clientes
GET	/api/v1/customers/:id	Detalles de un cliente
POST	/api/v1/customers	Crear cliente
PUT	/api/v1/customers/:id	Actualizar cliente
DELETE	/api/v1/customers/:id	Eliminar cliente
POST	/api/v1/customers/merge	Fusionar clientes duplicados

Enlaces de Acceso

Metodo	Endpoint	Descripcion
GET	/api/v1/access-links	Listar enlaces
GET	/api/v1/access-links/:id	Detalles de un enlace
POST	/api/v1/access-links	Crear enlace
POST	/api/v1/access-links/batch	Crear enlaces por lotes
POST	/api/v1/access-links/:id/cancel	Cancelar enlace

Citas

Metodo	Endpoint	Descripcion
GET	/api/v1/appointments	Listar citas
GET	/api/v1/appointments/:id	Detalles de una cita
POST	/api/v1/appointments	Crear cita
PUT	/api/v1/appointments/:id	Actualizar cita
GET	/api/v1/appointments/conflicts	Verificar conflictos de horario
POST	/api/v1/appointments/:id/confirm	Confirmar cita
POST	/api/v1/appointments/:id/cancel	Cancelar cita
POST	/api/v1/appointments/:id/complete	Marcar como completada
POST	/api/v1/appointments/:id/no-show	Marcar como no-show

Tags

Metodo	Endpoint	Descripcion
GET	/api/v1/tags	Listar tags
GET	/api/v1/tags/tree	Arbol de tags
POST	/api/v1/tags	Crear tag
PUT	/api/v1/tags/:id	Actualizar tag
DELETE	/api/v1/tags/:id	Eliminar tag
GET	/api/v1/calls/:call_id/tags	Tags de una llamada
POST	/api/v1/calls/:call_id/tags	Aplicar tag a una llamada
DELETE	/api/v1/calls/:call_id/tags/:tag_id	Remover tag de una llamada

Analytics

Metodo	Endpoint	Descripcion
GET	/api/v1/analytics/overview	Vision general de metricas
GET	/api/v1/analytics/hourly	Metricas por hora
GET	/api/v1/analytics/agents	Metricas por agente
GET	/api/v1/analytics/trends	Tendencias
POST	/api/v1/analytics/refresh-views	Actualizar materialized views

Webhooks

Metodo	Endpoint	Descripcion
GET	/api/v1/webhooks	Listar webhooks
GET	/api/v1/webhooks/:id	Detalles de un webhook
POST	/api/v1/webhooks	Crear webhook
PUT	/api/v1/webhooks/:id	Actualizar webhook
DELETE	/api/v1/webhooks/:id	Eliminar webhook
GET	/api/v1/webhooks/:id/deliveries	Historial de entregas
POST	/api/v1/webhooks/:id/test	Probar webhook

Exportacion

Metodo	Endpoint	Descripcion
GET	/api/v1/export/calls.csv	Exportar llamadas en CSV
GET	/api/v1/export/customers.csv	Exportar clientes en CSV
GET	/api/v1/export/links.csv	Exportar enlaces en CSV

Acceso Publico (Clientes)

Metodo	Endpoint	Descripcion
GET	/api/v1/call/:token/validate	Validar token de acceso
POST	/api/v1/call/:token/join	Entrar en la cola de atencion
GET	/api/v1/call/status/:call_id	Estado de la llamada
POST	/api/v1/call/evaluate/:call_id	Enviar evaluacion posatencion

9.4 Limitacion de Solicitudes (Rate Limiting)

Tipo de Endpoint	Limite	Intervalo
Autenticacion	5 solicitudes	Por minuto
API publica	30 solicitudes	Por minuto

Al exceder el limite:

• Codigo HTTP: 429 Too Many Requests
• Encabezado Retry-After: segundos hasta poder intentar nuevamente

9.5 Codigos de Respuesta

Codigo	Significado
200	Exito
201	Recurso creado con exito
400	Solicitud invalida (parametros faltantes o incorrectos)
401	No autenticado (token ausente o expirado)
403	Sin permiso (rol insuficiente o limite de plan)
404	Recurso no encontrado
422	Error de validacion (datos invalidos)
429	Limite de solicitudes excedido
500	Error interno del servidor

9.6 Documentacion Interactiva

La documentacion completa de la API con ejemplos de solicitud y respuesta esta disponible en:

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

---