API Enterprise de Auditoria de Chamadas: Endpoints e Exemplos
Referência prática da API v1 de auditoria: autenticação com chave da organização, criar auditorias por URL ou upload, agentes, equipas, guiões, analytics e webhooks HMAC.
Referência prática da API v1 de auditoria de chamadas — o canal de integração do módulo de auditoria com o seu PABX ou plataforma de telefonia. Requer organização com plano empresarial e uma chave de API da organização.
Autenticação
Crie a chave em /dashboard/organization/auditorias (OWNER/ADMIN; até 10 chaves ativas por organização) e envie-a em todos os pedidos:
Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG
- O segredo é exibido uma única vez na criação — guardamos apenas o hash.
- Cada chave carrega escopos (
audits:write,audits:read,usage:read,analytics:read, entre outros); o que não foi concedido é negado por padrão. - Limite de pedidos: 60 pedidos/minuto por chave.
Criar uma auditoria
curl -X POST https://www.vozparatexto.com.br/api/v1/audits \
-H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://pbx.suaempresa.com/gravacoes/8841.mp3",
"webhook_url": "https://api.suaempresa.com/hooks/auditorias",
"idempotency_key": "chamada-8841",
"agent_external_id": "maria.souza",
"team": "vendas-sp"
}'
Regras:
- Aceita
audio_url(apenashttps, pública) ouupload_id(ver abaixo). webhook_urlé obrigatório — o resultado chega por webhook, não por polling.idempotency_keyé persistida de forma durável: reenvios com a mesma chave não criam auditoria duplicada.- Resposta imediata:
202 { "audit_id": "...", "status": "queued" }.
Consultas: GET /api/v1/audits (lista) e GET /api/v1/audits/{id} (detalhe).
Gravações sem URL pública
Para PABX que não exponha uma URL, peça uma URL de envio temporária:
curl -X POST https://www.vozparatexto.com.br/api/v1/uploads \
-H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG"
A resposta devolve um put_url válido por 1 hora: carregue o ficheiro com um PUT e utilize o upload_id devolvido ao criar a auditoria.
Registo da operação e métricas
| Endpoint | Função |
|---|---|
GET/POST /api/v1/agents | Agentes (com identificador externo do seu sistema) |
GET/POST /api/v1/teams | Equipas |
GET/POST /api/v1/scripts + POST /api/v1/scripts/{id}/versions | Guiões e versões |
GET /api/v1/usage | Consumo do período |
GET /api/v1/analytics/summary | Resumo analítico da operação |
GET /api/v1/analytics/agents/{external_id} | Métricas por agente |
Webhooks e garantias
- Entregas assinadas com HMAC-SHA256 (
X-VPT-Signature+X-VPT-Event); valide antes de processar. - Timeout de 15 s por tentativa, até 6 tentativas com backoff de 5 min a 24 h.
- Tarefas bloqueadas não desaparecem: fila parada >10 min é reenfileirada; processamento bloqueado >60 min torna-se falha com webhook de erro. Todo o áudio enviado gera um callback final.
Mais detalhes em Webhooks e notificações.
FAQ
Posso usar a minha chave pessoal de API aqui?
Não — a API de auditoria utiliza chaves da organização, criadas por OWNER/ADMIN no painel de auditorias, com escopos próprios.
Enviei a mesma chamada duas vezes. Vai duplicar?
Não, se utilizou o mesmo idempotency_key — a idempotência é durável na base de dados.
O put_url expirou antes de o upload terminar. E agora?
Peça um novo put_url (validade de 1 hora) e refaça o envio; nada foi criado ainda.
Como restrinjo o que cada integração pode fazer?
Crie chaves separadas por sistema, cada uma apenas com os escopos necessários (ex.: o dashboard interno apenas com analytics:read), e revogue-as individualmente quando necessário.
Artigos relacionados
Não resolveu? Abra um ticket — a nossa equipa responde rapidamente.