Primeros Pasos

Esta guía explica cómo integrarse con la API Voki para construir aplicaciones que utilicen la plataforma de videollamadas.

Requisitos Previos

• Una cuenta de tenant activa en la plataforma Voki
• Credenciales de un usuario con el rol adecuado (ver Autenticación)
• Cliente HTTP (curl, Postman o biblioteca en su lenguaje)

Base URL

Todos los endpoints de la API utilizan la siguiente base URL:

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

Paso 1: Autenticación

El primer paso es obtener un token JWT mediante login.

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "su-email@empresa.com",
    "password": "su-contraseña",
    "tenant": "slug-del-tenant"
  }'

La respuesta contendrá los tokens de acceso:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid",
      "name": "Su Nombre",
      "email": "su-email@empresa.com",
      "role": "manager"
    }
  }
}

Paso 2: Realizando Solicitudes Autenticadas

Incluya el token y el tenant en todas las solicitudes:

curl -X GET https://voki.avanter.com.br/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Tenant: slug-del-tenant"

Paso 3: Explorando los Recursos

Con el token en mano, puede acceder a todos los endpoints de la API según el rol de su usuario:

Rol	Acceso
attendant	Llamadas, clientes, tags, citas
supervisor	Todo de attendant + departamentos, sectores, enlaces, exportación
manager	Acceso total: usuarios, empresa, facturación, analytics

Ejemplo: Listar Departamentos

curl -X GET https://voki.avanter.com.br/api/v1/departments \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Ejemplo: Listar Llamadas Recientes

curl -X GET "https://voki.avanter.com.br/api/v1/calls?page=1&page_size=5&sort_order=desc" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Paso 4: Tiempo Real con WebSocket

Para funcionalidades en tiempo real (cola, presencia, notificaciones), conéctese vía WebSocket:

import { Socket } from "phoenix"

const socket = new Socket("wss://voki.avanter.com.br/socket/websocket", {
  params: { token: accessToken }
})
socket.connect()

// Monitorear cola de un departamento
const queueChannel = socket.channel("queue:department_uuid")
queueChannel.join()

queueChannel.on("customer_joined", (payload) => {
  console.log("Nuevo cliente en la cola:", payload)
})

// Rastrear presencia de los agentes
const presenceChannel = socket.channel("presence:department_uuid")
presenceChannel.join()

Vea más detalles en WebSockets.

Formato de Respuestas

Éxito (objeto único)

{
  "data": {
    "id": "uuid",
    "campo": "valor"
  }
}

Éxito (lista paginada)

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_pages": 5,
    "total_count": 100
  }
}

Error de Validación (422)

{
  "errors": {
    "email": ["não pode ficar em branco"],
    "password": ["deve ter pelo menos 8 caracteres"]
  }
}

Error Genérico (401/403/404)

{
  "errors": {
    "detail": "Não autorizado"
  }
}

Paginación

Los endpoints de listado soportan paginación mediante query parameters:

Parámetro	Tipo	Predeterminado	Descripción
page	integer	1	Número de página (basado en 1)
page_size	integer	20	Elementos por página (máx. 100)
sort_by	string	varía	Campo para ordenamiento
sort_order	string	asc	asc o desc

Rate Limiting

Tipo	Límite
Endpoints de autenticación (/api/auth/*)	5 sol/min
Endpoints públicos (widget, signup)	30 sol/min
Endpoints autenticados	Sin límite explícito

Cuando se excede el rate limit, la API retorna 429 Too Many Requests.

SDKs y Bibliotecas

Actualmente no existen SDKs oficiales. La API REST puede consumirse directamente con cualquier cliente HTTP. Para WebSocket, recomendamos la biblioteca oficial phoenix (JavaScript/TypeScript).

npm install phoenix

Próximos Pasos

• Multi-Tenancy - Entienda la arquitectura multi-tenant
• Proveedores - Configure proveedores de servicio
• Autenticación - Referencia completa de autenticación
• WebSockets - Comunicación en tiempo real