إنشاء ملف تسجيل

أنشئ الملف مرة واحدة

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

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

طلب الإنشاء

قم بالمصادقة باستخدام حساب MultiTEL API المفعّل لديك وعنوان IP المسموح به. تستخدم الأمثلة بيانات اعتماد HTTP Basic مخزّنة في متغيرات البيئة. تحقق من استجابة HTTP ومن حقل JSON status.code؛ فاستجابة HTTP 200 وحدها لا تثبت النجاح. جميع قيم الأمثلة وهمية.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data @registration-profile.json \
  https://api.multitel.net/v3/create_document

{
  "identity_type": "Personal",
  "first_name": "Example",
  "last_name": "Person",
  "phone_number": "12025550123",
  "email": "end-user@example.com",
  "city": "Example City",
  "postal_code": "00000",
  "country": "US",
  "address": "1 Example Street",
  "nationality": "US",
  "signature": "BASE64_PNG_OF_THE_AUTHORIZED_END_USER_SIGNATURE"
}

هذا الـ JSON هو ملف Personal توضيحي، وليس هوية حقيقية جاهزة للإرسال. استبدل تفاصيله وتوقيعه بمعلومات المستخدم النهائي التي تتطلبها قواعد التسجيل المحددة. كما يُدعم الإدخال المرمّز بصيغة النموذج.

حقول ملف التسجيل
الحقل	الإلزامية والتنسيق
`identity_type`	إلزامي. استخدم القيمة الدقيقة Personal أو Business؛ إذ يعتمد التحقق الشرطي على حالة الأحرف.
`first_name, last_name`	إلزامية، وبحد أقصى 64 حرفًا لكل منها. بالنسبة إلى الشركات، قدّم بيانات الممثل التي يتطلبها البلد المحدد.
`phone_number`	قيمة هاتف رقمية إلزامية، بما لا يقل عن ثمانية أحرف. يصلح لهذا التحقق رقم دولي مكوّن من أرقام فقط ويتضمن رمز البلد؛ وهذا رقم للتواصل وليس شراءً لرقم.
`city, postal_code, address`	إلزامية، وبحد أقصى 64 حرفًا لكل منها.
`country`	رمز ISO إلزامي لبلد العنوان من كتالوج التسجيل. تقوم الخدمة بمطابقته مع سجل البلد لدى المشغّل.
`signature`	بيانات توقيع إلزامية. تقدّم البوابة الحالية بايتات صورة PNG بترميز Base64 دون البادئة data:image/png;base64,. احصل على توقيع المستخدم النهائي عبر سير العمل المصرّح به لديك؛ فالقيمة البديلة غير الفارغة ليست توقيعًا ذا معنى.
`nationality`	إلزامي لنوع Personal، على شكل رمز ISO للبلد. لا تستبدله بـ UUID للبلد.
`company_name, incorporation_country`	إلزامية لنوع Business. يبلغ الحد الأقصى لاسم الشركة 64 حرفًا؛ ويكون incorporation_country رمز ISO للبلد.
`email`	بريد إلكتروني اختياري للتواصل مع المستخدم النهائي، بحد أقصى 254 حرفًا. البريد الإلكتروني المحذوف أو الفارغ لا يرث البريد الإلكتروني للحساب الأساسي.
`company_reg_number, vat_id, id_number, personal_tax_id, birth_date, description`	اختيارية في هذا المعالج، لكن البلد أو المشغّل المحدد قد يتطلب بعضها. قدّم التنسيقات المطلوبة لذلك التسجيل. لا تطبّق استدعاءات API المباشرة تلقائيًا كل عمليات التوحيد التي تجريها البوابة.

يتطلب معالج v3 المباشر هذا حقول العنوان وينشئ عنوانًا. لا تفترض أن خيار تأجيل العنوان الموجود في البوابة متاح من خلاله.

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

يعرض ما يلي حقولًا مختارة من الاستجابة؛ وتحتوي الاستجابة الفعلية أيضًا على معلومات الملف المرسلة وبيانات التوقيع. تعامل مع الاستجابة الكاملة بوصفها خاصة.

{
  "status": {
    "code": 200,
    "msg": "Success Create Registration Detail."
  },
  "response": {
    "uuid": "11111111111111111111111111111111",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "country_iso": "US",
    "email": "end-user@example.com"
  }
}

response.uuid يحدد الملف المحلي. استخدمه مع get_document. وفي استجابات documents وكذلك get_document، يحمل معرّف الملف نفسه الاسم id.
response.identity_id يحدد الهوية لاستخدامها لاحقًا في إثباتات الهوية و المستندات الداعمة.
response.address_id يحدد العنوان الذي تم إنشاؤه. احتفظ به بشكل منفصل؛ فـ UUID الملف المحلي ليس معرّف عنوان. ولا يزال توافق إرفاق إثبات العنوان لاحقًا للملفات المنشأة حديثًا قيد المراجعة.

لا تُرجع نقطتا نهاية قراءة الملف identity_id أو address_id، لذا احتفظ باستجابة الإنشاء الناجحة الأصلية. وإذا فُقدت، فاستخدم عرض المستندات في البوابة أو تواصل مع الدعم قبل إنشاء بديل.

متقدم: إرفاق إثباتات مرفوعة مسبقًا أثناء الإنشاء

يمكنك تقديم identity_encryptfiles و address_encryptfiles كمصفوفات من المعرّفات التي تُرجعها create_encrypt_files. ارفع الملفات باستخدام نوع إثبات يطابق فئة الكيان، ثم أرسل الطلب قبل انتهاء صلاحية مرجع الملف البالغة نحو 20 دقيقة. يتحقق معالج الإنشاء من الحساب والفئة وتاريخ انتهاء الصلاحية لكل مرجع مقدَّم.

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

إذا رُفض إثبات عنوان لاحق لعنوان أُنشئ حديثًا، فلا تستبدل UUID الملف ولا تعِد إنشاء الهوية مرارًا. توقف وتحقق من الملف في البوابة أو عبر الدعم. ولا يزال مسار قراءة إثبات العنوان والبحث عنه قيدًا من قيود المراجعة.

حالات الفشل والإنشاء الجزئي

يغطي رمز API 400 التحقق من الحقول وحالات فشل الإنشاء لدى المشغّل وحالات فشل الحفظ المحلي. وقد تظهر أخطاء التحقق كإدخالات مفهرسة بأسماء الحقول في response. يُستخدم الرمز 500 لبلد تسجيل غير متاح أو غير صالح، والرمز 404 للمراجع المرفوعة مسبقًا المفقودة أو منتهية الصلاحية. اقرأ status.msg إلى جانب الرمز.

الملف المحلي وعمليات المشغّل في المنبع ليست معاملة ذرّية واحدة. قد يترك الطلب الفاشل حالة في المنبع حتى عندما لا يكون هناك ملف محلي مدرج. ولا يُتاح أي مفتاح تكرار (idempotency) من جهة العميل. بعد انتهاء مهلة أو فشل غير مؤكد، افحص الملفات الموجودة وتواصل مع الدعم قبل تكرار الإنشاء؛ فقائمة documents الفارغة ليست دليلًا على أنه لم يُنشأ أي شيء في المنبع.