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

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

MarkdownChatGPTClaude
تحذير

قبل استرجاع العملية، راجع تهيئة 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، 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

يتم الإبلاغ عن أنواع الوثائق التي تستخدم المخطط الموحّد — 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.

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

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

يتم عرض أنواع الوثائق التي تستخدم مخطط حقول خاص بها — والمدرجة تحت 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": "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": "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تم إنشاء العملية بدون وثيقة تعريف. موجودة فقط عندما يسمح Custom Flow بوثيقة اختيارية. أرسل الوثيقة باستخدام تعيين وثيقة العملية.
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عندما يكون معرّف العملية غير صالح.

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

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

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

آخر تحديث في