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

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

تحذير

قبل استرداد العملية، راجع إعداد webhook والاستراتيجيات الاحتياطية — انقر هنا.

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

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

الطلب​

الترويسات
الترويسةالقيمة
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
  }
}
حقول العملية
الحقلالمعنى
idمعرّف العملية الفريد (UUID)؛ المفتاح المستخدم للاستعلام عن التدفق وتتبعه.
flowنوع الرحلة المنفَّذة (مثلاً id_r2، idlivetrust_r2، idtrust_r2، إلخ).
callbackUriعنوان URL للاستدعاء الذي يُعاد توجيه تطبيق العميل إليه في نهاية التدفق.
userRedirectUrlعنوان URL الكامل لصفحة CbU التي يفتحها المستخدم لتنفيذ الرحلة (يحمل id وعلامات السلوك).
stateحالة دورة حياة العملية. قيم PROCESS_STATE_* (مثلاً CREATED، FAILED، FINISHED، AWAITING_FOR_DOCUMENT، 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.moja.dictionary.br.cnh.v2.Cnh هي CNH. لا يحمل الرمز الدولة ولا إصدار المخطط؛ ويُعاد الإصدار بشكل منفصل في doc.version.

أنواع المستندات التي تستخدم المخطط الموحّد — unified_schema في مرجع الحقول — يتم الإبلاغ عنها بالنوع الذي تم تحديده أثناء الالتقاط بأحرف كبيرة: IDCARD أو DRIVERLICENSE أو PASSPORT أو VOTERID. تحتفظ جوازات السفر الأمريكية بنوعها الفرعي بدلاً من دمجها في PASSPORT، لذا تُعاد أيضاً قيم مثل POLYCARBONATEPASSPORT وPASSPORTCARD وPAPERPASSPORT. على سبيل المثال، يتم الإبلاغ عن 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 فارغ
PASSAPORTE وPASAPORTE مستندان مختلفان

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

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

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

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

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

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idchecktrust",
    "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": "smart_revalidation",
    "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_INCONCLUSIVE",
      "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": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "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-2.
process.bioTokenDataobjectمعلومات العملية المرجعية — موجودة فقط في تدفقات التحقق 1:1 وإعادة التحقق الذكية.
process.servicesarrayالمظاريف الموقّعة والمستندات الملتقطة ومخرجات الخدمات الأخرى. انظر أدناه.
قيم process.state
القيمةالمعنى
PROCESS_STATE_CREATEDتم إنشاء العملية؛ لم يكمل المستخدم الرحلة بعد.
AWAITING_FOR_DOCUMENTتم إنشاء العملية بدون مستند تعريف؛ في انتظار تعيينه عبر تعيين مستند العملية. موجود فقط عندما يسمح التدفق المخصص بمستند اختياري.
PROCESS_STATE_FINISHEDاكتملت الرحلة. تحقق من result وauthenticationInfo.
PROCESS_STATE_FAILEDخطأ في المعالجة.
عدم اتساق في التسمية

AWAITING_FOR_DOCUMENT لا يتبع اصطلاح البادئة PROCESS_STATE_* المستخدم في الحالات الأخرى. هذا عدم اتساق معروف في التسمية في API الحالي.

قيم 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 (خطأ في التكامل).
حقول process.services
اصطلاحات تسمية مختلطة في services

تستخدم مصفوفة services camelCase لحقول مستوى المغلف (envelopeId، documentIds) وsnake_case لحقول مستوى المستند (doc_id، consent_granted، face_match، إلخ). يعكس هذا استجابة API الفعلية — كلا الاصطلاحين مقصودان وليسا خطأ في التوثيق.

الحقلالنوعالوصف
envelopeIdstring (UUID)معرّف المظروف الموقّع.
documentIdsarray of stringsمعرّفات المستندات الملتقطة في هذه الخدمة.
consent_grantedbooleanما إذا كان المستخدم قد منح موافقة مشاركة البيانات.
documentsarrayالمستندات الملتقطة مع بيانات OCR ونتائج التحقق.
documents[].doc_idstringمعرّف المستند.
documents[].typifiedbooleanما إذا تم تحديد نوع المستند بنجاح.
documents[].cpf_matchbooleanما إذا كان CPF الموجود في المستند يتطابق مع CPF المقدم (البرازيل فقط).
documents[].face_matchbooleanما إذا كانت صورة السيلفي تتطابق مع الصورة الموجودة في المستند.
documents[].validate_docbooleanما إذا اجتاز المستند التحقق من الأصالة.
documents[].reused_docbooleanما إذا كان هذا المستند قد أُعيد استخدامه من عملية سابقة.
documents[].signed_urlstringعنوان URL موقّع مسبقاً لتنزيل ملف PDF للمستند (صالح لمدة 5 دقائق — أعد الجلب للتجديد).
documents[].doc.versionintegerإصدار مخطط OCR.
documents[].doc.codestringرمز قصير لنوع المستند (مثلاً CNH). راجع أنواع المستندات وحقول OCR للاطلاع على جميع القيم وكيفية اشتقاق الرمز.
documents[].doc.dataobjectحقول OCR المستخرجة. يختلف المحتوى حسب نوع المستند — انظر المرجع الكامل للحقول للاطلاع على الكتالوج الكامل. تُعاد أسماء الحقول داخل doc.data (مثلاً nomeCivil، dataNascimento) باللغة البرتغالية — وهذه هي القيم الفعلية التي ينتجها محرك OCR.

رموز الخطأ​

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

الاستقصاء مقابل webhook​

يمكنك استقصاء نقطة النهاية هذه للتحقق من التقدم، لكن النمط الموصى به هو الاشتراك في webhook واستخدام نقطة النهاية هذه كاحتياطي فقط. انظر Webhooks والأحداث.

ما التالي​

آخر تحديث في