إرسال ملف تسجيل رقم

تجهيز الملف المحفوظ والرقم

استخدم سير العمل هذا لربط ملف تسجيل محفوظ برقم اشتريته، وطلب مراجعة التسجيل للأرقام المدعومة التي يُعالَج تسجيلها عبر مشغّل الاتصالات. هذه ليست واجهة API عامة لتفعيل الأرقام لدى جميع مزوّديها. ولا يثبت نجاح الطلب أن المستندات قد اعتُمدت أو أن الرقم قد فُعّل.

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

1. أنشئ ملف تسجيل أو اختر ملفًا موجودًا. احتفظ بمعرّف الملف المحلي uuid الناتج عن create_document؛ إذ تُرجع get_document المرجع المحلي نفسه باسم id.
2. للإرسال عبر مشغّل الاتصالات، يحتاج الملف إلى مرجعي الهوية والعنوان المحفوظين فيه. أرفق ما يلزم من إثباتات ومستندات داعمة عبر سير العمل المناسب لكل منها قبل الإرسال.
3. تحقّق من استيفاء الرقم والملف للمتطلبات المنطبقة على البلد والرقم. لا تفترض أن الملف المحفوظ معتمد لكل رقم.

إرسال طلب الربط

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

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

في الطلبات متعددة الأجزاء، تستخدم المصفوفة حقول onetime_files[] متكررة. يُقبل أيضًا طلب JSON مع Content-Type: application/json؛ وتُدمج خصائصه في بيانات النموذج. يمكن توفير حقل number ضمن بيانات الطلب عند حذف الرقم من المسار. يُفضّل استخدام المسار الصريح الموضّح أعلاه لتجنّب الالتباس.

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

اقرأ كلًا من نتيجة HTTP وحقل JSON status.code. قد تَرِد أخطاء JSON مع HTTP 200. عند نجاح الإرسال عبر مشغّل الاتصالات، تظهر الرسالة Address verification task created; awaiting carrier review. يستخدم هذا المثال مراجع افتراضية.

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

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

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

معالجة الأخطاء دون إنشاء مهام مكرّرة

يشير رمز API 400 إلى غياب الرقم أو مرجع الملف. ويشير الرمز 404 إلى ملف أو رقم غير متاح للحساب، أو رقم غير موجود في مخزون مشغّل الاتصالات. قد يشير الرمز 422 إلى غياب مراجع الهوية أو العنوان، أو متطلبات البائع، أو رفض من مشغّل الاتصالات أثناء التحقّق من الصلاحية. قد يؤدي غياب إعدادات الاستدعاء الراجع إلى الرمز 503، وقد يؤدي فشل النقل أثناء الإنشاء إلى الرمز 502. اقرأ الرسالة وأي requirement_diagnostics بدلًا من التعامل مع جميع حالات الفشل بالطريقة نفسها.

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

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

قيد المستندات المستخدمة لمرة واحدة

يقبل المعالج onetime_files ويمرّر كل سلسلة نصية غير فارغة إلى علاقة الملفات المشفّرة لدى مشغّل الاتصالات. ولا يبحث في سجلات الرفع التابعة للحساب المالك، ولا يحوّل معرّفات الرفع الخارجية المقنّعة إلى معرّفات ملفات لدى المزوّد. تحقّق التدقيق دون اتصال من سلوك التمرير، ولم يؤكّد نجاح إرفاق الملفات لدى مشغّل الاتصالات.

لا تفترض أنه يمكن نسخ معرّف ملف من create_encrypt_files إلى هذا الحقل لإكمال سير عمل اتفاقية لمرة واحدة. استخدم البوابة أو تأكّد مع MultiTEL من سير العمل المدعوم للمعرّفات عندما يتطلب الرقم هذه المستندات. يظل هذا جانبًا غير محسوم من مراجعة واجهة API، وليس مثالًا جرى التحقّق منه من البداية إلى النهاية.

حماية معلومات التسجيل

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