قراءة سجلات مكالمات الحساب

استرجاع سجلات مكالمات الحساب

اقرأ سجلات المكالمات الواردة أو الصادرة لحساب API الخاص بك. تحتوي هذه السجلات على معلومات خاصة بالمكالمات والفوترة. احصر استخدامها في مسارات العمل المصرّح بها على جانب الخادم، وتجنب تسجيلها أو مشاركتها دون حاجة.

تستخدم نقطة النهاية القديمة هذه حاليًا فترة افتراضية ثابتة، ولا تدعم تقسيم النتائج إلى صفحات. استخدم مسار سجل المكالمات وتصديرها في البوابة عندما تحتاج إلى فترة تقارير مختلفة أو إلى تصدير كميات كبيرة من السجلات التاريخية؛ فمعاملات التواريخ المخصصة في نقطة النهاية هذه غير موثوقة.

الطلبات

أجرِ المصادقة عبر HTTPS باستخدام حساب API المفعّل لديك، من عنوان بروتوكول الإنترنت المصدري المسموح به لهذا الحساب. يستخدم المثال بيانات اعتماد محفوظة في متغيرات البيئة. لا يلزم إرسال جسم للطلبات المدعومة التي تستخدم الفترة الافتراضية.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cdrs

مسارات طلبات سجلات المكالمات
المسار	النطاق
/v3/cdrs	سجلات المكالمات الواردة للحساب ضمن الفترة الافتراضية.
/v3/cdrs/{number}	سجلات المكالمات الواردة التي يطابق رقمها الرقم المقدّم تمامًا. يُفضّل استخدام الرقم بكامل أرقامه كما هو مسجّل في قائمة أرقامك.
/v3/cdrs/all/outbound	سجلات المكالمات الصادرة للحساب ضمن الفترة الافتراضية. يتجاهل فرع معالجة المكالمات الصادرة الوسيط الأول في المسار؛ وتُستخدم all هنا كقيمة نائبة، وليست رمزًا بديلًا لمطابقة المكالمات الواردة.

استخدم قيمة الاتجاه inbound أو outbound كما وردت أعلاه تمامًا. لا يطبّق فرع معالجة المكالمات الصادرة مرشحًا لكل رقم. وإضافة رقم إلى ذلك المسار لا تضيّق نطاق نتائج المكالمات الصادرة.

فترة التقارير الافتراضية

يبدأ الاستعلام عند منتصف الليل في التاريخ الذي يسبق اليوم بمقدار 30 يومًا وفق تقويم الخادم، وينتهي عند منتصف الليل في بداية اليوم الحالي. لذلك لا يشمل بقية اليوم الحالي. وهذه ليست فترة متحركة مدتها 720 ساعة تنتهي في الوقت الحالي.

لا يدعم التنفيذ الحالي حقول النموذج date_from/date_to بصورة موثوقة: فتقديم تواريخ مخصصة يترك متغيرات سنة تقسيم البيانات دون تعيين. لا تستخدم هذه الحقول لإعداد تقرير في بيئة الإنتاج. ولم تُنفّذ التواريخ ضمن سلسلة الاستعلام أو معاملات تقسيم النتائج إلى صفحات كبدائل.

الاستجابة

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

{
  "status": {
    "code": "200",
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "number": "12025550123",
      "callerid": "12025550124",
      "disposition": "ANSWERED",
      "billseconds": "60",
      "billcost": "0.0100",
      "callsid": "11111111111111111111111111111111",
      "date_created": "2026-10-01 12:00:00 UTC"
    }
  ]
}

تكون response قائمة. وقد يتضمن الغلاف المشترك للاستجابة الحقل status.results لبيان عدد الصفوف. وقد تكون رموز النتائج سلاسل نصية. وعند عدم وجود سجلات، تستخدم النتيجة رمز API رقم 404 مع الرسالة No entries found، بدلًا من إرجاع قائمة فارغة مع حالة نجاح.

حقول السجلات

الحقول الرئيسية المُرجعة
الحقول	المعنى
number, callerid	رقم المكالمة الواردة ومعرّف المتصل ضمن الحقول المعروضة للمكالمات الواردة.
calling, called, callerid	معرّفات الطرف المتصل والطرف المتصل به ضمن الحقول المعروضة للمكالمات الصادرة. لا تستنتج من معرّف المتصل أن هوية المشترك قد تم التحقق منها.
disposition, billseconds, billcost	حالة انتهاء المكالمة المخزّنة، والمدة المحتسبة للفوترة، ومبلغ الفوترة المخزّن. وقد تستخدم القيم تنسيقات نصية قديمة من قاعدة البيانات.
callsid	معرّف UUID المخزّن للمكالمة، ويُستخدم لربط السجلات ذات الصلة.
date_created	سلسلة نصية للتاريخ والوقت تنتهي باللاحقة الحرفية UTC، دون ضمان أن تكون طابعًا زمنيًا بتنسيق ISO8601. حلّل التنسيق المُرجع صراحةً.
حقول أخرى	تتضمن سجلات المكالمات الواردة أيضًا معلومات تشخيصية عن الإخفاق والتكلفة والقناة والجودة والمصدر؛ وتتضمن سجلات المكالمات الصادرة معلومات تشخيصية عن منطقة إنهاء المكالمة. وقد تحتوي الاستجابة الكاملة على معلومات عن البنية التحتية، ويجب التعامل معها على أنها معلومات خاصة.

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

الأخطاء وحدود إعداد التقارير

اقرأ كلًا من حالة HTTP والحقول status.code/status.msg في محتوى JSON. عند عدم وجود سجلات للحساب والفترة المحددين، يُرجع الطلب رمز API رقم 404. وتسري أيضًا قيود المصادقة وعنوان بروتوكول الإنترنت المصدري. قد يفشل تقرير كبير غير مقسّم إلى صفحات، أو طلب يستخدم تواريخ مخصصة غير موثوقة؛ والاستعلام المتكرر عن الجدول كاملًا ليس استراتيجية للتصدير التزايدي.

يحتوي المعالج الذي تمت مراجعته على استعلامات قراءة، ولا يخصم من رصيد الحساب ولا يبدأ أي مكالمة. ووجود سجل مُرجع لا يثبت أن شخصًا قد أجاب؛ فسّر حالة انتهاء المكالمة ومدتها المخزّنتين بما يلائم غرض تقريرك.