Começando

Este guia explica como se integrar com a API Voki para construir aplicações que utilizam a plataforma de videochamadas.

Pré-requisitos

• Uma conta de tenant ativa na plataforma Voki
• Credenciais de um usuário com papel adequado (ver Autenticação)
• Cliente HTTP (curl, Postman, ou biblioteca na sua linguagem)

Base URL

Todos os endpoints da API utilizam a seguinte base URL:

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

Passo 1: Autenticação

O primeiro passo é obter um token JWT via login.

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seu-email@empresa.com",
    "password": "sua-senha",
    "tenant": "slug-do-tenant"
  }'

A resposta conterá os tokens de acesso:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "uuid",
      "name": "Seu Nome",
      "email": "seu-email@empresa.com",
      "role": "manager"
    }
  }
}

Passo 2: Fazendo Requisições Autenticadas

Inclua o token e o tenant em todas as requisições:

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

Passo 3: Explorando os Recursos

Com o token em mãos, você pode acessar todos os endpoints da API conforme o papel do seu usuário:

Papel	Acesso
attendant	Chamadas, clientes, tags, agendamentos
supervisor	Tudo de attendant + departamentos, setores, links, exportação
manager	Acesso total: usuários, empresa, billing, analytics

Exemplo: Listar Departamentos

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

Exemplo: Listar Chamadas Recentes

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"

Passo 4: Tempo Real com WebSocket

Para funcionalidades em tempo real (fila, presença, notificações), conecte via WebSocket:

import { Socket } from "phoenix"

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

// Monitorar fila de um departamento
const queueChannel = socket.channel("queue:department_uuid")
queueChannel.join()

queueChannel.on("customer_joined", (payload) => {
  console.log("Novo cliente na fila:", payload)
})

// Rastrear presença dos atendentes
const presenceChannel = socket.channel("presence:department_uuid")
presenceChannel.join()

Veja mais detalhes em WebSockets.

Formato de Respostas

Sucesso (objeto único)

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

Sucesso (lista paginada)

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

Erro de Validação (422)

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

Erro Genérico (401/403/404)

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

Paginação

Endpoints de listagem suportam paginação via query parameters:

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página (1-based)
page_size	integer	20	Itens por página (máx. 100)
sort_by	string	varia	Campo para ordenação
sort_order	string	asc	asc ou desc

Rate Limiting

Tipo	Limite
Endpoints de autenticação (/api/auth/*)	5 req/min
Endpoints públicos (widget, signup)	30 req/min
Endpoints autenticados	Sem limite explícito

Quando o rate limit é excedido, a API retorna 429 Too Many Requests.

SDKs e Bibliotecas

Atualmente não há SDKs oficiais. A API REST pode ser consumida diretamente com qualquer cliente HTTP. Para WebSocket, recomendamos a biblioteca oficial phoenix (JavaScript/TypeScript).

npm install phoenix

Próximos Passos

• Multi-Tenancy - Entenda a arquitetura multi-tenant
• Fornecedores - Configure fornecedores de serviço
• Autenticação - Referência completa de autenticação
• WebSockets - Comunicação em tempo real