API Enterprise di Audit delle Chiamate: Endpoint ed Esempi
Riferimento pratico dell'API v1 di audit: autenticazione con chiave dell'organizzazione, creazione di audit tramite URL o upload, agenti, team, copioni, analytics e webhook HMAC.
Riferimento pratico dell'API v1 di audit delle chiamate — il canale di integrazione del modulo di audit con il tuo PABX o piattaforma telefonica. Richiede un'organizzazione con piano aziendale e una chiave API dell'organizzazione.
Autenticazione
Crea la chiave in /dashboard/organization/auditorias (OWNER/ADMIN; fino a 10 chiavi attive per organizzazione) e inviala in ogni richiesta:
Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG
- Il segreto viene mostrato una sola volta alla creazione: conserviamo solo l'hash.
- Ogni chiave include scope (
audits:write,audits:read,usage:read,analytics:read, ecc.); ciò che non è concesso viene negato di default. - Rate limit: 60 richieste/minuto per chiave.
Creare 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"
}'
Regole:
- Accetta
audio_url(solohttps, pubblica) oppureupload_id(vedi sotto). webhook_urlè obbligatorio — il risultato arriva tramite webhook, non tramite polling.idempotency_keyviene conservata in modo durevole: invii ripetuti con la stessa chiave non creano un audit duplicato.- Risposta immediata:
202 { "audit_id": "...", "status": "queued" }.
Per le query: GET /api/v1/audits (lista) e GET /api/v1/audits/{id} (dettaglio).
Registrazioni senza URL pubblico
Per i PABX che non espongono un URL, richiedi un URL di upload temporaneo:
curl -X POST https://www.vozparatexto.com.br/api/v1/uploads \
-H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG"
La risposta contiene un put_url valido per 1 ora: carica il file con una richiesta PUT e usa l'upload_id restituito quando crei l'audit.
Registrazione di agenti, team e metriche
| Endpoint | Funzione |
|---|---|
GET/POST /api/v1/agents | Agenti (con identificatore esterno del tuo sistema) |
GET/POST /api/v1/teams | Team |
GET/POST /api/v1/scripts + POST /api/v1/scripts/{id}/versions | Copioni e versioni |
GET /api/v1/usage | Consumo del periodo |
GET /api/v1/analytics/summary | Riepilogo analitico dell'operazione |
GET /api/v1/analytics/agents/{external_id} | Metriche per agente |
Webhook e garanzie
- Consegnano firme HMAC-SHA256 (
X-VPT-Signature+X-VPT-Event); valida prima di elaborare. - Timeout di 15 secondi per tentativo, fino a 6 tentativi con backoff da 5 minuti a 24 ore.
- I job bloccati non spariscono: una coda ferma per più di 10 minuti viene rimessa in coda; un'elaborazione bloccata per più di 60 minuti diventa un errore con webhook di errore. Ogni audio inviato genera un callback finale.
Maggiori dettagli in Webhook e notifiche.
FAQ
Posso usare la mia chiave API personale qui?
No — l'API di audit utilizza chiavi dell'organizzazione, create da OWNER/ADMIN nel pannello audit, con scope dedicati.
Ho inviato la stessa chiamata due volte. Verrà duplicata?
No, se hai usato la stessa idempotency_key — l'idempotenza è persistente nel database.
Il put_url è scaduto prima del completamento dell'upload. E ora?
Richiedi un nuovo put_url (validità di 1 ora) e ripeti l'invio; non è stato ancora creato nulla.
Come posso limitare ciò che ogni integrazione può fare?
Crea chiavi separate per sistema, ciascuna solo con gli scope necessari (es. dashboard interno solo con analytics:read), e revocale singolarmente quando serve.
Articoli correlati
Non hai risolto? Apri un ticket — il nostro team risponde rapidamente.