الحصول على العملية

تحذير

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

نقطة النهاية

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

الطلب

الترويسات

الترويسة	القيمة
`Authorization`	`Bearer <access_token>`

معاملات المسار

المعامل	النوع	مطلوب	الوصف
`processId`	string (UUID)	نعم	معرّف العملية الذي تُعيده إنشاء عملية.

مثال

cURL
Node.js

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

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();

الاستجابات

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "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.id`	string (UUID)	معرّف العملية.
`process.flow`	string	معرّف التدفق المُرسَل عند الإنشاء.
`process.callbackUri`	string	عنوان URL الخاص بالاستدعاء المُهيَّأ لأحداث العملية.
`process.userRedirectUrl`	string	عنوان URL لتحويل المستخدم بعد اكتمال الرحلة.
`process.state`	enum	الحالة الراهنة للعملية. انظر القيم أدناه.
`process.result`	enum	نتيجة التحقق. تظهر فقط عندما تكون `state = PROCESS_STATE_FINISHED`.
`process.createdAt`	string (datetime)	الطابع الزمني بتنسيق ISO 8601 عند إنشاء العملية.
`process.finishedAt`	string (datetime)	الطابع الزمني بتنسيق ISO 8601 عند اكتمال العملية. يظهر فقط عندما تكون `state = PROCESS_STATE_FINISHED`.
`process.expiresAt`	string (datetime)	الطابع الزمني بتنسيق ISO 8601 عند انتهاء صلاحية العملية.
`process.purpose`	string	الغرض من العملية كما هو مُهيَّأ في التدفق.
`process.clientReference`	string	مرجع اختياري من جانب العميل للفهرسة في البوابة.
`process.useCase`	string	معرّف حالة الاستخدام المرتبطة بالتدفق.
`process.capacities`	array of strings	قائمة القدرات المُفعَّلة في هذه العملية.
`process.token`	string	JWT موقَّع لتكامل SDK.
`process.person`	object	بيانات التعريف المقدَّمة عند الإنشاء.
`process.person.notifications`	array	قنوات الإشعارات المُهيَّأة للرحلة (مثل `email`).
`process.authenticationInfo`	object	نتائج كل قدرة على حدة. انظر أدناه.
`process.companyData`	object	سياق الشركة والفرع.
`process.companyData.branchId`	string	معرّف الفرع.
`process.companyData.countryCode`	string	رمز الدولة بتنسيق ISO 3166-1 alpha-2.
`process.bioTokenData`	object	معلومات العملية المرجعية — تظهر فقط في تدفقات التحقق 1:1 وإعادة التحقق الذكية.
`process.services`	array	المغلفات الموقَّعة والوثائق الملتقَطة ومخرجات الخدمات الأخرى. انظر أدناه.

قيم 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.

الأشكال المختصرة لقيم enum

تُعيَّن القيم المختصرة (مثل livenessResult = LIVE، authenticationResult = INCONCLUSIVE) مباشرةً إلى قيم enum الكاملة الموثقة هنا (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:1	`BIO_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`	عائد تشابه Serpro	`0`–`100` (التشابه)؛ `-1` (لا يوجد وجه في الملف لهذا الرقم)؛ `-2` (خطأ في التكامل).

حقول process.services

الحقل	النوع	الوصف
`envelopeId`	string (UUID)	معرّف المغلف الموقَّع.
`documentIds`	array of strings	معرّفات الوثائق الملتقَطة في هذه الخدمة.
`consent_granted`	boolean	ما إذا كان المستخدم قد منح موافقته على مشاركة البيانات.
`documents`	array	الوثائق الملتقَطة مع بيانات OCR ونتائج التحقق.
`documents[].doc_id`	string	معرّف الوثيقة.
`documents[].typified`	boolean	ما إذا تم التعرف بنجاح على نوع الوثيقة.
`documents[].cpf_match`	boolean	ما إذا كان الرقم الضريبي على الوثيقة يطابق الرقم المُقدَّم.
`documents[].face_match`	boolean	ما إذا كانت الصورة الشخصية تطابق الصورة على الوثيقة.
`documents[].validate_doc`	boolean	ما إذا كانت الوثيقة قد اجتازت التحقق من الأصالة.
`documents[].reused_doc`	boolean	ما إذا كانت هذه الوثيقة مُعادة الاستخدام من عملية سابقة.
`documents[].signed_url`	string	رابط URL موقَّع مسبقًا لتنزيل ملف PDF للوثيقة (صالح لمدة 5 دقائق — أعد الاسترداد للتجديد).
`documents[].doc.version`	integer	إصدار مخطط OCR.
`documents[].doc.code`	string	رمز نوع الوثيقة (مثل `CNH`، `RG`).
`documents[].doc.data`	object	حقول OCR المستخرجة. يتفاوت المحتوى حسب نوع الوثيقة والبيانات المتاحة.

400 Bad Request

المعامل processId في المسار مفقود أو غير صحيح.

401 Unauthorized

رمز Bearer مفقود أو منتهي الصلاحية أو غير صالح.

404 Not Found

المعامل processId غير موجود أو لا ينتمي إلى المستأجر الذي تم المصادقة له.

429 Too Many Requests

تم الوصول إلى حد معدل الطلبات.

رموز الخطأ

400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

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

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

الرمز	الرسالة	الوصف
`5`	error getting process: rpc error: code = NotFound desc = process not found	عندما لا يُعثر على معرّف العملية.

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

الاستطلاع مقابل webhook

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

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

للاطلاع على الصورة الشخصية الملتقَطة، راجع الحصول على الصورة الشخصية.
للاطلاع على حزمة مراجعة الأدلة، راجع الحصول على مجموعة الأدلة.

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

الطلب​

مثال​

الاستجابات​

رموز الخطأ​

الاستطلاع مقابل webhook​

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