API Enterprise d'audit d'appels : Endpoints et exemples
Référence pratique de l'API v1 d'audit : authentification avec clé d'organisation, création d'audits par URL ou téléversement, agents, équipes, scripts, analytics et webhooks HMAC.
Référence pratique de l'API v1 d'audit d'appels — le canal d'intégration du module d'audit avec votre PABX ou plateforme téléphonique. Nécessite une organisation avec un plan entreprise et une clé d'API d'organisation.
Authentification
Créez la clé dans /dashboard/organization/auditorias (OWNER/ADMIN ; jusqu'à 10 clés actives par organisation) et envoyez-la dans chaque requête :
Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG
- Le secret n'est affiché qu'une seule fois à la création — nous ne conservons que le hash.
- Chaque clé porte des scopes (
audits:write,audits:read,usage:read,analytics:read, entre autres) ; ce qui n'est pas accordé est refusé par défaut. - Rate limit : 60 requêtes/minute par clé.
Créer un audit
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"
}'
Règles :
- Accepte
audio_url(uniquementhttps, publique) ouupload_id(voir ci-dessous). webhook_urlest obligatoire — le résultat arrive par webhook, pas par polling.idempotency_keyest persistée de manière durable : les renvois avec la même clé ne créent pas d'audit en double.- Réponse immédiate :
202 { "audit_id": "...", "status": "queued" }.
Requêtes : GET /api/v1/audits (liste) et GET /api/v1/audits/{id} (détail).
Enregistrements sans URL publique
Pour un PABX qui n'expose pas d'URL, demandez une URL d'envoi temporaire :
curl -X POST https://www.vozparatexto.com.br/api/v1/uploads \
-H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG"
La réponse fournit un put_url valide pendant 1 heure : téléversez le fichier avec un PUT et utilisez le upload_id renvoyé lors de la création de l'audit.
Enregistrement de l'opération et métriques
| Endpoint | Fonction |
|---|---|
GET/POST /api/v1/agents | Agents (avec identifiant externe de votre système) |
GET/POST /api/v1/teams | Équipes |
GET/POST /api/v1/scripts + POST /api/v1/scripts/{id}/versions | Scripts et versions |
GET /api/v1/usage | Consommation de la période |
GET /api/v1/analytics/summary | Résumé analytique de l'opération |
GET /api/v1/analytics/agents/{external_id} | Métriques par agent |
Webhooks et garanties
- Livraisons signées avec HMAC-SHA256 (
X-VPT-Signature+X-VPT-Event) ; validez avant de traiter. - Timeout de 15 s par tentative, jusqu'à 6 tentatives avec backoff de 5 min à 24 h.
- Les jobs bloqués ne disparaissent pas : une file arrêtée plus de 10 min est remise en file ; un traitement bloqué plus de 60 min devient un échec avec webhook d'erreur. Chaque audio envoyé génère un callback final.
Plus de détails dans Webhooks et notifications.
FAQ
Puis-je utiliser ma clé API personnelle ici ?
Non — l'API d'audit utilise des clés d'organisation, créées par OWNER/ADMIN dans le panneau d'audits, avec leurs propres scopes.
J'ai envoyé le même appel deux fois. Va-t-il se dupliquer ?
Non, si vous avez utilisé le même idempotency_key — l'idempotence est durable en base.
Le put_url a expiré avant la fin du téléversement. Et maintenant ?
Demandez un nouveau put_url (valable 1 heure) et refaites l'envoi ; rien n'a encore été créé.
Comment restreindre ce que chaque intégration peut faire ?
Créez des clés séparées par système, chacune avec uniquement les scopes nécessaires (ex. : le dashboard interne avec seulement analytics:read), et révoquez-les individuellement si nécessaire.
Articles connexes
- [Audit d'appels](/help/auditoria-de-chamadas