عرض قائمة الفاكسات المستلمة

عرض قائمة الفاكسات المستلمة

استخدم حساب API مفعّلًا لدى MultiTEL عبر HTTPS، مع بيانات الاعتماد وقيود عناوين IP المهيأة له. تعرض نقطة النهاية هذه قائمة الفاكسات المستلمة التابعة للحساب الذي تمت مصادقته. وهي لا ترسل فاكسًا ولا تنزّل المستند المرتبط به.

curl --silent --show-error --get --user "$API_USER:$API_PASSWORD" \
  --data-urlencode page=1 \
  --data-urlencode limit=25 \
  --data-urlencode date_from=2026-10-01 \
  --data-urlencode date_to=2026-10-02 \
  https://api.multitel.net/v3/fax_inbox

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

قراءة صفحة من صندوق الوارد

اقرأ نتيجة HTTP وحقل status.code في بيانات JSON. قد تستخدم حالات الإخفاق في مواضع أخرى من API غلاف خطأ بتنسيق JSON حتى عندما تكون حالة HTTP هي 200. تحتوي الاستجابة الناجحة على response.faxes وresponse.pagination. يستخدم هذا المثال قيمًا وهمية.

{
  "status": {"code": 200, "msg": ""},
  "response": {
    "faxes": [{
      "id": 12,
      "hash": "c20ad4d76fe97759aa27a0c99bff6710",
      "from_number": "+12125550123",
      "to_number": "+12125550124",
      "remote_station_id": "Example sender",
      "pages": 2,
      "cost": 0.05,
      "received_at": "2026-10-01 12:00:00",
      "received_timestamp": 1790856000,
      "status": "success",
      "status_text": "OK",
      "emailed": "yes",
      "viewed": false
    }],
    "pagination": {"page": 1, "limit": 25, "total": 1, "total_pages": 1}
  }
}

id هو المعرّف الرقمي لسجل صندوق الوارد. hash هو تمثيله بصيغة MD5 المستخدم في سير العمل القديم للمستندات الواردة؛ وهو ليس معرّف مهمة send_fax ولا بيانات اعتماد للتفويض. لا تستخدمه مع نقطة النهاية fax_status المخصصة للفاكسات الصادرة.

received_timestamp هو الطابع الزمني المخزّن بنظام Unix. received_at هو طابع زمني ينسّقه الخادم دون إزاحة للمنطقة الزمنية، أو null إذا لم يُسجّل وقت استلام؛ استخدم قيمة Unix عند عرض الأوقات في منطقتك الزمنية. cost هو عدد بتنسيق JSON، وليس عرض سعر ولا دليلًا على إتمام خصم مالي منفصل.

status تكون قيمته success فقط عندما يكون رمز الحالة المخزّن صفرًا؛ أما القيم الأخرى فتُحوّل إلى failed. status_text يحمل رسالة المعالجة المخزّنة، مع استخدام OK أو Failed كقيمة بديلة. emailed يحتفظ بالقيمة المخزّنة بدلًا من قيمة منطقية. viewed هو قيمة منطقية. لا تستنتج نجاح تسليم البريد الإلكتروني اعتمادًا على حالة الفاكس وحدها.

التعامل مع القوائم الفارغة والمتغيرة

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

الوصول إلى المستندات والخصوصية

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