إرسال فاكس

قبل الإرسال

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

استخدم حسابًا مفعّلًا لواجهة API لدى MultiTEL. أرسل بيانات اعتماد HTTP Basic للحساب الذي يستخدم كلمة مرور، أو رمز Bearer للحساب الذي يستخدم رمزًا. تظل صلاحيات الحساب والقيود على عناوين بروتوكول الإنترنت سارية. لا تستخدم بيانات الاعتماد الداخلية لعوامل التنفيذ.

رفع المستند

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax

حقول الطلب
الحقل	مطلوب	المعنى
`from_number`	نعم	رقم المرسل المصرح لك باستخدامه. استخدم التنسيق الدولي الذي يبدأ بعلامة + متبوعة برمز البلد.
`to_number`	نعم	رقم فاكس المستلم بالتنسيق الدولي.
`fax_file`	نعم للطلبات متعددة الأجزاء	المستند المرفوع. دع curl يضبط ترويسة Content-Type والفاصل بين أجزاء الطلب متعدد الأجزاء.
`webhook_url`	لا	عنوان اختياري لاستقبال الإشعارات الراجعة عبر HTTP أو HTTPS؛ ويُفضّل استخدام HTTPS. لا يزال محتوى الإشعارات الراجعة وضمانات تسليمها قيد المراجعة: استعلم دوريًا من fax_status لاتباع سير العمل الموثّق لمتابعة الحالة.

تُقبل أيضًا صيغة JSON مع Content-Type: application/json، وحقول الأرقام نفسها والحقل الاختياري webhook_url، بالإضافة إلى file_name و file_b64. يحتوي file_b64 على بايتات المستند بترميز Base64 المطابق للصيغة بدقة، دون البادئة data:. تكون الأولوية لحقل fax_file الصالح المقدّم ضمن طلب متعدد الأجزاء. واجهة API هذه ليست مخصّصة لجلب الملفات من عناوينها.

حدود المستندات والطلبات المقدّمة

يقبل التطبيق مستندًا لا يتجاوز حجمه بعد فك الترميز 15,728,640 بايت (15 MiB)، بامتداد pdf أو tif أو tiff أو jpg أو jpeg أو png أو doc أو docx أو txt. لا يضمن الامتداد المسموح به قدرة الخدمة على عدّ الصفحات أو تحويلها. قد تكون حدود حجم الطلبات في البنية التحتية أقل، كما يزيد ترميز Base64 من حجم الطلب.

يسمح التطبيق الحالي لكل حساب بمهمة واحدة في قائمة الانتظار أو قيد الإرسال إلى الوجهة نفسها، وبخمسة طلبات على الأكثر إلى تلك الوجهة خلال الساعة السابقة، وبما لا يتجاوز 50 طلبًا إجمالًا خلال الساعة السابقة. تستخدم استجابة تقييد المعدل رمز API 429. انتظر قبل إعادة المحاولة؛ ولا تحاول تجاوز الحدود.

الاحتفاظ بمعرّف المهمة

اقرأ نتيجة HTTP وكذلك، في محتوى JSON، الحقل status.code. قد تَرِد حالات الفشل المبيّنة بصيغة JSON مع الرمز HTTP 200. تحتوي الاستجابة الناجحة بصيغة JSON على status وresponse؛ وتستخدم الأمثلة بيانات وهمية.

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

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

الأخطاء والتحقق من الرصيد

تشمل رموز API الرمز 400 عند غياب حقول أو عدم صلاحية عنوان استقبال الإشعارات الراجعة أو رفض المستند أو فشل اكتشاف الصفحات؛ والرمز 401 عند غياب المصادقة؛ والرمز 402 عندما تتجاوز تكلفة الفاكس المقدّرة، مضافًا إليها تقديرات المهام في قائمة الانتظار أو قيد الإرسال، الرصيد المتاح في الحساب؛ والرمز 429 لحدود المعدل؛ والرمز 500 عند فشل التجهيز المرحلي للمستند. اقرأ status.msg لمعرفة السبب المحدّد.

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