إنشاء عملية

MarkdownChatGPTClaude

تتعامل نقطة النهاية هذه مع ثلاثة منتجات تشترك في نفس المسار لكنها تختلف في معاملات الجسم والإمكانيات وحقول الاستجابة:

• التأهيل - يتحقق من هوية المستخدم عن طريق مقارنة وجهه مع قاعدة هويات Unico (مطلوب subject.duiType + subject.code).
• المعاملات - يتحقق من أنه نفس الشخص من عملية سابقة عن طريق مقارنة وجه بوجه (مطلوب referenceProcessId أو مصفوفة references مع صورة سيلفي / معرّف عملية).
• Cardholder Verification - يؤكد أن البطاقة تخص حاملها المُعلَن، دون أي التقاط لصورة سيلفي (مطلوب subject.code + card). يمكن اختيارياً إعادة استخدام عملية تم التحقق منها مسبقاً عبر referenceProcessId لتشغيل بوابة إعادة الاستخدام؛ بدونها، تُعيد الاستجابة تلقائياً النتيجة unsure. انظر إمكانية Cardholder Verification.

يتم تحديد المنتج النشط بواسطة APIKEY المرسل في ترويسة الطلب.

للاطلاع على تدفق التكامل الكامل، انظر نظرة عامة على API.

نقطة النهاية

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

الطلب

الترويسات

الترويسة	القيمة
Authorization	Bearer <access_token> (انظر المصادقة)
APIKEY	مفتاح API المخصص - يحدد المنتج النشط والإمكانيات المفعّلة.
Content-Type	application/json

معاملات الجسم

التأهيل

الحقل	النوع	مطلوب	الوصف
subject.duiType	integer	نعم	معرّف نوع الوثيقة. انظر قيم duiType أدناه.
subject.code	string	نعم	قيمة المعرف كما هو محدد بواسطة subject.duiType. بدون نقاط أو شرطات.
subject.name	string	لا	الاسم الكامل.
subject.gender	string	لا	M أو F.
subject.birthDate	string (ISO 8601)	لا	تاريخ الميلاد (YYYY-MM-DD).
subject.email	string	لا	عنوان البريد الإلكتروني.
subject.phone	string	لا	رقم هاتف E.164.
subject.clientReference	string	مشروط	المعرّف الفريد للمستخدم في نظامك. مطلوب لقدرة حسابات متعددة. فريد في قاعدتك، بحد أقصى 256 حرفاً وبدون مسافات.
useCase	string	لا	سياق العملية، مثلاً Onboarding.
subsidiaryId	string	لا	معرف الفرع — مطلوب فقط إذا كانت هناك فروع متعددة.
imageBase64	string	نعم	صورة سيلفي ملتقطة بواسطة واجهتك الأمامية، بتنسيق base64.

المعاملات

الحقل	النوع	مطلوب	الوصف
references	array	مشروط	مدخلات مرجعية لتدفقات التحقق 1:1. كل عنصر يحتوي على referenceType (REFERENCE_TYPE_IMAGE_BASE64 أو REFERENCE_TYPE_PROCESS_ID) وreferenceContent (صورة مشفرة بـ base64 أو UUID عملية).
referenceProcessId	string	مشروط	مهمل. استخدم references بدلاً منه. معرّف عملية التأهيل المرجعية للمقارنة معها. إذا كان المرجع عملية by-Unico، استخدم authenticationInfo.authenticationId.
imageBase64	string	نعم	صورة سيلفي ملتقطة بواسطة واجهتك الأمامية، بتنسيق base64.
subject	object	لا	حاوية معلومات المستخدم.
subject.duiType	string	لا	نوع المعرف. القيم المحتملة: DUI_TYPE_AR_DNI، DUI_TYPE_BR_CPF، DUI_TYPE_ID_NIK، DUI_TYPE_MX_CURP، DUI_TYPE_NG_NIN، DUI_TYPE_US_SSN.
subject.code	string	لا	قيمة المعرف كما هو محدد بواسطة subject.duiType. بدون نقاط أو شرطات.
subject.name	string	لا	الاسم الكامل للمستخدم.
subject.gender	string	لا	M أو F.
subject.birthDate	string (ISO 8601)	لا	تاريخ الميلاد (YYYY-MM-DD).
subject.email	string	لا	عنوان البريد الإلكتروني.
subject.phone	string	لا	رقم هاتف E.164.
useCase	string	لا	سياق العملية، مثلاً Transactional.
subsidiaryId	string	لا	معرّف الفرع - مطلوب فقط إذا كانت هناك فروع متعددة.

معلومة

لهذا المنتج، لا يمكن التنسيق مع درجة المخاطر. يتم دائماً إرجاع النتيجة بشكل متزامن في استجابة POST.

Cardholder Verification

الحقل	النوع	مطلوب	الوصف
subject.duiType	integer	نعم	معرّف نوع الوثيقة. انظر قيم duiType أدناه. حالياً DUI_TYPE_BR_CPF فقط.
subject.code	string	نعم	CPF حامل البطاقة الجاري التحقق منه. بدون نقاط أو شرطات.
card.bin	string	مشروط	أول 6 أو 8 أرقام من البطاقة (BIN). مطلوب مع card.last4.
card.last4	string	مشروط	آخر 4 أرقام من البطاقة. مطلوب مع card.bin.
card.name	string	لا	اسم حامل البطاقة كما هو مطبوع عليها.
referenceProcessId	string (UUID)	لا	معرّف عملية تم التحقق منها مسبقاً لإعادة استخدامها — عملية بها نتيجة معتمدة للتحقق من الهوية أو لايفنس لنفس CPF. النسخة الحالية من هذه القدرة تعتمد على إعادة الاستخدام: بدون هذا الحقل، لا يتم تشغيل البوابة أبداً وتُعيد الاستجابة تلقائياً النتيجة القياسية unsure — ولا يفشل الطلب نفسه أبداً.
useCase	string	لا	سياق العملية، مثلاً CardholderVerification.
subsidiaryId	string	لا	معرف الفرع — مطلوب فقط إذا كانت هناك فروع متعددة.

معلومة

لا يتم إرسال imageBase64 لهذا المنتج — يعمل Cardholder Verification بالكامل على الخادم (back-end)، دون أي خطوة لالتقاط صورة سيلفي.

قيم duiType

الدولة	الرمز	الوصف
AR	6	جواز سفر أرجنتيني
AR	7	DNI الأرجنتيني
AR	49	رخصة القيادة الأرجنتينية (Licencia Nacional de Conducir)
AT	34	الرقم الضريبي النمساوي (STNR)
BE	36	الرقم الوطني البلجيكي (NN)
BR	1	CPF البرازيلي
BR	5	جواز سفر برازيلي
BR	14	CNPJ البرازيلي
CA	28	SIN الكندي
CH	33	رقم AHV/AVS السويسري
CL	9	RUN التشيلي
CL	52	جواز سفر تشيلي
CL	57	رخصة القيادة التشيلية (Licencia de Conducir)
CO	26	NIT الكولومبي
CO	53	جواز سفر كولومبي
CO	55	رخصة القيادة الكولومبية (Licencia de Conducción)
CO	56	بطاقة المواطنة الكولومبية (Cédula de Ciudadanía)
DE	41	رقم التعريف الضريبي الألماني (IdNr)
DK	29	CPR الدنماركي
EC	10	NI الإكوادوري
ES	50	رقم هوية الأجانب الإسباني (NIE)
ES	51	وثيقة الهوية الوطنية الإسبانية (DNI)
FI	35	رمز الهوية الشخصية الفنلندي (HETU)
FR	46	الرقم الضريبي المرجعي الفرنسي (SPI)
GB	30	رقم التأمين الوطني البريطاني (NINO)
GT	12	CUI الغواتيمالي
ID	16	NIK الإندونيسي
IE	47	رقم الخدمة العامة الشخصي الأيرلندي (PPSN)
IT	37	Codice Fiscale الإيطالي (CF)
LU	48	رقم الهوية الوطني اللوكسمبورغي (Matricule)
MX	2	CURP المكسيكي
MX	25	RFC المكسيكي (شخص طبيعي)
MX	58	رخصة القيادة المكسيكية (Licencia de Conducir)
NG	8	NIN النيجيري
NG	20	رقم التحقق المصرفي النيجيري (BVN)
NG	43	رمز BVN النيجيري (مُجزّأ)
NG	44	رمز NIN النيجيري (مُجزّأ)
NL	42	رقم خدمة المواطن الهولندي (BSN)
NO	39	رقم الهوية الوطني النرويجي (Fødselsnummer)
PE	27	RUC البيروفي
PE	40	DNI البيروفي
PE	54	جواز سفر بيروفي
PL	31	PESEL البولندي
PT	45	رقم التعريف الضريبي البرتغالي (NIF)
SE	32	الرقم الشخصي السويدي (PNR)
SE	38	الرقم التنسيقي السويدي (Samordningsnummer)
TR	24	رقم الهوية التركي (TCKN)
US	4	SSN الأمريكي
US	11	جواز سفر أمريكي
US	18	رخصة قيادة أمريكية
US	21	بطاقة جواز سفر أمريكية
US	22	جواز سفر أمريكي مصنوع من البولي كاربونات
US	23	بطاقة هوية أمريكية
UY	13	CI الأوروغوياني
ZZ	15	عنوان البريد الإلكتروني
ZZ	17	رقم الهاتف
—	0	غير محدد
—	3	معرّف Unico الداخلي

متطلبات الصورة

• الدقة الدنيا: 640 × 480 (معيار HD)
• الحجم الأقصى للملف: 800 KB (يُنصح بضغط JPEG92)
• التنسيقات المقبولة: PNG، JPEG، WebP
• رموز JWT من SDK تنتهي صلاحيتها بعد 10 دقائق ويمكن استخدامها مرة واحدة فقط

الطلبات المضغوطة

تدعم API إرسال جسم الطلب مضغوطاً، باستخدام ترويسة HTTP القياسية Content-Encoding. هذا اختياري ومتوافق بالكامل مع الإصدارات السابقة: العملاء الذين لا يرسلون هذه الترويسة يستمرون في العمل تماماً كما كان الحال من قبل.

التنسيقات المدعومة

الترميز	ترويسة Content-Encoding	الحالة
Gzip	gzip	✅ مُوصى به
Deflate	deflate	✅ مدعوم
بدون ضغط	(الترويسة غير موجودة)	✅ مدعوم (السلوك الافتراضي)

توصية

استخدم gzip. فهو يحظى بالدعم الأكثر شمولاً عبر اللغات ومكتبات HTTP، مما يجنّبك الغموض في التنفيذ الموجود في التنسيقات الأخرى.

يُنصح باستخدام الضغط للطلبات التي تحتوي على جسم كبير (مثل حمولات JSON ضخمة، أو رفع صور مشفّرة بـ base64، أو إرسال دفعات). بالنسبة للطلبات الصغيرة، قد لا يحقق عبء الضغط فائدة ملموسة.

كيفية إرسال طلب مضغوط

1. اضغط جسم الطلب (مثل JSON المُسلسَل) باستخدام الخوارزمية المختارة.
2. أرسل الجسم المضغوط كبايتات ثنائية في الطلب.
3. أضف ترويسة Content-Encoding بالقيمة المطابقة (gzip أو deflate).
4. احتفظ بترويسة Content-Type لوصف تنسيق المحتوى الأصلي (مثلاً application/json)، وليس ترميز النقل.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

نصيحة

للمثال بلغة Python، استخدم معامل data=، وليس json=. معامل json= يُسلسل الحمولة تلقائيًا لكنه لا يضغطها.

استخدام deflate بدلاً من ذلك: التدفق أعلاه مطابق تمامًا — يتغير فقط استدعاء الضغط وقيمة Content-Encoding.

اللغة	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (من qpdf)، ثم -H "Content-Encoding: deflate"
Python	zlib.compress(data) بدلاً من gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream بدلاً من GZipStream

deflate غامض في الممارسة العملية

يُحدَّد ترميز المحتوى deflate في HTTP على أنه تدفق zlib (RFC 1950)، لكن بعض العملاء والخوادم تاريخيًا تُصدر أو تتوقع تدفق DEFLATE الخام (RFC 1951) بدلاً من ذلك. تتوقع هذه الواجهة البرمجية (API) تدفق zlib القياسي المُغلَّف — وهو نفس الناتج الذي تُنتجه zlib.compress() (بايثون) أو DeflateStream (.NET) بشكل افتراضي. عند الشك، يُفضَّل استخدام gzip، الذي لا يحمل هذا الغموض.

سلوك الخطأ

إذا تم إرسال Content-Encoding بقيمة غير مدعومة، أو كان الجسم تالفاً أو غير صالح للترميز المُعلن، تُعيد API الخطأ 400 Bad Request مع رسالة تشير إلى فشل فك ضغط جسم الطلب.

الأسئلة الشائعة

هل يتعين علي تغيير أي شيء إذا لم أرغب في استخدام الضغط؟ لا. دعم Content-Encoding إضافي — تستمر معالجة الطلبات التي لا تحتوي على هذه الترويسة بشكل طبيعي.

هل يؤثر هذا على استجابة API؟ لا. تتعلق هذه الميزة فقط بالجسم المُرسل من العميل (الطلب). ضغط الاستجابة (ما تُعيده API) يُتحكم فيه بشكل منفصل بواسطة ترويسة Accept-Encoding.

ما التنسيق الذي يجب أن أختاره؟ استخدم gzip، إلا إذا كان هناك قيد معين في بيئتك يتطلب تنسيقاً آخر.

مثال

التأهيل - cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

التأهيل - Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

المعاملات - cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

المعاملات - Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Cardholder Verification - cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification - Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

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 (قيد المعالجة)، 3 (انتهت بنجاح)، 5 (خطأ).

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

idCloud.result	المعنى	الإجراء الموصى به
approved	شخص حقيقي وهوية تم التحقق منها.	تابع التدفق.
denied	لم يتم التحقق من الهوية، فشل فحص لايفنس، أو تم تحديد مخاطر شديدة.	أنهِ التدفق أو أعد التوجيه إلى تدفق بديل.
critical-risk	تم تحديد مستوى مخاطر حرج.	أنهِ التدفق أو وجّهه إلى مراجعة يدوية.
high-risk	تم تحديد مستوى مخاطر مرتفع.	وجّه إلى مراجعة يدوية أو تدفق بديل.
retry	التقاط أو درجة غير كافية للتقييم.	اطلب من المستخدم التقاطاً جديداً.
inconclusive	لا يوجد دليل كافٍ لإصدار حكم.	وجّه إلى مراجعة يدوية أو تدفق بديل.

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

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

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

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

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

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

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

الحقل	النوع	الوصف
unicoId.result	string	yes، no، inconclusive - انظر التحقق من الهوية.
riskLevel.result	string	approved، reproved، risk-critical، risk-high، 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 (فشل) - انظر لايفنس.

riskLevel.result — القيم المحتملة

القيمة	المعنى
approved	هذا هو وجه صاحب الهوية، ولم يتم العثور على أي دليل يتعلق بالاحتيال.
reproved	يُوصى بالرفض، إذ تم اكتشاف مؤشرات احتيال متعددة.
risk-critical	يُوصى بالرفض، غير أن القرار النهائي يعود إلى تقديركم. تشير المخاطرة الحرجة إلى وجود ما لا يقل عن دليلين قويين على الاحتيال.
risk-high	يُوصى بالرفض أيضاً، لكن القرار يبقى بيدكم. تشير المخاطرة العالية إلى وجود دليل قوي واحد على الأقل على الاحتيال.
inconclusive	لم يتم العثور على أدلة قوية على الاحتيال، وبالتالي لا يمكن استنتاج ما إذا كانت هناك مخاطرة ذات صلة أم لا.

معلومة

عندما يكون unicoId.result = inconclusive وتنسيق درجة المخاطر نشط، قد تُرجع العملية status: 1 (قيد المعالجة). استعلم عبر الحصول على العملية أو استخدم webhooks لاسترداد النتيجة النهائية.

قد يتلقى العملاء في المكسيك كتلة التحقق من RENAPO

تحتفظ الاستجابة بالهيكل نفسه وتضيف كتلة idGov.

تتلقى عمليات التكامل في المكسيك التي فُعّل فيها التحقق من RENAPO كتلة idGov إضافية تتضمن السجل الذي تحتفظ به RENAPO لـ CURP الخاص بالمستخدم. وهي إجابة منفصلة عن نتيجة الهوية.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

الحقل	النوع	الوصف
idGov	object	سجل RENAPO لـ CURP. غائب عندما لا تكون القدرة مفعّلة. {} عندما لا تستجيب RENAPO. المكسيك فقط. انظر التحقق من RENAPO.

المعاملات

200 OK

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

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

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

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

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

idCloud.result	المعنى	الإجراء الموصى به
approved	شخص حقيقي وهوية تم التحقق منها.	تابع التدفق.
denied	لم يتم التحقق من الهوية، فشل فحص لايفنس، أو تم تحديد مخاطر شديدة.	أنهِ التدفق أو أعد التوجيه إلى تدفق بديل.
critical-risk	تم تحديد مستوى مخاطر حرج.	أنهِ التدفق أو وجّهه إلى مراجعة يدوية.
high-risk	تم تحديد مستوى مخاطر مرتفع.	وجّه إلى مراجعة يدوية أو تدفق بديل.
retry	التقاط أو درجة غير كافية للتقييم.	اطلب من المستخدم التقاطاً جديداً.
inconclusive	لا يوجد دليل كافٍ لإصدار حكم.	وجّه إلى مراجعة يدوية أو تدفق بديل.

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

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

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

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

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

الحقل	النوع	الوصف
biometryToken.result	boolean	true إذا تطابق الوجه المقدم مع العملية المرجعية؛ false خلاف ذلك.
liveness	integer	1 (نجح)، 2 (فشل) - انظر لايفنس.

Cardholder Verification

200 OK

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

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية.
status	integer	1 (قيد المعالجة)، 3 (انتهت بنجاح)، 5 (خطأ). لجميع القيم، انظر الحصول على العملية.
cardholderVerification.result	string	approved — تنتمي CPF والبطاقة إلى نفس الشخص. unsure — إما أن بوابة إعادة الاستخدام لم تُستوفَ، أو أن التحقق نفسه كان غير قاطع. غائب أثناء عدم بلوغ status قيمة 3 بعد. انظر Cardholder Verification.

رموز الخطأ

400 Bad Request

الرمز	الرسالة	الوصف
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	تم رفض تدفق إعادة الاستخدام (referenceProcessId/bioTokenId، بدون صورة) لأن إعادة استخدام العملية غير مفعّلة لهذا مفتاح API.
20900	O base64 informado não é válido.	معامل base64 غير صالح. الأسباب المحتملة: ليس صورة أو محاولة حقن.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	دقة الصورة المرفوعة منخفضة جداً.
20532	No face detected in image.	تعذّر اكتشاف أي وجه في الصورة المرسلة.
20513	The referenced process was not found.	يشير referenceProcessId إلى عملية غير موجودة أو لم تعد متاحة.
20512	The referenced process is not available for reuse.	العملية المرجعية موجودة لكنها غير متاحة لإعادة الاستخدام.
20509	The subject.name field is invalid.	يحتوي subject.name على أحرف غير صالحة.
20508	The subject.gender field is invalid.	يجب أن يكون subject.gender هو M أو F.
20507	O parâmetro subject.code é inválido.	CPF غير قياسي أو غير موجود.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	حجم الصورة يتجاوز 800 KB؛ اضغط إلى JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	تنسيق base64 غير صالح أو غير مدعوم.
20065	The referenceProcessId field is invalid.	referenceProcessId ليس UUID صالحاً.
20062	The useCase field is invalid.	قيمة غير معروفة في حقل useCase.
20024	The referenceProcessId field is missing.	لم يتم تقديم معامل referenceProcessId ولم يتم إرسال references كبديل. لا ينطبق على Cardholder Verification — لا يتم أبداً التحقق من referenceProcessId فيها كحقل مطلوب؛ بوابة إعادة استخدام غير مستوفاة تُجيب بـ unsure عوضاً عن ذلك.
20533	The card field is missing.	Cardholder Verification: لم يتم تقديم كائن card.
20534	The card.bin field is missing.	Cardholder Verification: لم يتم تقديم card.bin.
20535	The card.last4 field is missing.	Cardholder Verification: لم يتم تقديم card.last4.
20536	The card data is invalid.	Cardholder Verification: تم رفض بيانات البطاقة باعتبارها غير صالحة.
20021	The subject.phone field is invalid.	تنسيق subject.phone غير صالح (IDD + رمز المنطقة + الرقم، 13 حرف).
20019	The subject.birthDate field is invalid.	subject.birthDate خارج تنسيق ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	معامل صورة السيلفي مفقود.
20008	The subject.email field is invalid.	تنسيق بريد إلكتروني غير صالح في subject.email.
20006	O parâmetro subject.name não foi informado.	معامل subject.name مفقود.
20005	O parâmetro subject.code não foi informado.	معامل subject.code مفقود.
20004	O parâmetro subject não foi informado.	معامل subject مفقود.
20003	The request body is missing or invalid.	حمولة فارغة أو غير صالحة.
20002	O parâmetro APIKey não foi informado.	معامل APIKEY مفقود من ترويسة الطلب.
20001	O parâmetro authtoken não foi informado.	معامل رمز التكامل مفقود من ترويسة الطلب.
10508	The JWT with the captured face has already been used.	يمكن استخدام JWT مرة واحدة فقط.
10507	The JWT with the captured face is expired.	انتهت صلاحية JWT؛ يجب إرساله خلال 10 دقائق.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 ليس JWT صالحاً تم إنشاؤه بواسطة SDK.

403 Forbidden

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

الرمز	الرسالة	الوصف
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 غير صالح أو غير موجود.

409 Conflict

الرمز	الرسالة	الوصف
20073	The processID already exists.	processId المقدم موجود بالفعل لهذا المستأجر.

429 Too Many Requests

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

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

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

تحذير

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

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

500 Internal Server Error

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

ما التالي

• للاستعلام عن نتيجة عملية التأهيل، انظر الحصول على العملية.
• للاطلاع على جميع تركيبات الوصفات وقيم النتيجة المحتملة لكل منها، انظر التدفقات.
• لعمليات المستندات والتحقق من العمر، انظر الصفحات المعنية في هذا القسم.