إنشاء عملية

هذه هي نقطة الدخول لكل تكامل Web و SDK. يقوم خادمك الخلفي باستدعائها لإنشاء عملية؛ وتستخدم واجهتك الأمامية الرموز المُرجعة لعرض iFrame، أو إعادة توجيه المستخدم، أو تهيئة SDK أصلي.

للاطلاع على تدفق التكامل الكامل، انظر نظرة عامة على Web و SDK.

نقطة النهاية

البيئة	الرابط
الإنتاج	POST https://api.idcloud.unico.app/client/v1/process
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process

الطلب

الترويسات

الترويسة	القيمة
Authorization	Bearer <access_token> (انظر المصادقة)
Content-Type	application/json

معاملات الجسم

الحقل	النوع	مطلوب	الوصف
callbackUri	string	نعم	عنوان URL الذي يتم إعادة توجيه المستخدم إليه بعد انتهاء الرحلة. استخدم / لتدفقات SDK الأصلية حيث يتم التعامل مع الاستدعاء داخل التطبيق.
flow	string	نعم	معرّف التدفق - يحدد الإمكانيات التي سيتم تشغيلها. أمثلة: idunicodocs، idunicosign، idchecktrust، idtoken، idsmart. انظر التدفقات المتاحة.
purpose	string	نعم	الغرض التجاري. القيم المقبولة: creditprocess، biometryonboarding، carpurchase، ageverification.
person.duiType	enum	نعم	نوع المستند. القيم المقبولة: DUI_TYPE_BR_CPF، DUI_TYPE_MX_CURP، DUI_TYPE_US_SSN، DUI_TYPE_BR_PASSPORT، DUI_TYPE_AR_PASSPORT، DUI_TYPE_AR_DNI، DUI_TYPE_NG_NIN، DUI_TYPE_CL_RUN، DUI_TYPE_EC_NI، DUI_TYPE_US_PASSPORT، DUI_TYPE_GT_CUI، DUI_TYPE_UY_CI، DUI_TYPE_ZZ_EMAIL، DUI_TYPE_ID_NIK، DUI_TYPE_ZZ_PHONE_NUMBER، DUI_TYPE_US_DRIVER_LICENSE، DUI_TYPE_NG_BVN، DUI_TYPE_MX_RFC_PERSONA_FISICA، DUI_TYPE_CO_NIT، DUI_TYPE_PE_RUC، DUI_TYPE_CA_SIN، DUI_TYPE_DK_CPR، DUI_TYPE_GB_NINO، DUI_TYPE_PL_PESEL، DUI_TYPE_SE_PNR، DUI_TYPE_AT_STNR، DUI_TYPE_FI_HETU.
person.duiValue	string	نعم	رقم المستند، بدون تنسيق.
person.friendlyName	string	لا	اسم العرض للمستخدم المعروض في واجهة الرحلة. الحد الأقصى 50 حرفاً.
person.phone	string	لا	رقم الهاتف بتنسيق DDI + DDD + الرقم، بدون فواصل. مطلوب عند إرسال إشعارات عبر SMS أو WhatsApp.
person.email	string	لا	عنوان البريد الإلكتروني. مطلوب للتدفقات التي تتضمن التوقيع الإلكتروني.
person.notifications	array	لا	قنوات الإشعارات لإرسال رابط الرحلة. كل عنصر يحتوي على notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP، NOTIFICATION_CHANNEL_SMS، أو NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	مشروط	مهمل. استخدم references بدلاً منه. معرّف العملية البيومترية المرجعية. مطلوب لتدفقات التحقق 1:1 (idtoken، idtokentrust، idtokensign) وإعادة التحقق الذكية (idsmart).
references	array	مشروط	مدخلات مرجعية لتدفقات التحقق 1:1 وإعادة التحقق الذكية، بديلاً عن bioTokenId. كل عنصر يحتوي على referenceType (REFERENCE_TYPE_IMAGE_BASE64 أو REFERENCE_TYPE_PROCESS_ID) وreferenceContent (صورة مشفرة بـ base64 أو UUID عملية).
useCase	string	مشروط	حالة استخدام إعادة التحقق الذكية. مطلوب لـ idsmart. أمثلة: USE_CASE_LOGIN، USE_CASE_IDENTITY_REVALIDATION_7_DAYS، USE_CASE_FIN_TRANSACTIONS.
clientReference	string	لا	المعرّف الداخلي الخاص بك لهذه العملية (مفتاح خارجي للإسناد التبادلي في البوابة).
companyBranchId	string (UUID)	لا	معرّف الفرع. مطلوب فقط إذا كان لدى حساب الخدمة أكثر من فرع واحد مرتبط.
expiresIn	string	لا	نافذة صلاحية العملية من الإنشاء. التنسيق: "3600s". الافتراضي 7 أيام إذا لم يُحدد.
flow_config	object	لا	تجاوزات تكوين لكل تدفق.
flow_config.biometry_capture.enabled_back_camera	boolean	لا	استخدام الكاميرا الخلفية للجهاز. غير متوافق مع تدفقات التقاط المستندات أو التوقيع الإلكتروني.
contextualization	object	لا	سياق المعاملة المعروض للمستخدم أثناء الرحلة لشرح الالتقاط.
contextualization.company_name	string	لا	اسم الشركة المعروض أثناء الرحلة. الحد الأقصى 20 حرفاً.
contextualization.currency	string	لا	رمز العملة المعروض للمستخدم. القيم المقبولة: BRL، MXN، USD.
contextualization.price	number	لا	مبلغ المعاملة المعروض للمستخدم.
contextualization.locale	object	لا	النص المترجم المعروض أثناء الرحلة. المفاتيح: ptBr، enUs، esMx.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	لا	سبب موجز للالتقاط، يُعرض أثناء الرحلة. الحد الأقصى 50 حرفاً.
contextualization.locale.{ptBr|enUs|esMx}.title	string	لا	عنوان إشعار العميل المعروض أثناء الرحلة. الحد الأقصى 100 حرف. يجب تقديمه مع text. يتم تجريد وسوم HTML.
contextualization.locale.{ptBr|enUs|esMx}.text	string	لا	نص إشعار العميل المعروض أثناء الرحلة. الحد الأقصى 210 أحرف. يجب تقديمه مع title. يتم تجريد وسوم HTML.

مثال

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

الاستجابات

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

الحقل	النوع	الوصف
process.id	string (UUID)	معرّف العملية. استخدمه لجلب النتيجة عبر الحصول على العملية.
process.state	enum	PROCESS_STATE_CREATED - تم إنشاء العملية، لم تبدأ الرحلة بعد. PROCESS_STATE_FAILED - فشل إنشاء العملية.
process.flow	string	معرّف التدفق المرسل عند الإنشاء.
process.purpose	string	الغرض التجاري المرسل عند الإنشاء.
process.callbackUri	string	عنوان URI للاستدعاء المرسل عند الإنشاء.
process.clientReference	string	المعرّف الداخلي الخاص بك المرسل عند الإنشاء. موجود فقط إذا تم تقديمه في الطلب.
process.companyBranchId	string (UUID)	معرّف الفرع. موجود فقط إذا تم تقديمه في الطلب.
process.userRedirectUrl	string	عنوان URL لإعادة توجيه المستخدم إليه (تكامل Web Redirect و iFrame). لا تعدّل هذا العنوان.
process.token	string	JWT لتهيئة Web SDK iFrame.
process.webAppToken	string	JWT لتهيئة SDKs الأصلية (Android، iOS، Flutter).
process.createdAt	string (date-time)	الطابع الزمني لوقت إنشاء العملية.
process.expiresAt	string (date-time)	الطابع الزمني الذي تنتهي بعده صلاحية العملية ولا يمكن إكمالها.
process.capacities	array	الإمكانيات المكوّنة لهذه العملية.
process.authenticationInfo	object	معلومات المصادقة للعملية (فارغة وقت الإنشاء).
process.person	object	صدى كائن person المرسل عند الإنشاء.
process.companyData.branchId	string (UUID)	معرّف الفرع المرتبط بالعملية.
process.companyData.countryCode	string	رمز الدولة المرتبط بالفرع (مثلاً BR، MX).

400 Bad Request

يتم إرجاعه عندما تكون حمولة الطلب غير صحيحة، أو الحقول المطلوبة مفقودة، أو قيمة flow غير معروفة.

401 Unauthorized

رمز Bearer مفقود أو منتهي الصلاحية أو غير صالح. انظر المصادقة.

429 Too Many Requests

تم الوصول إلى حد المعدل. عندما يتلقى نظامك خطأ HTTP 429، يجب عليك تنفيذ آليات لمنع الأعطال المتتالية وتجنب تفاقم القيود.

أفضل الممارسات:

• فترة التهدئة (backoff): أوقف أو قلل الطلبات اللاحقة من نظامك فوراً. لا تعيد محاولة الطلبات الفاشلة باستمرار في حلقة ضيقة.
• التخزين المؤقت وتنظيم المعدل: قم بتخزين الطلبات الصادرة مؤقتاً أو وضعها في قائمة انتظار للتحكم في تدفق حركة المرور قبل إعادة إرسالها.
• التراجع الأسي مع التشتيت: عند إعادة المحاولة، قم بزيادة وقت الانتظار بشكل أسي بين المحاولات (مثلاً 1 ث، 2 ث، 4 ث، 8 ث) وأضف تأخيراً عشوائياً صغيراً ("تشتيت") لمنع تأثير القطيع حيث تعيد جميع الطلبات المؤجلة المحاولة في نفس الميلي ثانية بالضبط.

تحذير

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

للحدود الافتراضية وزيادة الطلبات والتفاصيل الإضافية، انظر حدود المعدل.

رموز الخطأ

400 Bad Request

الرمز	الرسالة	الوصف
3	invalid flow	عندما لا يكون التدفق المحدد موجوداً.
3	invalid person: friendly name exceeds 50 characters.	عندما يتجاوز الاسم الودي 50 حرفاً.
3	invalid purpose	عندما يكون الغرض المقدم غير صالح.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	عندما يكون callbackUri المقدم غير صالح.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	عندما يكون البريد الإلكتروني المقدم غير صالح وإشعار البريد الإلكتروني مكوّن.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	عندما يكون رقم الهاتف المقدم غير صالح وإشعار SMS أو WhatsApp مكوّن.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	عندما يكون المعرّف المقدم (duiValue) غير صالح.
3	invalid expiresIn argument	عندما تكون قيمة expiresIn غير صالحة.
3	invalid company_name argument in process contextualization, max length is 20	عندما يتجاوز contextualization.company_name 20 حرفاً.
3	title and text must be provided together in process contexts	عندما يُقدَّم أحد title أو text فقط دون الآخر في إعدادات اللغة.
3	invalid title argument in process contexts, max length is 100	عندما يتجاوز title الخاص بإعدادات اللغة 100 حرف.
3	invalid text argument in process contexts, max length is 210	عندما يتجاوز text الخاص بإعدادات اللغة 210 أحرف.
3	invalid reason argument in process contexts, max length is 50	عندما يتجاوز reason الخاص بإعدادات اللغة 50 حرفاً.
9	XX ID Apikeys are not set	عندما لا يكون مفتاح API مكوّناً بشكل صحيح.

401 Unauthorized

الرسالة	الوصف
Jwt header is an invalid JSON	عندما يحتوي رمز الوصول المستخدم على أحرف غير صحيحة.
Jwt is expired	عندما تنتهي صلاحية رمز الوصول المستخدم.

429 Too Many Requests

لا يتم توفير رمز خطأ مفصل لهذه الحالة — حالة HTTP فقط. انظر قسم 429 Too Many Requests أعلاه لأفضل الممارسات.

500 Internal Server Error

الرمز	الرسالة	الوصف
99999	Internal failure! Try again later	عند حدوث خطأ داخلي.

ما التالي

• بعد أن ينهي المستخدم الرحلة، استدعِ الحصول على العملية لجلب النتيجة، أو انتظر webhook.