Enterprise-API für Anruf-Auditierung: Endpunkte und Beispiele

Praktische Referenz der Audit-API v1 für Anrufe – der Integrationskanal des Audit-Moduls mit Ihrer TK-Anlage oder Telefonieplattform. Erfordert eine Organisation mit Enterprise-Tarif und einen Organisations-API-Schlüssel.

Authentifizierung

Erstellen Sie den Schlüssel unter /dashboard/organization/auditorias (OWNER/ADMIN; bis zu 10 aktive Schlüssel pro Organisation) und senden Sie ihn bei jeder Anfrage mit:

Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG

• Das Secret wird bei der Erstellung nur einmal angezeigt – wir speichern nur den Hash.
• Jeder Schlüssel besitzt Scopes (audits:write, audits:read, usage:read, analytics:read u. a.); nicht erteilte Berechtigungen werden standardmäßig verweigert.
• Rate-Limit: 60 Anfragen pro Minute und Schlüssel.

Audit erstellen

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"
  }'

Regeln:

• Es wird audio_url (nur https, öffentlich) oder upload_id akzeptiert (siehe unten).
• webhook_url ist erforderlich – das Ergebnis wird per Webhook zugestellt, nicht per Polling.
• idempotency_key wird dauerhaft gespeichert: Erneute Sendungen mit demselben Schlüssel erzeugen kein doppeltes Audit.
• Sofortige Antwort: 202 { "audit_id": "...", "status": "queued" }.

Abfragen: GET /api/v1/audits (Liste) und GET /api/v1/audits/{id} (Details).

Aufnahmen ohne öffentliche URL

Für TK-Anlagen, die keine URL bereitstellen, fordern Sie eine temporäre Upload-URL an:

curl -X POST https://www.vozparatexto.com.br/api/v1/uploads \
  -H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG"

Die Antwort enthält einen put_url, der 1 Stunde gültig ist: Laden Sie die Datei per PUT hoch und verwenden Sie die zurückgegebene upload_id beim Erstellen des Audits.

Betriebsregistrierung und Metriken

Webhooks und Garantien

• Zustellungen sind mit HMAC-SHA256 signiert (X-VPT-Signature + X-VPT-Event); validieren Sie diese, bevor Sie verarbeiten.
• Timeout von 15 s pro Versuch, bis zu 6 Versuche mit Backoff von 5 min bis 24 h.
• Hängende Jobs verschwinden nicht: Eine länger als 10 Minuten gestoppte Warteschlange wird erneut eingereiht; eine Verarbeitung, die länger als 60 Minuten hängt, wird zu einem Fehler mit Fehler-Webhook. Jede gesendete Audiodatei erzeugt einen abschließenden Callback.

Weitere Details in Webhooks und Benachrichtigungen.

FAQ

Verwandte Artikel

• Anruf-Auditierung
• Webhooks und Benachrichtigungen
• Transkriptions-API

Nicht weitergekommen? Eröffnen Sie ein Ticket – unser Team antwortet schnell.