إنشاء عملية
هذه هي نقطة الدخول لكل عملية تكامل مع Unico API. يستدعيها الخادم الخلفي (back-end) الخاص بك لإنشاء عملية؛ ويستخدم الواجهة الأمامية (front-end) الرموز المُعادة لعرض iFrame، أو إعادة توجيه المستخدم، أو تهيئة SDK أصلي.
للتعرف على تدفق التكامل الكامل، راجع التدفقات.
النقطة النهائية
| البيئة | الرابط |
|---|---|
| الإنتاج | POST https://api.idcloud.unico.app/client/v1/process |
| Sandbox | POST https://api.idcloud.uat.unico.app/client/v1/process |
الطلب
Headers
| Header | القيمة |
|---|---|
Authorization | Bearer <access_token> (راجع المصادقة) |
Content-Type | application/json |
معاملات الطلب (Body)
متطلبات الحقول تعتمد على التدفق
ما إذا كان الحقل مطلوبًا أو اختياريًا أو غير قابل للتطبيق يعتمد على flow الذي تدمجه — راجع التدفقات لمعرفة الوصفة المحددة التي تستخدمها قبل افتراض متطلبات الحقل من هذا الجدول فقط.
| الحقل | النوع | الوصف |
|---|---|---|
callbackUri | string | عنوان URL الذي يُعاد توجيه المستخدم إليه بعد انتهاء الرحلة. استخدم / لتدفقات SDK الأصلي حيث يتم التعامل مع الاستدعاء داخل التطبيق. |
flow | string | معرّف التدفق — يحدد الإمكانيات التي تعمل. أمثلة: idunicodocs، idunicosign، idchecktrust، idtoken، idsmart. راجع التدفقات المتاحة. |
purpose | string | الغرض التجاري. القيم المقبولة: creditprocess، biometryonboarding، carpurchase، ageverification. |
person.duiType | enum | نوع الوثيقة. راجع قيم duiType أدناه. |
person.duiValue | string | رقم الوثيقة، بدون تنسيق. |
person.friendlyName | string | اسم العرض للمستخدم الظاهر في واجهة الرحلة. الحد الأقصى 50 حرفًا. |
person.phone | string | رقم الهاتف بصيغة رمز الدولة + رمز المنطقة + الرقم، بدون فواصل. مطلوب عند إرسال الإشعارات عبر SMS أو WhatsApp. |
person.email | string | عنوان البريد الإلكتروني. مطلوب للتدفقات التي تتضمن التوقيع الإلكتروني. |
person.notifications | array | قنوات الإشعارات لإرسال رابط الرحلة. يحتوي كل عنصر على notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP، NOTIFICATION_CHANNEL_SMS، أو NOTIFICATION_CHANNEL_EMAIL. |
references | array | مدخلات مرجعية لتدفقات التحقق 1:1 وإعادة التحقق الذكية. يحتوي كل عنصر على referenceType (REFERENCE_TYPE_IMAGE_BASE64 أو REFERENCE_TYPE_PROCESS_ID أو REFERENCE_TYPE_HUMAN_TOKEN) وreferenceContent (صورة مُرمَّزة بـ base64 أو UUID للعملية أو قيمة humanToken). يأخذ REFERENCE_TYPE_HUMAN_TOKEN قيمة humanToken التي يُعيدها Human Token للحساب نفسه. يُعيد humanToken غير المعروف، أو الصادر لحساب آخر، نتيجة تحقق 1:1 سلبية بدلاً من خطأ. أرسل عنصرًا واحدًا كحد أقصى — تُرفض مصفوفة أطول برمز 400، ويجب ألا يكون referenceContent فارغًا. |
useCase | string | سيناريو إعادة التحقق الذكية. مطلوب لـ 🇧🇷 idsmart، idsmart_r2، idsmart_tp1. أمثلة: USE_CASE_LOGIN، USE_CASE_FIN_TRANSACTIONS. |
clientReference | string | معرّف فريد للمستخدم في نظامك. مطلوب لإمكانية حسابات متعددة. فريد في قاعدتك، بحد أقصى 256 حرفًا، بدون مسافات. |
companyBranchId | string (UUID) | معرّف الفرع. مطلوب فقط إذا كان حساب الخدمة مرتبطًا بأكثر من فرع واحد. |
expiresIn | string | نافذة صلاحية العملية من الإنشاء. الصيغة: "3600s". القيمة الافتراضية 7 أيام إذا لم تُحدَّد. |
flowConfig | object | تجاوزات التهيئة الخاصة بكل تدفق. |
flowConfig.biometryCapture.enabledBackCamera | 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. |
imageBase64 | string | الصورة الشخصية، مُرسَلة مباشرة. تقبل JWT الالتقاط الخاص بـ SDK. |
document.purpose | enum | الغرض من الوثيقة. مفردات ثابتة: DOCUMENT_PURPOSE_ONBOARDING، DOCUMENT_PURPOSE_CREDIT_PROCESS، DOCUMENT_PURPOSE_CAR_PURCHASE، DOCUMENT_PURPOSE_PAY_BY_PAYCHECK، DOCUMENT_PURPOSE_FGTS. تُستخدم فقط مع تدفقات Face Document Match. |
document.files[].data | bytes | التقاط وثيقة جديدة: ملف واحد مُرمَّز بـ base64 لكل وجه أو صفحة من الوثيقة، كصورة أو PDF، بحد أقصى 16 MB لكل ملف. أرسل الوجه الأمامي أولًا؛ إذ يُعامَل الملف الأول على أنه الوجه الأمامي. متاح عالميًا، وليس مقتصرًا على البرازيل. متعارض مع document.documentId. |
document.documentId | string (UUID) | يعيد استخدام وثيقة تم التقاطها مسبقًا لنفس الشخص، بدلًا من التقاط جديد. متعارض مع document.files[]. |
expectedResult | object | يحاكي نتيجة إمكانية في بيئات الاختبار/sandbox ويضع علامة simulated: true على الاستجابة. راجع محاكاة النتائج (Test Mock). |
قيم duiType
| الدولة | القيمة | الوصف |
|---|---|---|
| AR | DUI_TYPE_AR_PASSPORT | جواز سفر أرجنتيني |
| AR | DUI_TYPE_AR_DNI | DNI الأرجنتيني |
| AR | DUI_TYPE_AR_LNC | رخصة القيادة الأرجنتينية (Licencia Nacional de Conducir) |
| AT | DUI_TYPE_AT_STNR | الرقم الضريبي النمساوي (STNR) |
| BE | DUI_TYPE_BE_NN | الرقم الوطني البلجيكي (NN) |
| BR | DUI_TYPE_BR_CPF | CPF البرازيلي |
| BR | DUI_TYPE_BR_PASSPORT | جواز سفر برازيلي |
| BR | DUI_TYPE_BR_CNPJ | CNPJ البرازيلي |
| CA | DUI_TYPE_CA_SIN | SIN الكندي |
| CH | DUI_TYPE_CH_AHV | رقم AHV/AVS السويسري |
| CL | DUI_TYPE_CL_RUN | RUN التشيلي |
| CL | DUI_TYPE_CL_PASSPORT | جواز سفر تشيلي |
| CL | DUI_TYPE_CL_LICENCIA_CONDUCIR | رخصة القيادة التشيلية (Licencia de Conducir) |
| CO | DUI_TYPE_CO_NIT | NIT الكولومبي |
| CO | DUI_TYPE_CO_PASSPORT | جواز سفر كولومبي |
| CO | DUI_TYPE_CO_LICENCIA_CONDUCCION | رخصة القيادة الكولومبية (Licencia de Conducción) |
| CO | DUI_TYPE_CO_CC | بطاقة المواطنة الكولومبية (Cédula de Ciudadanía) |
| DE | DUI_TYPE_DE_IDNR | رقم التعريف الضريبي الألماني (IdNr) |
| DK | DUI_TYPE_DK_CPR | CPR الدنماركي |
| EC | DUI_TYPE_EC_NI | NI الإكوادوري |
| ES | DUI_TYPE_ES_NIE | رقم هوية الأجانب الإسباني (NIE) |
| ES | DUI_TYPE_ES_DNI | وثيقة الهوية الوطنية الإسبانية (DNI) |
| FI | DUI_TYPE_FI_HETU | رمز الهوية الشخصية الفنلندي (HETU) |
| FR | DUI_TYPE_FR_SPI | الرقم الضريبي المرجعي الفرنسي (SPI) |
| GB | DUI_TYPE_GB_NINO | رقم التأمين الوطني البريطاني (NINO) |
| GT | DUI_TYPE_GT_CUI | CUI الغواتيمالي |
| ID | DUI_TYPE_ID_NIK | NIK الإندونيسي |
| IE | DUI_TYPE_IE_PPSN | رقم الخدمة العامة الشخصي الأيرلندي (PPSN) |
| IT | DUI_TYPE_IT_CF | Codice Fiscale الإيطالي (CF) |
| LK | DUI_TYPE_LK_NIC | NIC سريلانكي |
| LU | DUI_TYPE_LU_MATRICULE | رقم الهوية الوطني اللوكسمبورغي (Matricule) |
| MX | DUI_TYPE_MX_CURP | CURP المكسيكي |
| MX | DUI_TYPE_MX_RFC_PERSONA_FISICA | RFC المكسيكي (شخص طبيعي) |
| MX | DUI_TYPE_MX_LICENCIA_CONDUCIR | رخصة القيادة المكسيكية (Licencia de Conducir) |
| NG | DUI_TYPE_NG_NIN | NIN النيجيري |
| NG | DUI_TYPE_NG_BVN | رقم التحقق المصرفي النيجيري (BVN) |
| NG | DUI_TYPE_NG_BVN_TOKEN | رمز BVN النيجيري (مُجزّأ) |
| NG | DUI_TYPE_NG_NIN_TOKEN | رمز NIN النيجيري (مُجزّأ) |
| NL | DUI_TYPE_NL_BSN | رقم خدمة المواطن الهولندي (BSN) |
| NO | DUI_TYPE_NO_FNR | رقم الهوية الوطني النرويجي (Fødselsnummer) |
| PE | DUI_TYPE_PE_RUC | RUC البيروفي |
| PE | DUI_TYPE_PE_DNI | DNI البيروفي |
| PE | DUI_TYPE_PE_PASSPORT | جواز سفر بيروفي |
| PL | DUI_TYPE_PL_PESEL | PESEL البولندي |
| PT | DUI_TYPE_PT_NIF | رقم التعريف الضريبي البرتغالي (NIF) |
| SE | DUI_TYPE_SE_PNR | الرقم الشخصي السويدي (PNR) |
| SE | DUI_TYPE_SE_SAMORDNINGSNUMMER | الرقم التنسيقي السويدي (Samordningsnummer) |
| TR | DUI_TYPE_TR_TCKN | رقم الهوية التركي (TCKN) |
| US | DUI_TYPE_US_SSN | SSN الأمريكي |
| US | DUI_TYPE_US_PASSPORT | جواز سفر أمريكي |
| US | DUI_TYPE_US_DRIVER_LICENSE | رخصة قيادة أمريكية |
| US | DUI_TYPE_US_PASSPORT_CARD | بطاقة جواز سفر أمريكية |
| US | DUI_TYPE_US_POLYCARBONATE_PASSPORT | جواز سفر أمريكي مصنوع من البولي كاربونات |
| US | DUI_TYPE_US_ID_CARD | بطاقة هوية أمريكية |
| UY | DUI_TYPE_UY_CI | CI الأوروغوياني |
| ZZ | DUI_TYPE_ZZ_EMAIL | عنوان البريد الإلكتروني |
| ZZ | DUI_TYPE_ZZ_PHONE_NUMBER | رقم الهاتف |
إنشاء عملية بدون وثيقة
عندما يسمح التدفق بوثيقة اختيارية، يمكنك حذف person.duiType وperson.duiValue. بعد الالتقاط، تنتظر العملية في الحالة PROCESS_STATE_AWAITING_FOR_DOCUMENT حتى ترسل الواجهة الخلفية (back-end) الخاصة بك الوثيقة باستخدام تعيين وثيقة العملية.
مثال
- cURL
- Node.js
curl -X POST https://api.idcloud.unico.app/client/v1/process \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"flow": "idunicodocs_r2",
"purpose": "biometryonboarding",
"clientReference": "pedido-88216",
"callbackUri": "https://your-app.example.com/onboarding/callback",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909"
}
}'
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({
flow: 'idunicodocs_r2',
purpose: 'biometryonboarding',
clientReference: 'pedido-88216',
callbackUri: 'https://your-app.example.com/onboarding/callback',
person: {
duiType: 'DUI_TYPE_BR_CPF',
duiValue: '12345678909',
},
}),
});
const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken
الاستجابات
200 OK
{
"process": {
"id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
"flow": "idunicodocs_r2",
"state": "PROCESS_STATE_CREATED",
"result": "PROCESS_RESULT_UNSPECIFIED",
"purpose": "biometryonboarding",
"clientReference": "pedido-88216",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909"
},
"capacities": [
"PROCESS_CAPACITY_IDLIVE",
"PROCESS_CAPACITY_IDUNICO",
"PROCESS_CAPACITY_IDDOCS"
],
"authenticationInfo": {
"authenticationId": ""
},
"companyData": {
"branchId": "",
"countryCode": "BRA"
},
"callbackUri": "https://your-app.example.com/onboarding/callback",
"userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
"webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
"simulated": false
}
}
| الحقل | النوع | الوصف |
|---|---|---|
process.id | string (UUID) | معرّف العملية. استخدمه لجلب النتيجة عبر الحصول على العملية. |
process.state | enum | PROCESS_STATE_CREATED — تم إنشاء العملية، ولم تبدأ الرحلة بعد. PROCESS_STATE_FAILED — فشل إنشاء العملية. |
process.result | enum | نتيجة التحقق. موجودة فقط عندما تكون state = PROCESS_STATE_FINISHED — راجع التدفقات لمعرفة قيم النتائج التي يمكن أن يُعيدها تدفق معيّن. |
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). |