API Enterprise de Auditoría de Llamadas: Endpoints y Ejemplos
Referencia práctica de la API v1 de auditoría: autenticación con clave de la organización, crear auditorías por URL o subida, agentes, equipos, guiones, analíticas y webhooks HMAC.
Referencia práctica de la API v1 de auditoría de llamadas: el canal de integración del módulo de auditoría con tu PABX o plataforma de telefonía. Requiere organización con plan empresarial y una clave de API de la organización.
Autenticación
Crea la clave en /dashboard/organization/auditorias (OWNER/ADMIN; hasta 10 claves activas por organización) y envíala en cada solicitud:
Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG
- El secreto se muestra una única vez en la creación: solo guardamos el hash.
- Cada clave lleva alcances (
audits:write,audits:read,usage:read,analytics:read, entre otros); lo que no se ha concedido se deniega por defecto. - Límite de peticiones: 60 solicitudes/minuto por clave.
Crear una auditoría
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"
}'
Reglas:
- Acepta
audio_url(solohttps, pública) oupload_id(ver abajo). webhook_urles obligatorio: el resultado llega por webhook, no por polling.idempotency_keyse conserva de forma duradera: los reenvíos con la misma clave no crean una auditoría duplicada.- Respuesta inmediata:
202 { "audit_id": "...", "status": "queued" }.
Consultas: GET /api/v1/audits (lista) y GET /api/v1/audits/{id} (detalle).
Grabaciones sin URL pública
Para PABX que no expone una URL, pide una URL de envío temporal:
curl -X POST https://www.vozparatexto.com.br/api/v1/uploads \
-H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG"
La respuesta incluye un put_url válido por 1 hora: sube el archivo con un PUT y usa el upload_id devuelto al crear la auditoría.
Registro de la operación y métricas
| Endpoint | Función |
|---|---|
GET/POST /api/v1/agents | Agentes (con identificador externo de tu sistema) |
GET/POST /api/v1/teams | Equipos |
GET/POST /api/v1/scripts + POST /api/v1/scripts/{id}/versions | Guiones y versiones |
GET /api/v1/usage | Consumo del período |
GET /api/v1/analytics/summary | Resumen analítico de la operación |
GET /api/v1/analytics/agents/{external_id} | Métricas por agente |
Webhooks y garantías
- Entregas firmadas con HMAC-SHA256 (
X-VPT-Signature+X-VPT-Event); valida antes de procesar. - Timeout de 15 s por intento, hasta 6 intentos con backoff de 5 min a 24 h.
- Los trabajos atascados no desaparecen: una cola detenida >10 min se vuelve a encolar; el procesamiento atascado >60 min se convierte en fallo con webhook de error. Todo audio enviado genera un callback final.
Más detalles en Webhooks y notificaciones.
FAQ
¿Puedo usar mi clave personal de API aquí?
No: la API de auditoría usa claves de la organización, creadas por OWNER/ADMIN en el panel de auditorías, con alcances propios.
Envié la misma llamada dos veces. ¿Se duplicará?
No, si usaste el mismo idempotency_key: la idempotencia es duradera en la base de datos.
El put_url caducó antes de que terminara la subida. ¿Y ahora?
Pide un nuevo put_url (validez de 1 hora) y vuelve a hacer el envío; aún no se ha creado nada.
¿Cómo restrinjo lo que puede hacer cada integración?
Crea claves separadas por sistema, cada una solo con los alcances necesarios (p. ej., el panel interno solo con analytics:read), y revócalas individualmente cuando sea necesario.
Artículos relacionados
¿No se resolvió? Abre un ticket: nuestro equipo responde rápido.