شكرًا على ملاحظاتك.

يوفر دليل الويب الخاص بسجلات المكالمات التفصيلية حلاً آمنًا وقابلًا للتطوير وقويًا مدفوعًا بالأحداث بدلاً من الطلبات. يوفر هذا الويب هوك رؤية أكبر Webex Calling لأنشطة عملائك، ويدعم حالات الاستخدام من إعداد الفواتير إلى التقارير المصممة خصيصًا.

يمكنك استخدام دليل الويب هذا لجمع السجلات بسهولة لجميع العملاء الذين تتم إدارتهم من خلال Partner Hub دون الاستعلام عن كل عميل على حدة. يتيح لك دليل الويب هذا تطوير تطبيقات مخصصة لإعداد التقارير والفواتير والتحليلات لكل من متطلبات الأعمال الداخلية والخدمات ذات القيمة المضافة.

للحصول على مقدمة حول كتاب الويب وواجهات برمجة التطبيقات المصاحبة له، شاهد هذا Vidcast: واجهة برمجة تطبيقات سجل المكالمات المفصلة Webex Calling للشركاء.

ما يقدمه دليل الويب الخاص بالشركاء

يقدم webhook سجلات مفصلة لسجل المكالمات كل 5 دقائق. تحتوي كل حمولة webhook على:

• سجلات المكالمات التي انتهت بين 10 دقائق و 5 دقائق قبل الوقت الحالي.
• أي سجلات متأخرة تمت معالجتها بواسطة Webex Calling السحابة.
• يقوم تلقائيًا بإعادة ملء سجلات المكالمات المتأخرة في حمولات webhook اللاحقة لضمان التسليم الموثوق.

لإظهار كيفية تضمين سجلات المكالمات في كل حمولة، خذ بعين الاعتبار المثال التالي:

• تحتوي الحمولة المستلمة في الساعة 14:05 على مكالمات انتهت بين الساعة 13:55 والساعة 14:00.
• يتم تضمين المكالمات التي تنتهي بين 14:00 و 14:05 في حمولة 14:10.
• يتم تضمين السجلات التي تم إكمالها مسبقًا (على سبيل المثال، مكالمة انتهت في 14:04) ولكن تمت معالجتها في وقت متأخر بواسطة Webex Calling السحابة (على سبيل المثال، الساعة 14:11) في الحمولة المجدولة التالية ( على سبيل المثال، 14:15).

Webhook في مركز الشركاء

من خلال توفير webhook، يمكنك تمكين منصة التحليلات من إرسال سجلات المكالمات إلى عنوان URL الخاص برد الاتصال الخاص بك كلما تم إنشاؤها.

Webex Callingيتم تسليم السجلات باستخدام نفس التنسيق مثل واجهات برمجة تطبيقات سجلات المكالمات التفصيلية الحالية. يمكنك إعداد webhook والاختيار بين نوعين من الخلاصات:

• التحليلات - تتضمن جميع سجلات المكالمات لجميع مؤسسات العملاء التي يرتبط الشريك بعلاقة معها. Webex Calling يشمل ذلك المنظمات التي:
  • يقوم الشريك بإدارة مؤسسة العميل من خلال دور المسؤول الكامل للشريك.
  • لدى منظمة العملاء Webex Calling اشتراك نشط داخل المؤسسة الشريكة.
• إعداد الفواتير - تتضمن سجلات المكالمات للمكالمات التي أجراها المستخدمون Webex Calling بترخيص تم بيعه وتوفيره من قبل الشريك. يتم تضمين سجلات المكالمات لمساحات العمل في هذه الخلاصة.

الوصول وخصوصية البيانات

يمكن للشريك المالك فقط الوصول إلى سجلات تفاصيل المكالمات (CDR) للفواتير.

• يصبح الشريك (أو الشريك الفرعي) الذي يدير الترخيص المرتبط بسجل المكالمات هو الشريك المالك.
• يتم تحديد الملكية من خلال: معرف المستخدم > معرف الترخيص > معرف الاشتراك > معرف الشريك.
• يمكن الوصول إلى كل CDR لشريك واحد.
• لا يتم ربط بعض سجلات المكالمات بشريك الفواتير، ولا يحصل جميع الشركاء المرتبطين بالمؤسسة على وصول متساوٍ إلى جميع السجلات، نظرًا لأن هذه السجلات قد تحتوي على معلومات تعريف شخصية (PII).

بالإضافة إلى webhook، Webex Calling يوفر نقاط نهاية API لدعم تسوية البيانات. تسمح لك نقاط النهاية هذه باللحاق بمخازن البيانات الخاصة بك أو تسويتها مع أي سجلات مفقودة ربما لم يستلمها مستمع webhook الخاص بك. نقطتا نهاية API هما واجهة برمجة تطبيقات التسوية وواجهة برمجة تطبيقات السجلات.

تتوفر السجلات من واجهات برمجة التطبيقات هذه لمدة 30 يومًا. لضمان حصولك على جميع السجلات المتوقعة، نوصي بتسوية مخازن السجلات الخاصة بك بشكل دوري، مثل كل 12 أو 24 ساعة.

يجب عليك استخدام رمز وصول الشريك للوصول إلى واجهات برمجة التطبيقات هذه. يجب أن يكون المستخدم المصادق مسؤولًا كاملًا شريكًا يتمتع بإمكانية الوصول إلى مستوى المسؤول التنظيمي الكامل ويجب تمكين الوصول إلى Webex CallingCDR API. يجب أن يتضمن رمز OAuth النطاق. spark-admin:calling_cdr_read لا تكفي أدوار المسؤول للقراءة فقط لواجهات برمجة تطبيقات تسوية الشركاء والسجلات.

استخدم analytics-callingنقطة النهاية لمنطقة Webex Calling بيانات مؤسسة العميل. استخدم عنوان URL الأساسي القابل للتطبيق لكل من واجهات برمجة تطبيقات التسوية والسجلات:

• الولايات المتحدة وكندا: https://analytics-calling.webexapis.com
• أوروبا: https://analytics-calling-eu.webexapis.com
• الهند: https://analytics-calling-in.webexapis.com
• أستراليا: https://analytics-calling-au.webexapis.com

نقطة نهاية API للمصالحة

تقوم نقطة نهاية Replication API بإرجاع العدد الإجمالي لعدد سجلات المكالمات التي تم إنشاؤها لكل عميل يديره الشريك خلال الفترة الزمنية المحددة. يمكنك استخدام هذه الإجماليات للتحقق من سعة التخزين المحلية وتحديد أي سجلات مكالمات مفقودة أو غير متسقة لعملاء محددين.

إذا كنت تدير أكثر من 200 مؤسسة عملاء، فإن واجهة برمجة التطبيقات تقوم بترقيم النتائج لتحسين قابلية القراءة.

يستخدم عنوان URL الخاص بنقطة نهاية API للمصالحة التنسيق التالي:

بارامترات واجهة برمجة التطبيقات

يمكنك استخدام API لاسترداد سجلات المكالمات من آخر 30 يومًا. يجب أن تبدأ النافذة الزمنية المحددة قبل 5 دقائق على الأقل من وقت UTC الحالي ولا يمكن أن تتجاوز 12 ساعة بين أوقات البدء والانتهاء في مكالمة API واحدة.

معايير API هي:

• وقت البدء (مطلوب، سلسلة) - تاريخ ووقت البدء (UTC) للسجل الأول الذي تريد تجميعه. تأكد من:
  • تقوم بتنسيق الوقت كـ YYYY-MM-DDTHH:MM:SS.mmmZ. على سبيل المثال، 2025-08-15T06:00:00.000Z.
  • يجب ألا يزيد تاريخ ووقت البدء عن 30 يومًا من وقت UTC الحالي.
  • لا يمكن أن تتجاوز الفترة startTimeالفاصلة بين 12 ساعة ولا endTimeيمكن أن تتجاوز.
• وقت الانتهاء (مطلوب، سلسلة) - تاريخ ووقت الانتهاء (UTC) للسجلات التي تريد جمعها. تعتمد السجلات على وقت التقرير، وهو وقت الانتهاء من المكالمة. تأكد من:
  • تقوم بتنسيق الوقت كـ YYYY-MM-DDTHH:MM:SS.mmmZ. على سبيل المثال، 2025-08-15T18:00:00.000Z.
  • يجب أن يكون تاريخ ووقت الانتهاء قبل 5 دقائق من التوقيت العالمي المنسق الحالي وألا يزيد عمرهما عن 30 يومًا.
  • يجب أن يكون تاريخ ووقت الانتهاء أكبر من startTime.
  • لا endTimeيمكن أن تتجاوز الفترة الفاصلة بين الساعة 12 ساعة. startTime

مثال على استجابة JSON لنقطة نهاية API للمصالحة:

          {
          "cdr_counts": [
          {
          "orgId": "zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
          "count": 3009
          },
          {
          "orgId": "yyyyyyyy-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
          "count": 129
          },
          {
          "orgId": "xxxxxxxx-yyyy-zzzz-xxxx-yyyyyyyyyyyy",
          "count": 27895
          }
          ]
          }          
        

تشير عناوين استجابة API إلى إجمالي عدد المؤسسات التي تم إرجاعها وما إذا كانت هناك صفحات إضافية متاحة. تحقق من معاملات العنوان التالية للتأكد من أنك استفسرت عن جميع الصفحات:

• عدد الصفحات: إجمالي عدد الصفحات (على سبيل المثال، 2)
• total-orgs: إجمالي عدد المنظمات المدرجة في الرد (على سبيل المثال، 283)
• الصفحة الحالية: رقم الصفحة الحالية (على سبيل المثال، 1)

على سبيل المثال، إذا كانت العناوين تعرض num-pages=2 وtotal-orgs=283 وcurrent-page=1، فإنك تعرض الصفحة الأولى من الرد المكون من صفحتين والذي يحتوي على 283 مؤسسة إجمالاً. للوصول إلى الصفحة التالية، أضف المعلمة page=2 إلى طلب GET الخاص بك، كما هو موضح أدناه:

https://analytics-calling.webexapis.com/v1/partners/cdrcountbyorg?endTime=YYYY-MM-DDTHH:MM:SS.000Z&startTime=YYYY-MM-DDTHH:MM:SS.000Z&page=2

نقطة نهاية API للسجلات

تُستخدم نقطة نهاية Records API للاستعلام عن سجلات المكالمات المفقودة لمؤسسات معينة حيث تم تحديد التناقضات أو البيانات المفقودة باستخدام واجهة برمجة تطبيقات التسوية.

التدفق الموصى به: اتصل /v1/partners/cdrcountbyorgأولاً. ثم استخدم الرقم الذي تم orgIdإرجاعه بالضبط cdr_counts[].orgIdعند الاتصال /v1/partners/cdrsbyorg.

تقوم واجهة برمجة تطبيقات السجلات بإرجاع سجلات المكالمات بصيغة JSON، وهي مطابقة للتنسيق الموضح في واجهة برمجة تطبيقات سجل المكالمات التفصيلي. تحتوي الحمولة التي تم إرجاعها على حقول مماثلة للحمولة التي تم إرجاعها في سجل المكالمات التفصيلي. لمزيد من المعلومات حول الحقول وقيمها، راجع تقرير سجل المكالمات Webex Calling المفصل.

توفر واجهة برمجة التطبيقات سجلات المكالمات التي انتهت قبل 5 دقائق من الوقت الحالي. لضمان توفير جميع سجلات المكالمات، نوصي بالاستعلام عن واجهة برمجة التطبيقات بعد ساعة واحدة من النافذة الزمنية المفضلة لديك.

يستخدم عنوان URL الخاص بنقطة نهاية Records API التنسيق التالي:

https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=YYYY-MM-DDTHH:MM:SS.000Z&startTime=YYYY-MM-DDTHH:MM:SS.000Z

بارامترات واجهة برمجة التطبيقات

• orgId(مطلوب، سلسلة) —معرف مؤسسة العميل الذي تريد استرداد السجلات الخاصة به. اسم المعلمة حساس لحالة الأحرف. يمكنك الحصول على معرفات المؤسسة من حقل استجابة Replication API cdr_counts[].orgId.
• وقت البدء (مطلوب، سلسلة) - تاريخ ووقت البدء (UTC) للسجل الأول الذي تريد تجميعه. تأكد من:
  • تقوم بتنسيق الوقت كـ YYYY-MM-DDTHH:MM:SS.mmmZ. على سبيل المثال، 2025-08-15T06:00:00.000Z.
  • يجب ألا يزيد تاريخ ووقت البدء عن 30 يومًا من وقت UTC الحالي.
  • endTimeيجب ألا تتجاوز الفترة الفاصلة بين الساعة 12 ساعة في طلب API واحد. startTime
• وقت النهاية (مطلوب، سلسلة) - تاريخ ووقت الانتهاء (UTC) للسجل الأخير الذي تريد تجميعه. تعتمد السجلات على وقت التقرير، وهو وقت الانتهاء من المكالمة. تأكد من:
  • تقوم بتنسيق الوقت كـ YYYY-MM-DDTHH:MM:SS.mmmZ. على سبيل المثال، 2025-08-15T18:00:00.000Z.
  • يجب أن يكون تاريخ ووقت الانتهاء قبل 5 دقائق على الأقل من التوقيت العالمي المنسق الحالي وألا يزيد عمرهما عن 30 يومًا.
  • يجب أن يكون تاريخ ووقت الانتهاء أكبر من startTime.
  • endTimeيجب ألا تتجاوز الفترة الفاصلة بين الساعة 12 ساعة في طلب API واحد. startTime
• الحد الأقصى (اختياري، رقم) —يحدد الحد الأقصى لعدد السجلات لكل صفحة في الاستجابة. تأكد من:
  • يتراوح النطاق من 500 إلى 5000. القيمة الافتراضية هي 5000. على سبيل المثال، max=1000.
  • إذا كانت واجهة برمجة التطبيقات تحتوي على سجلات أكثر من القيمة القصوى المحددة، فسيتم ترقيم الاستجابة إلى صفحات.
  • إذا تم تحديد قيمة أقل من 500، يتم ضبطها تلقائيًا حتى 500. إذا تم تحديد قيمة أعلى من 5000، يتم تعديلها إلى 5000.

ترقيم الصفحات

لتحديد ما إذا كانت استجابات API مقسمة إلى صفحات أم لا، تحقق من رؤوس الاستجابة لرأس الارتباط. في حالة وجود nextرابط في رأس الرابط، قم باستخراجه واستخدم startTimeForNextFetchالقيمة لطلب المجموعة التالية من السجلات. إذا لم يكن هناك رابط تالي، فسيتم جمع جميع التقارير الخاصة بالنطاق الزمني المحدد.

يمكن تقديم طلبات API للصفحات اللاحقة على الفور، ولكن يجب أن يقتصر تقييمها على 10 طلبات مقسمة إلى صفحات في الدقيقة كحد أقصى، لكل نطاق رمزي.

استخدم المعالجة غير الفعالة وإزالة التكرار عند استرداد السجلات، بما في ذلك عبر الردود المقسمة إلى صفحات أو نوافذ التسوية المتكررة. استخدم reportIdكمفتاح أساسي reportTimeولتحديد أحدث سجل تمت معالجته.

على سبيل المثال، إذا كان طلب API الأولي هو:

https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=2025-08-15T18:00:00.000Z&startTime=2025-08-15T06:00:00.000Z&max=5000

ثم يكون عنوان الرابط في الاستجابة هو:

<https://analytics-calling.webexapis.com/v1/partners/cdrsbyorg?orgId=zzzzzzzz-yyyy-zzzz-xxxx-yyyyyyyyyyyy&endTime=2025-08-15T18:00:00.000Z&startTime=2025-08-15T06:00:00.000Z&startTimeForNextFetch=2025-08-15T09:30:00.000Z&totalCount=20000&max=5000>; rel="next"

يستخدم ترقيم الصفحات رأس rel="next"الارتباط فقط. إذا كانت الاستجابة تتضمن rel="next"رابطًا، فاستخدم عنوان URL هذا لاسترداد الصفحة التالية من السجلات. إذا لم تتضمن الاستجابة rel="next"رابطًا، فقد استرجعت جميع السجلات المتاحة للنطاق الزمني المحدد.

يمكنك إنشاء وتنزيل التقارير المتوفرة في Partner Hub باستخدام واجهات برمجة تطبيقات تقارير الشركاء. لمزيد من المعلومات، راجع تقرير/قوالب الشركاء.

يمكن للشركاء أيضًا الوصول إلى تقارير متعددة وتنزيلها مباشرةً من Partner Hub. لمزيد من المعلومات، راجع تقارير Partner Hub.