3 min čtení Business

Enterprise API pro audit hovorů: Endpointy a příklady

Q: Můžu tady použít svůj osobní API klíč?

Ne — API pro auditování používá klíče organizace , vytvořené rolemi OWNER/ADMIN v panelu auditů, s vlastními rozsahy oprávnění.

Q: Poslal jsem stejný hovor dvakrát. Vznikne duplicita?

Ne, pokud jste použili stejný idempotency_key — idempotence je v databázi trvalá.

Q: Platnost put_url vypršela před dokončením uploadu. Co teď?

Vyžádejte si nový put_url (platnost 1 hodina) a odešlete znovu; zatím nic nevzniklo.

Praktická reference k API v1 pro audit hovorů: autentizace klíčem organizace, vytváření auditů URL/uploadem, agenti, týmy, scénáře, analytika a HMAC webhooky.

Praktická reference k API v1 pro audit hovorů — integrační kanál modulu auditu s vaším PABX nebo telefonní platformou. Vyžaduje organizaci s podnikovým plánem a klíč API organizace.

Autentizace

Vytvořte klíč v /dashboard/organization/auditorias (OWNER/ADMIN; až 10 aktivních klíčů na organizaci) a posílejte ho v každém požadavku:

Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG

Tajemství je zobrazeno pouze jednou při vytvoření — ukládáme jen hash.
Každý klíč nese rozsahy oprávnění (audits:write, audits:read, usage:read, analytics:read a další); to, co nebylo uděleno, je ve výchozím stavu odepřeno.
Rate limit: 60 požadavků/minutu na klíč.

Vytvořit 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"
  }'

Pravidla:

Akceptuje audio_url (pouze https, veřejné) nebo upload_id (viz níže).
webhook_url je povinné — výsledek dorazí přes webhook, ne pollingem.
idempotency_key se ukládá trvale: opakované odeslání se stejným klíčem nevytvoří duplicitní audit.
Okamžitá odpověď: 202 { "audit_id": "...", "status": "queued" }.

Dotazy: GET /api/v1/audits (seznam) a GET /api/v1/audits/{id} (detail).

Nahrávky bez veřejné URL

Pro PABX, který neposkytuje URL, vyžádejte dočasnou URL pro nahrání:

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

Odpověď obsahuje put_url platný 1 hodinu: nahrajte soubor metodou PUT a při vytváření auditu použijte vrácené upload_id.

Registrace provozu a metriky

Endpoint	Funkce
`GET/POST /api/v1/agents`	Agenti (s externím identifikátorem z vašeho systému)
`GET/POST /api/v1/teams`	Týmy
`GET/POST /api/v1/scripts` + `POST /api/v1/scripts/{id}/versions`	Scénáře a verze
`GET /api/v1/usage`	Spotřeba za období
`GET /api/v1/analytics/summary`	Analytický přehled provozu
`GET /api/v1/analytics/agents/{external_id}`	Metriky podle agenta

Webhooky a záruky

Doručení jsou podepsaná HMAC-SHA256 (X-VPT-Signature + X-VPT-Event); před zpracováním ověřte podpis.
Timeout 15 s na pokus, až 6 pokusů s backoffem od 5 minut do 24 hodin.
Zaseklé úlohy nezmizí: fronta nečinná déle než 10 min se znovu zařadí; zpracování zaseklé déle než 60 min skončí chybou a odešle se chybový webhook. Každé nahrané audio vygeneruje finální callback.

Více podrobností v Webhooky a notifikace.

FAQ

Můžu tady použít svůj osobní API klíč?

Ne — API pro auditování používá klíče organizace, vytvořené rolemi OWNER/ADMIN v panelu auditů, s vlastními rozsahy oprávnění.

Poslal jsem stejný hovor dvakrát. Vznikne duplicita?

Ne, pokud jste použili stejný idempotency_key — idempotence je v databázi trvalá.

Platnost put_url vypršela před dokončením uploadu. Co teď?

Vyžádejte si nový put_url (platnost 1 hodina) a odešlete znovu; zatím nic nevzniklo.

Jak omezím, co může každá integrace dělat?

Vytvořte pro každý systém samostatné klíče, každý jen s nezbytnými rozsahy (např. interní dashboard jen s analytics:read), a v případě potřeby je jednotlivě zrušte.

Související články

Nepomohlo vám to? Otevřete ticket — náš tým odpovídá rychle.

Audit hovorů pro firmy: Jak modul funguje