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

تحذير

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

في عقد API، تُعدّ استجابة POST /processes/v1 بالفعل النتيجة النهائية. توجد هذه النقطة النهائية لإعادة الاستعلام — على سبيل المثال، عندما تحتاج إلى فحص عملية حفظتها مسبقاً، أو مراجعة معاملة سابقة. في تعاقد API، استجابة POST /processes/v1 هي بالفعل النتيجة النهائية. نقطة النهاية هذه موجودة لإعادة الاستعلام - على سبيل المثال، عندما تحتاج إلى فحص عملية قمت بحفظها مسبقاً، أو مراجعة معاملة سابقة.

نقطة النهاية

البيئة	الرابط
الإنتاج	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

{
  "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
}

تعتمد حقول الاستجابة على مفتاح APIKey الخاص بك

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

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

400 Bad Request

معامل المسار processId مفقود أو غير صحيح. انظر رموز الخطأ أدناه.

403 Forbidden

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

404 Not Found

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

410 Gone

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

429 Too Many Requests

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

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

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

تحذير

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

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

500 Internal Server Error

خطأ غير متوقع في الخادم.

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

تعاقد 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.

500 Internal Server Error

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