الانتقال إلى المحتوى الرئيسي

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

تحذير

قبل استرداد العملية، راجع إعداد 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": "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، RG).
documents[].doc.dataobjectحقول OCR المستخرجة. يختلف المحتوى حسب نوع المستند والبيانات المتاحة. تُعاد أسماء الحقول داخل doc.data (مثلاً nomeCivil، dataNascimento) باللغة البرتغالية — وهذه هي القيم الفعلية التي ينتجها محرك OCR.
400 Bad Request

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

401 Unauthorized

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

404 Not Found

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

429 Too Many Requests

تم الوصول إلى حد المعدل. عندما يتلقى نظامك خطأ HTTP 429، يجب عليك تنفيذ آليات لمنع الأعطال المتتالية وتجنب تفاقم القيود.

أفضل الممارسات:

  • فترة التهدئة (backoff): أوقف أو قلل الطلبات اللاحقة من نظامك فوراً. لا تعيد محاولة الطلبات الفاشلة باستمرار في حلقة ضيقة.
  • التخزين المؤقت وتنظيم المعدل: قم بتخزين الطلبات الصادرة مؤقتاً أو وضعها في قائمة انتظار للتحكم في تدفق حركة المرور قبل إعادة إرسالها.
  • التراجع الأسي مع التشتيت: عند إعادة المحاولة، قم بزيادة وقت الانتظار بشكل أسي بين المحاولات (مثلاً 1 ث، 2 ث، 4 ث، 8 ث) وأضف تأخيراً عشوائياً صغيراً ("تشتيت") لمنع تأثير القطيع حيث تعيد جميع الطلبات المؤجلة المحاولة في نفس الميلي ثانية بالضبط.
تحذير

الاستمرار في الوصول إلى نقطة نهاية محدودة المعدل دون تراجع يمكن أن يطيل فترة التقييد ويؤثر بشدة على الإنتاجية التشغيلية لنظامك. تنظيم الطلبات بشكل صحيح من جانبك يضمن تكاملاً أكثر سلاسة ومرونة.

للحدود الافتراضية وزيادة الطلبات والتفاصيل الإضافية، انظر حدود المعدل.

رموز الخطأ​

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

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

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

ما التالي​

آخر تحديث في