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

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

تحذير

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

نقطة النهاية

البيئة	الرابط
الإنتاج	GET https://api.id.unico.app/processes/v1/{processId}
Sandbox	GET https://api.id.uat.unico.app/processes/v1/{processId}

الطلب

الترويسات

الترويسة	القيمة
Authorization	Bearer <access_token>
APIKEY	مفتاح API المخصص.

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

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

مثال

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

الاستجابات

200 OK

التعاقد فريد — يحمل الحقل idCloud.result الحكم الموحّد للإمكانيات المستخدمة.

توحّد Unico نتائج الإمكانيات المنفّذة في idCloud.result واحد، جاهز لتحديد الخطوة التالية في تدفقك — دون الحاجة إلى تنسيق النتائج الفردية.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية.
status	integer	1 (قيد المعالجة)، 2 (تباين)، 3 (انتهت بنجاح)، 4 (ملغاة)، 5 (خطأ).

قيم النتيجة المحتملة

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

تعتمد القيم المُرجعة على الوصفة المكوّنة في APIKey الخاص بك. انظر التدفقات لمعرفة قيم النتيجة التي يمكن أن ترجعها كل وصفة.

قد يتلقى العملاء في البرازيل الاستجابة حسب الإمكانية

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

قد تتلقى عمليات التكامل في البرازيل النتائج المفتوحة لكل إمكانية على حدة. تضيف كل إمكانية مفعّلة في APIKey كتلتها الخاصة إلى الاستجابة — يتم حذف الحقول الخاصة بالإمكانيات غير المفعّلة.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1,
  "idAge": {
    "result": "yes"
  },
  "cardholderVerification": {
    "result": "approved"
  }
}

الحقل	النوع	الوصف
unicoId.result	string	yes، no، inconclusive — انظر التحقق من الهوية.
riskLevel.result	string	not_approved، critical_risk، high_risk، inconclusive — انظر تصنيف مخاطر الاحتيال.
idFace.result	string	FOUND — انظر معرّف الوجه.
idFace.personId	string	معرّف مستقر وغير شفاف للوجه، يُعاد جنبًا إلى جنب مع idFace.result = FOUND. عندما يتعذّر التعرف على أي وجه في الصورة، تُعيد العملية الخطأ 20532 بدلاً من كتلة idFace.
identityFraudsters.result	string	مهجور. استخدم riskLevel بدلاً منه. يمكن للعملاء الذين لديهم عمليات تكامل جارية الاستمرار في استخدامه أثناء تنسيق الترحيل مع فريق مشروعهم.
government.serpro	integer	درجة تشابه Serpro (0–100، ‎-1‎، ‎-2‎). متاح في البرازيل فقط. انظر عائد تشابه Serpro.
liveness	integer	1 (نجح)، 2 (فشل) — انظر لايفنس.
idAge.result	string	yes، no، inconclusive — انظر التحقق من العمر. متاح في البرازيل فقط.
score	integer	درجة مخاطر احتمالية. موجودة عندما تكون unicoId.result = inconclusive وتنسيق درجة المخاطر نشط. القيم الموجبة تشير إلى احتمالية أعلى لكون الشخص هو صاحب الحساب؛ القيم السالبة تشير إلى مخاطر أعلى. متاح في البرازيل فقط.
cardholderVerification.result	string	approved، unsure — انظر Cardholder Verification. غائب أثناء عدم بلوغ status قيمة 3 (منتهية) بعد. متاح في البرازيل فقط.

متى تستخدم نقطة النهاية هذه

تعاقد API يُرجع النتائج بشكل متزامن، لذا معظم عمليات التكامل لا تحتاج إلى نقطة النهاية هذه. استخدمها عندما:

• حفظت فقط processId وتحتاج إلى استرداد النتيجة الكاملة لاحقاً (تدقيق، دعم).
• تشك في أن الاستجابة الأصلية فُقدت أثناء النقل (خطأ في الشبكة بعد أن أكملت المنصة العمل).
• تقوم ببناء أداة مكتب خلفي تراجع العمليات التاريخية.

رموز الخطأ

400 Bad Request

الرمز	الرسالة	الوصف
20023	O parâmetro processId não foi informado.	معامل معرّف العملية مفقود.
20002	O parâmetro APIKey não foi informado.	معامل APIKEY مفقود من ترويسة الطلب.
20001	O parâmetro authtoken não foi informado.	معامل رمز التكامل مفقود من ترويسة الطلب.

404 Not Found

الرمز	الرسالة	الوصف
50001	O processo informado não foi encontrado.	العملية غير موجودة في قاعدة البيانات.

403 Forbidden

الرمز	الرسالة	الوصف
30017	User does not have permission to perform this action.	JWT غير صحيح أو مستخدم بدون صلاحية لتنفيذ هذه العملية.
10502	O token informado está expirado.	عندما تكون صلاحية رمز الوصول المستخدم قد انتهت.
10501	O token informado é inválido.	رمز المصادقة المُقدَّم غير صالح.
10201	O AppKey informado é inválido.	معامل APIKEY غير صالح أو غير موجود.

410 Gone

العملية موجودة لكنها أسفرت عن خطأ. تُرجع فقط id وstatus: 5.

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

تحذير

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

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

التدفقات

الوصفة هي مجموعة الإمكانيات (لايفنس، التحقق من الهوية، إشارات المخاطر، المستندات...) المكوّنة في APIKey الخاص بمشروعك. تحدد ما تنفذه Unico في كل عملية وكيف يتم توحيد النتائج في result واحد — لا تحتاج إلى تنسيق أي شيء من جانبك.

تحتفظ Unico بكتالوج من الوصفات المُعدّة مسبقاً، المسماة والمرقمة بالإصدار (مثلاً byunico-idlive-idunico-oneresponse-std). بعضها حصري للبرازيل، مثل تلك التي تتضمن Score أو Serpro أو التحقق من العمر.

ما هي الإمكانيات التي تُشغّل عمليتك؟

مجموعة الإمكانيات — تدفق مشروعك — مُحددة في إعدادات APIKey الخاص بك. راجع الوصفات المُعدّة مسبقاً أو تواصل مع مسؤول مشروع Unico لتخصيصها.