إنشاء عملية

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

للاطلاع على تدفق التكامل الكامل، راجع نظرة عامة على الويب و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	نعم	الرابط الذي يُعاد توجيه المستخدم إليه بعد انتهاء الرحلة. استخدم / لتدفقات 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.
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.currency	string	لا	رمز العملة المعروض للمستخدم. القيم المقبولة: BRL، MXN، USD.
contextualization.price	number	لا	مبلغ المعاملة المعروض للمستخدم.
contextualization.locale	object	لا	نص السبب المترجم. المفاتيح: ptBr، enUs، esMx — كل منها يحتوي على سلسلة reason تُعرض أثناء الرحلة.

مثال

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	رابط رد الاتصال المُرسَل عند الإنشاء.
process.clientReference	string	معرّفك الداخلي المُرسَل عند الإنشاء. يظهر فقط إذا تم تقديمه في الطلب.
process.companyBranchId	string (UUID)	معرّف الفرع. يظهر فقط إذا تم تقديمه في الطلب.
process.userRedirectUrl	string	الرابط لإعادة توجيه المستخدم إليه (تكاملات إعادة التوجيه على الويب و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

تم الوصول إلى حد معدل الطلبات. أعد المحاولة بعد الفترة المُشار إليها في ترويسات الاستجابة.

رموز الأخطاء

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 غير صالحة.
9	XX ID Apikeys are not set	عندما لا يكون مفتاح API مُهيَّأً بشكل صحيح.

401 Unauthorized

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

429 Too Many Requests

لا يُوفَّر رمز خطأ تفصيلي لهذه الحالة — رمز حالة HTTP فقط.

500 Internal Server Error

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

الخطوات التالية

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