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, times, roteiros, 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 em toda requisição:
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. - Rate limit: 60 requisições/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(somentehttps, pública) ouupload_id(veja 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 expõe 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 traz um put_url válido por 1 hora: suba o arquivo com um PUT e use o upload_id retornado ao criar a auditoria.
Cadastro 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 | Times |
GET/POST /api/v1/scripts + POST /api/v1/scripts/{id}/versions | Roteiros 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.
- Jobs travados não somem: fila parada >10 min é reenfileirada; processamento travado >60 min vira falha com webhook de erro. Todo áudio enviado gera um callback final.
Mais detalhes em Webhooks e notificações.
FAQ
Posso usar minha chave pessoal de API aqui?
Não — a API de auditoria usa 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 você usou o mesmo idempotency_key — a idempotência é durável no banco.
O put_url expirou antes do 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 só com os escopos necessários (ex.: o dashboard interno só com analytics:read), e revogue individualmente quando preciso.
Artigos relacionados
Não resolveu? Abra um ticket — nossa equipe responde rápido.