API Enterprise audytu połączeń: Endpointy i przykłady
API v1 audytu połączeń: uwierzytelnianie kluczem organizacji, audyty przez URL lub upload, agenci, zespoły, skrypty, analityka i webhooki HM
Praktyczne odniesienie do API v1 audytu połączeń — kanał integracji modułu audytu z Twoim PABX lub platformą telefoniczną. Wymaga organizacji w planie Enterprise i klucza API organizacji.
Uwierzytelnianie
Utwórz klucz w /dashboard/organization/auditorias (OWNER/ADMIN; do 10 aktywnych kluczy na organizację) i dołączaj go w każdym żądaniu:
Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG
- Sekret jest wyświetlany tylko raz podczas tworzenia — przechowujemy wyłącznie hash.
- Każdy klucz niesie zakresy uprawnień (
audits:write,audits:read,usage:read,analytics:read, i inne); to, czego nie przyznano, jest domyślnie odrzucane. - Limit zapytań: 60 żądań/minutę na klucz.
Tworzenie audytu
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"
}'
Zasady:
- Akceptuje
audio_url(tylkohttps, publiczny) lubupload_id(patrz poniżej). webhook_urljest wymagany — wynik przychodzi przez webhook, a nie przez polling.idempotency_keyjest trwale przechowywany: ponowne wysłanie z tym samym kluczem nie tworzy zduplikowanego audytu.- Natychmiastowa odpowiedź:
202 { "audit_id": "...", "status": "queued" }.
Zapytania: GET /api/v1/audits (lista) i GET /api/v1/audits/{id} (szczegóły).
Nagrania bez publicznego URL
Dla PABX, który nie udostępnia URL, poproś o tymczasowy URL przesyłania:
curl -X POST https://www.vozparatexto.com.br/api/v1/uploads \
-H "Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG"
Odpowiedź zawiera put_url ważny przez 1 godzinę: prześlij plik metodą PUT i użyj otrzymanego upload_id podczas tworzenia audytu.
Rejestracja operacji i metryki
| Endpoint | Funkcja |
|---|---|
GET/POST /api/v1/agents | Agenci (z zewnętrznym identyfikatorem z Twojego systemu) |
GET/POST /api/v1/teams | Zespoły |
GET/POST /api/v1/scripts + POST /api/v1/scripts/{id}/versions | Skrypty i wersje |
GET /api/v1/usage | Zużycie w okresie |
GET /api/v1/analytics/summary | Analityczne podsumowanie operacji |
GET /api/v1/analytics/agents/{external_id} | Metryki według agenta |
Webhooki i gwarancje
- Dostawy podpisane HMAC-SHA256 (
X-VPT-Signature+X-VPT-Event); zweryfikuj przed przetworzeniem. - Limit czasu 15 s na próbę, do 6 prób z backoffem od 5 minut do 24 godzin.
- Zablokowane zadania nie znikają: zatrzymana kolejka >10 min jest ponownie umieszczana; przetwarzanie zawieszone >60 min staje się błędem z webhookiem błędu. Każde przesłane audio generuje końcowy callback.
Więcej szczegółów w Webhooki i powiadomienia.
FAQ
Czy mogę tu użyć mojego osobistego klucza API?
Nie — API audytu używa kluczy organizacji, tworzonych przez OWNER/ADMIN w panelu audytów, z własnymi zakresami uprawnień.
Wysłałem to samo połączenie dwa razy. Czy się zduplikuje?
Nie, jeśli użyjesz tego samego idempotency_key — idempotencja jest trwale zapisana w bazie.
Put_url wygasł przed zakończeniem wysyłania. Co teraz?
Poproś o nowy put_url (ważność 1 godzina) i ponów wysyłkę; nic jeszcze nie zostało utworzone.
Jak ograniczyć to, co może robić każda integracja?
Twórz osobne klucze dla każdego systemu, każdy tylko z niezbędnymi zakresami uprawnień (np. wewnętrzny dashboard tylko z analytics:read) i w razie potrzeby odwołuj je indywidualnie.
Powiązane artykuły
Nie znalazłeś rozwiązania? Otwórz zgłoszenie — nasz zespół odpowiada szybko.