واجهة برمجة تطبيقات المؤسسات لتدقيق المكالمات: النقاط الطرفية وأمثلة

مرجع عملي لواجهة برمجة التطبيقات v1 لتدقيق المكالمات — قناة التكامل بين وحدة التدقيق ونظام PBX أو منصة الهاتف الخاصة بك. يتطلب مؤسسة بخطة المؤسسات ومفتاح واجهة برمجة تطبيقات للمؤسسة.

المصادقة

أنشئ المفتاح في /dashboard/organization/auditorias (OWNER/ADMIN؛ حتى 10 مفاتيح نشطة لكل مؤسسة) وأرسله في كل طلب:

Authorization: Bearer vpt_live_SUA_CHAVE_DA_ORG

• يُعرض السر مرة واحدة فقط عند الإنشاء — نحتفظ بالتجزئة فقط.
• يحمل كل مفتاح نطاقات (audits:write, audits:read, usage:read, analytics:read، وغيرها)؛ وما لم يُمنح يُرفض افتراضيًا.
• حد المعدل: 60 طلبًا/الدقيقة لكل مفتاح.

إنشاء تدقيق

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

القواعد:

• يقبل audio_url (https فقط، عام) أو upload_id (انظر أدناه).
• webhook_url إلزامي — تصل النتيجة عبر خطاف الويب، وليس من خلال الاستقصاء.
• idempotency_key يُحفظ بشكل دائم: إعادة الإرسال بنفس المفتاح لا تُنشئ تدقيقًا مكررًا.
• استجابة فورية: 202 { "audit_id": "...", "status": "queued" }.

الاستعلامات: GET /api/v1/audits (قائمة) و GET /api/v1/audits/{id} (تفاصيل).

تسجيلات بدون رابط عام

بالنسبة إلى PABX الذي لا يعرض رابطًا، اطلب رابط رفع مؤقتًا:

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

يحتوي الرد على put_url صالح لمدة ساعة واحدة: ارفع الملف باستخدام PUT واستخدم upload_id المُعاد عند إنشاء التدقيق.

إدارة بيانات العملية والمقاييس

خطافات الويب والضمانات

• التسليمات موقّعة بـ HMAC-SHA256 (X-VPT-Signature + X-VPT-Event)؛ تحقق منها قبل المعالجة.
• مهلة 15 ثانية لكل محاولة، حتى 6 محاولات مع تراجع من 5 دقائق إلى 24 ساعة.
• المهام العالقة لا تختفي: إذا توقفت قائمة الانتظار لأكثر من 10 دقائق، تُعاد المهام إلى القائمة؛ المعالجة العالقة لأكثر من 60 دقيقة تتحول إلى فشل مع خطاف ويب للخطأ. كل صوت يُرسل يولّد استدعاءً نهائيًا.

مزيد من التفاصيل في خطافات الويب والإشعارات.

الأسئلة الشائعة

مقالات ذات صلة

• تدقيق المكالمات
• خطافات الويب والإشعارات
• واجهة برمجة تطبيقات النسخ

لم تجد حلًا؟ افتح تذكرة — فريقنا يرد بسرعة.