الانتقال إلى المحتوى الرئيسي
الحصول على العمليةGET

استرجاع عملية موجودة بواسطة معرّفها. وفقًا لعقد API، تُعاد النتيجة بشكل متزامن عند إنشاء العملية — استخدم هذه النقطة النهائية لإعادة الاستعلام والتدقيق والدعم.

Markdown
تحذير

قبل استرجاع العملية، راجع تهيئة webhook واستراتيجيات fallback الخاصة بنا — اضغط هنا.

النقطة النهائية​

البيئةالرابط
الإنتاجGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

الطلب​

Headers
Headerالقيمة
AuthorizationBearer <access_token>
معاملات المسار
المعاملالنوعمطلوبالوصف
processIdstring (UUID)نعممعرّف العملية الذي أعادته إنشاء عملية.

مثال​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"

الاستجابات​

200 OK
{
"process": {
"id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
"flow": "id_r2",
"callbackUri": "/",
"userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_APPROVED",
"createdAt": "2026-08-06T01:42:21.693615Z",
"finishedAt": "2026-08-06T01:43:03.080508Z",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "40*******50",
"friendlyName": "teste",
"email": "",
"phone": "5511999999999",
"notifications": [
{ "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
],
"phoneCountryCodeAlpha3": ""
},
"purpose": "personAuthentication",
"services": [],
"authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
"capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
"expiresAt": "2026-08-13T01:42:21.536500Z",
"token": "",
"companyData": { "branchId": "", "countryCode": "BRA" },
"simulated": false
}
}
حقول العملية
الحقلالمعنى
idUUID الخاص بالعملية؛ المفتاح المستخدم للاستعلام عن التدفق وتتبعه.
flowنوع الرحلة التي تم تنفيذها (مثل id_r2، idlivetrust_r2، idtrust_r2، ...).
callbackUriعنوان URL لإعادة الاتصال الذي يُعاد توجيه تطبيق العميل إليه في نهاية التدفق.
userRedirectUrlعنوان URL الكامل لصفحة CbU التي يفتحها المستخدم لتنفيذ الرحلة (يحمل id وأعلام السلوك).
stateحالة دورة حياة العملية (مثل PROCESS_STATE_CREATED، PROCESS_STATE_FAILED، PROCESS_STATE_FINISHED، PROCESS_STATE_AWAITING_FOR_DOCUMENT، PROCESS_STATE_UNSPECIFIED).
resultالقرار النهائي للتقييم. قيم PROCESS_RESULT_* (مثل APPROVED، AUTHENTICATED، NOT_APPROVED، ...). حاسم فقط عندما تكون state = PROCESS_STATE_FINISHED.
createdAtالطابع الزمني لإنشاء العملية (UTC).
finishedAtالطابع الزمني لاكتمال العملية (UTC).
personكائن فرعي يحتوي على بيانات الشخص الذي يجري التحقق منه.
purposeالغرض من العملية (مثل personAuthentication، تسجيل شخص).
servicesقائمة الخدمات الإضافية المرتبطة بالعملية؛ فارغة عند عدم وجودها.
authenticationInfo.​authenticationIdمعرّف حدث مصادقة الهوية الذي تم إنشاؤه بواسطة التدفق.
capacitiesالإمكانيات/المنتجات المستخدَمة. قيم PROCESS_CAPACITY_* (مثل IDCLOUDONE).
expiresAtالطابع الزمني لانتهاء صلاحية العملية/الرابط (UTC).
tokenرمز الجلسة/الوصول المرتبط بالعملية (قد يكون فارغًا).
companyDataكائن فرعي يحتوي على بيانات الشركة/المستأجر الذي يملك العملية.
simulatedقيمة منطقية؛ تحدد إذا كانت هذه عملية محاكاة/sandbox (true) أو عملية حقيقية (false).
حقول الشخص
الحقلالمعنى
duiTypeنوع وثيقة التعريف الفريدة. قيم DUI_TYPE_* (مثل BR_CPF).
duiValueقيمة الوثيقة (مثل رقم CPF).
friendlyNameاسم ودّي/لقب للشخص (نص حر، غير مُتحقَّق منه).
emailالبريد الإلكتروني للشخص؛ قد يكون فارغًا.
phoneرقم الهاتف بصيغة E.164 (رمز الدولة + رمز المنطقة + الرقم).
notificationsقائمة قنوات الإشعارات. يحمل كل عنصر notificationChannel بقيم NOTIFICATION_CHANNEL_* (مثل WHATSAPP، SMS، EMAIL).
phoneCountryCodeAlpha3رمز الدولة ISO alpha-3 لرقم الهاتف (مثل BRA)؛ قد يكون فارغًا.
حقول بيانات الشركة
الحقلالمعنى
branchIdمعرّف فرع المستأجر؛ فارغ عندما لا يكون التقسيم بحسب الفرع.
countryCodeدولة الشركة بصيغة ISO alpha-3 (مثل BRA).
أنواع الوثائق وحقول OCR

يُبلّغ process.services[].documents[].doc.code عن نوع الوثيقة بأحد شكلين. تحمل الوثائق التي تعالجها وحدة الوثائق في Unico، بما في ذلك الوثائق المُعاد استخدامها، رمزاً مختصراً بحروف كبيرة (CNH). وتحمل العمليات المُنشأة عبر API فقط عادةً نوع القاموس الكامل (unico.moja.dictionary.br.cnh.v2.Cnh)، لكنها قد تحمل أيضاً رمزاً مختصراً. تعامل مع الشكلين في أي مسار تكامل. لا يحمل الرمز المختصر الدولة أو إصدار المخطط؛ يُعاد الإصدار بشكل منفصل في doc.version.

في الشكل المختصر، يتم الإبلاغ عن أنواع الوثائق التي تستخدم المخطط الموحّد — unified_schema في مرجع الحقول — كمعرّف النوع بحروف كبيرة الذي تم تحديده خلال الالتقاط. القيم الأكثر شيوعاً هي IDCARD وDRIVERLICENSE وPASSPORT وVOTERID، لكن القائمة مفتوحة: تُعاد الأنواع الأخرى التي يتم تحديدها أثناء الالتقاط كما هي، بأحرف كبيرة. تعامل مع القيم خارج هذه القائمة. تحافظ جوازات السفر الأمريكية على نوعها الفرعي بدلاً من دمجها في PASSPORT: تُعاد أيضاً القيم POLYCARBONATEPASSPORT وPASSPORTCARD وPAPERPASSPORT وCONSULARPASSPORT وALIENPASSPORT وREFUGEEPASSPORT. على سبيل المثال، يتم الإبلاغ عن unico.moja.dictionary.ar.generic.v1.IdCard وunico.moja.dictionary.us.generic.v1.PolycarbonatePassport كـ IDCARD وPOLYCARBONATEPASSPORT.

المخططات الخاصة

يتم عرض أنواع الوثائق التي تستخدم مخطط حقول خاص بها — والمدرجة تحت specific_document_schemas في مرجع الحقول — في الجدول أدناه. استخدم نوع القاموس للبحث عن كل مخطط في ذلك الملف.

الدولةdoc.codeنوع القاموسالوثيقة
BRRGunico.​moja.​dictionary.​br.​rg.​v2.​RgRG
BRCNHunico.​moja.​dictionary.​br.​cnh.​v2.​CnhCNH (رخصة القيادة)
BRCINunico.​moja.​dictionary.​br.​cin.​v1.​CinCIN
BRPASSAPORTEunico.​moja.​dictionary.​br.​passaporte.​v1.​Passaporteجواز السفر
MXINEunico.​moja.​dictionary.​mx.​ine.​v1.​Ineبطاقة ناخب INE
MXLPCunico.​moja.​dictionary.​mx.​lpc.​v1.​LpcLicencia para conducir (رخصة القيادة)
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​Pasaporteجواز السفر
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​Unknownتعذّر تحديد النوع، أو نوع برازيلي أو مكسيكي بلا مخطط خاص به — doc.data فارغ

تستخدم الوثائق البرازيلية والمكسيكية المخططات الخاصة أعلاه فقط. يتم الإبلاغ عن أي وثيقة برازيلية أو مكسيكية من نوع آخر — على سبيل المثال، بطاقة إقامة مكسيكية — على أنها UNKNOWN، وليس بالمخطط الموحّد.

PASSAPORTE وPASAPORTE وثيقتان مختلفتان

جواز السفر البرازيلي هو PASSAPORTE (بحرفي S) والمكسيكي هو PASAPORTE (بحرف S واحد)، ويعكس كل منهما تهجئة القاموس الخاص به. هذا ليس خطأً مطبعيًا — لا تعامل القيمتين كمتكافئتين.

لا يتم إجراء أي استخراج OCR ولا يُبلَّغ عن أي حقل في doc.data عندما يكون doc.code هو UNKNOWN.

Brazilقد يستلم العملاء في البرازيل حمولة العملية الكاملة

يبقى الهيكل العام للاستجابة كما هو — النتيجة الواحدة هي الإعداد الافتراضي.

قد تستلم عمليات التكامل في البرازيل كائن العملية الكامل أدناه، مع نتائج لكل إمكانية في authenticationInfo.

{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"callbackUri": "https://example.com/callback",
"userRedirectUrl": "https://example.com/redirect",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_OK",
"createdAt": "2024-01-01T10:00:00Z",
"finishedAt": "2024-01-01T10:15:00Z",
"expiresAt": "2024-01-08T10:00:00Z",
"purpose": "VERIFICATION",
"clientReference": "client-ref-abc",
"useCase": "USE_CASE_LOGIN",
"capacities": ["liveness", "face_match"],
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "12345678909",
"friendlyName": "Luke Skywalker",
"notifications": [
{
"notificationChannel": "email"
}
]
},
"authenticationInfo": {
"authenticationId": "auth-123",
"livenessResult": "LIVENESS_RESULT_LIVE",
"authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
"identityFraudstersResult": "TRUST_RESULT_UNSPECIFIED",
"bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
"smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
"idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
"scoreEngineResult": {
"scoreEnabled": "SCORE_ENABLED_TRUE",
"score": 85.5
}
},
"companyData": {
"branchId": "branch-123",
"countryCode": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"code": "CNH",
"data": {
"numero": "044589731564",
"cpfNumero": "12345678909",
"nomeCivil": "Luke Skywalker",
"dataNascimento": "1990-05-12T00:00:00Z",
"dataExpiracao": "2027-12-07T00:00:00Z",
"categoria": "B"
}
}
}
]
}
]
}
}
الحقول ذات المستوى الأعلى
الحقلالنوعالوصف
process.idstring (UUID)معرّف العملية.
process.flowstringمعرّف التدفق المرسَل عند الإنشاء.
process.callbackUristringعنوان URL لإعادة الاتصال المهيّأ لأحداث العملية.
process.​userRedirectUrlstringعنوان URL لإعادة توجيه المستخدم بعد اكتمال الرحلة.
process.stateenumحالة العملية الحالية. راجع القيم أدناه.
process.resultenumنتيجة التحقق. موجودة فقط عندما تكون state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)طابع زمني بصيغة ISO 8601 لوقت إنشاء العملية.
process.finishedAtstring (datetime)طابع زمني بصيغة ISO 8601 لوقت اكتمال العملية. موجود فقط عندما تكون state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)طابع زمني بصيغة ISO 8601 لوقت انتهاء صلاحية العملية.
process.purposestringالغرض من العملية كما تم تهيئته في التدفق.
process.​clientReferencestringمرجع اختياري من جانب العميل للفهرسة في البوابة.
process.useCasestringمعرّف السيناريو المرتبط بالتدفق.
process.capacitiesarray of stringsقائمة الإمكانيات المفعّلة في هذه العملية.
process.tokenstringJWT موقّع لتكامل SDK.
process.personobjectبيانات التعريف المقدَّمة عند الإنشاء.
process.​person.​notificationsarrayقنوات الإشعارات المهيّأة للرحلة (مثل email).
process.​authenticationInfoobjectالنتائج لكل إمكانية. راجع أدناه.
process.companyDataobjectسياق الشركة والفرع.
process.​companyData.​branchIdstringمعرّف الفرع.
process.​companyData.​countryCodestringرمز الدولة ISO 3166-1 alpha-3 (مثلاً BRA).
process.​bioTokenDataobjectمعلومات العملية المرجعية — موجودة فقط في تدفقات التحقق 1:1 وإعادة التحقق الذكية.
process.servicesarrayالمغلّفات الموقَّعة، الوثائق المُلتقَطة، ومخرجات الخدمة الأخرى. راجع أدناه.
قيم process.state
القيمةالمعنى
PROCESS_STATE_CREATEDتم إنشاء العملية؛ لم يكمل المستخدم الرحلة بعد.
PROCESS_STATE_AWAITING_FOR_DOCUMENTتم إنشاء العملية بدون وثيقة تعريف. موجودة فقط عندما يسمح Custom Flow بوثيقة اختيارية. أرسل الوثيقة باستخدام تعيين وثيقة العملية.
PROCESS_STATE_FINISHEDاكتملت الرحلة. تحقق من result وauthenticationInfo.
PROCESS_STATE_FAILEDخطأ في المعالجة.
قيم process.result
القيمةالمعنى
PROCESS_RESULT_OKأعادت جميع الإمكانيات نتائج إيجابية.
PROCESS_RESULT_INVALID_IDENTITYأعادت إمكانية واحدة على الأقل نتيجة سلبية حاسمة (مثل فشل لايفنس، أو عدم تطابق الهوية).
PROCESS_RESULT_ERRORخطأ خلال معالجة النتيجة.
PROCESS_RESULT_EXPIREDانتهت صلاحية العملية قبل اكتمال الرحلة.
PROCESS_RESULT_UNSPECIFIEDلم تنتهِ العملية بعد.
نتائج الإمكانيات في authenticationInfo

يتم إعادة جميع الحقول دائمًا بغض النظر عن التدفق. تُعيد الحقول الخاصة بالإمكانيات غير المستخدَمة في التدفق القيمة *_UNSPECIFIED.

قيم تعداد مختصرة

القيم المختصرة (مثل livenessResult = LIVE، authenticationResult = INCONCLUSIVE) تُطابق مباشرة القيم الكاملة للتعداد الموثّقة هنا (LIVENESS_RESULT_LIVE، AUTHENTICATION_RESULT_INCONCLUSIVE، إلخ) — تم حذف البادئة لأجل الاختصار.

الحقلالإمكانيةالقيم الممكنة
authenticationId—معرّف فريد لمحاولة المصادقة هذه.
livenessResultلايفنسLIVENESS_RESULT_LIVE، LIVENESS_RESULT_NOT_LIVE، LIVENESS_RESULT_UNSPECIFIED
authenticationResultالتحقق من الهويةAUTHENTICATION_RESULT_POSITIVE، AUTHENTICATION_RESULT_NEGATIVE، AUTHENTICATION_RESULT_INCONCLUSIVE، AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResultتصنيف مخاطر الاحتيالTRUST_RESULT_YES، TRUST_RESULT_INCONCLUSIVE، TRUST_RESULT_UNSPECIFIED
bioTokenEngineResultالتحقق 1:1BIO_TOKEN_ENGINE_RESULT_POSITIVE، BIO_TOKEN_ENGINE_RESULT_NEGATIVE، BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResultإعادة التحقق الذكيةSMART_REVALIDATION_RESULT_POSITIVE، SMART_REVALIDATION_RESULT_NEGATIVE، SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResultالتحقق من العمرID_AGE_RESULT_POSITIVE، ID_AGE_RESULT_NEGATIVE، ID_AGE_RESULT_INCONCLUSIVE، ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.​scoreEnabledدرجة المخاطرSCORE_ENABLED_TRUE، SCORE_ENABLED_FALSE، SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.​scoreدرجة المخاطررقم من -100 إلى +100. موجود عندما تكون authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE ودرجة المخاطر مفعّلة.
serproResult.scoreتشابه Serpro0–100 (التشابه)؛ -1 (لا وجه مسجَّل لهذا CPF)؛ -2 (خطأ في التكامل).
deviceMetadataالبيانات الوصفية للجهازكائن يحتوي على status (found، not_found، unavailable) وبيانات الجهاز. غائب عندما لا تكون القدرة مفعّلة في التدفق.
حقول process.services
عنصر واحد لكل وحدة

تحتوي services على عنصر واحد لكل وحدة اكتملت في العملية: أحدث تشغيل مكتمل لكل وحدة، وفقط ما دامت العملية في الحالة PROCESS_STATE_FINISHED أو PROCESS_STATE_AWAITING_FOR_DOCUMENT. وتحمل العمليات المُنشأة عبر API فقط عنصر الوثيقة في أي حالة. يحمل عنصر التقاط الوثائق الحقلين documents وconsent_granted. ويحمل عنصر التوقيع الإلكتروني الحقلين envelope_id وdocument_ids. لا تحتوي العناصر على حقل نوع وترتيبها غير ثابت: حدّد كل عنصر من خلال مفاتيحه لا من خلال موضعه، وتجاهل العناصر التي لا تتعرّف عليها. المفاتيح بصيغة snake_case، باستثناء مفاتيح doc.data التي تتبع مخطط الوثيقة (مثلاً nomeCivil).

الحقلالنوعالوصف
consent_grantedbooleanعنصر التقاط الوثائق. ما إذا كان المستخدم قد منح موافقته على مشاركة الوثائق مع شركتك.
documentsarrayعنصر التقاط الوثائق. الوثائق المُلتقَطة مع بيانات OCR ونتائج التحقق.
documents[].doc_idstringمعرّف الوثيقة.
documents[].​share_idstringمعرّف المشاركة التي منحها المستخدم لشركتك في هذه العملية.
documents[].​typifiedbooleanما إذا تم تحديد نوع الوثيقة.
documents[].​cpf_matchbooleanالبرازيل فقط. ما إذا كان رقم CPF في الوثيقة يطابق رقم CPF المُرسَل عند الإنشاء. موجود دائماً للشركات التي تم تعيين بلدها على البرازيل؛ ويُحذف للدول الأخرى وللشركات التي لم يُعيَّن لها بلد.
documents[].​validate_docbooleanالبرازيل فقط. ما إذا اجتازت الوثيقة عملية التحقق من الوثائق لدى Unico. موجود دائماً للشركات التي تم تعيين بلدها على البرازيل (false عندما لا يُجرى التحقق)؛ ويُحذف للدول الأخرى وللشركات التي لم يُعيَّن لها بلد.
documents[].​face_matchboolean or nullما إذا كانت صورة السيلفي تطابق الصورة في الوثيقة. تعني القيمة null أن الفحص لم يُجرَ — وهي ليست نتيجة سلبية.
documents[].​verifiedboolean or nullتكون true فقط عندما يكون نوع الوثيقة معروفاً، ولم تُحذف الوثيقة، وتكون قيمة face_match هي true، واجتازت الوثيقة فحوصات الجودة. وتكون false في غير ذلك، بما في ذلك عندما لا يُجرى face_match. وتكون null عندما لا تمر العملية عبر وحدة الوثائق.
documents[].​reused_docbooleanما إذا تمت إعادة استخدام هذه الوثيقة من عملية سابقة.
documents[].​signed_urlstringعنوان URL موقَّع قصير الصلاحية لتنزيل صورة الوثيقة. تنتهي صلاحيته: لا تخزّنه ولا تعتمد على مدة صلاحية ثابتة، واستدعِ هذه النقطة النهائية مرة أخرى للحصول على عنوان جديد.
documents[].​doc.​versionintegerإصدار قاموس نوع الوثيقة (مثلاً 2 لـ unico.moja.dictionary.br.cnh.v2.Cnh).
documents[].​doc.​codestringنوع الوثيقة، كرمز مختصر (مثلاً CNH) أو كنوع القاموس الكامل (مثلاً unico.moja.dictionary.br.cnh.v2.Cnh). تحمل الوثائق التي تعالجها وحدة الوثائق الرمز المختصر. تعامل مع الشكلين. راجع أنواع الوثائق وحقول OCR للاطلاع على جميع القيم وكيفية اشتقاق الرمز.
documents[].​doc.​dataobjectحقول OCR المُستخرَجة. يختلف المحتوى بحسب نوع الوثيقة — راجع مرجع الحقول الكامل للاطلاع على الكتالوج الكامل. تتبع أسماء الحقول مخطط الوثيقة: البرتغالية للوثائق البرازيلية (مثلاً nomeCivil، dataNascimento)، والإسبانية للوثائق المكسيكية، والإنجليزية للمخطط الموحّد.
envelope_idstring (UUID)عنصر توقيع إلكتروني. معرّف المغلّف الموقَّع.
document_idsarray of stringsعنصر توقيع إلكتروني. معرّفات الوثائق في المغلّف.
العمليات المُنشأة عبر API فقط

في العملية المُنشأة عبر API فقط، يأتي عنصر الوثيقة من استدعاء API، لا من وحدة الوثائق في Unico، وتختلف بعض القيم عن الجدول أعلاه:

  • تكون قيمة consent_granted دائماً false: تجمع شركتك الموافقة، ولا تتتبّعها Unico.
  • يكون share_id وsigned_url فارغين.
  • تكون قيمة face_match دائماً true أو false، ولا تكون null أبداً.
  • تكون قيمة verified دائماً null.
  • تكون قيمة doc.version هي 0.
  • يحمل doc.code عادةً نوع القاموس الكامل (مثلاً unico.moja.dictionary.br.cnh.v2.Cnh)، لكنه قد يحمل رمزاً مختصراً.
  • تكون قيمة doc.data هي null عندما يتعذّر قراءة بيانات OCR.

رموز الأخطاء​

الرمزالرسالةالوصف
3process id is invalidعندما يكون معرّف العملية غير صالح.

الاستقصاء (Polling) مقابل webhook​

يمكنك استقصاء (poll) هذه النقطة النهائية للتحقق من التقدّم، ولكن النمط الموصى به هو الاشتراك في webhook واستخدام هذه النقطة النهائية فقط كخطة احتياطية. راجع Webhooks and Events.

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