إنشاء عمليةPOST

أنشئ عملية Human Token من الخادم الخلفي (back-end) الخاص بك واحصل على humanToken في data.humanToken.

Markdown

يعمل Human Token على نقطة النهاية POST /client/v1/process في Human API. مع تدفقات API Only (api+humantoken وapi+liveness+humantoken وapi+liveness+humantoken+revalidation)، تُنشأ العملية وتنتهي في استدعاء واحد: تحمل الاستجابة النتيجة بالفعل في data.humanToken. مع تدفقات Human Token Journey (humantoken وhumantoken+revalidation)، تحمل الاستجابة id العملية وtoken وlink الرحلة، وتتوفر النتيجة بعد أن يُكمل المستخدم الرحلة. تتطلب تدفقات +revalidation مصفوفة references تحتوي على humanToken تم الحصول عليه مسبقًا لإعادة التحقق.

التدفقات

يعمل Human Token وفق نموذجَي تكامل:

• API Only — يرسل الخادم الخلفي الخاص بك الصورة الشخصية في imageBase64.
• Human Token Journey — يمرّ المستخدم برحلة Unico على الويب ثم يعود إلى callbackUri الخاص بك.

Flow	Capabilities	Possible result	Integration components required	Example
api+humantoken	Human Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken	LivenessHuman Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	LivenessHuman Token	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb
humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb

نقطة النهاية

البيئة	الرابط
الإنتاج	POST https://humantoken.unico.app/client/v1/process

الطلب

Headers

Header	القيمة
x-unico-accesskey	<your_access_key> (راجع المصادقة)
Content-Type	application/json

معاملات الطلب (Body)

الحقل	النوع	مطلوب	الوصف
flow	string	نعم	تدفق Human Token: ‏api+humantoken أو api+liveness+humantoken أو api+liveness+humantoken+revalidation (API Only) أو humantoken أو humantoken+revalidation (Human Token Journey). راجع التدفقات.
imageBase64	string	API Only	الصورة الشخصية، تلتقطها الواجهة الأمامية (front-end) الخاصة بك وتُرسَل مباشرةً بترميز base64. بصيغة PNG أو JPEG أو WebP، بحد أقصى 800 KB. اتّبع معيار الالتقاط.
callbackUri	string	Human Token Journey	عنوان URL الذي يُعاد توجيه المستخدم إليه بعد انتهاء الرحلة.
companyBranchId	string	لا	معرّف الفرع. عند تقديمه، تستخدم العملية إعدادات الفرع المحدد.
references	array	تدفقات إعادة التحقق	مصفوفة من كائنات المرجع. مطلوبة لتدفقات +revalidation. يحتوي كل كائن على referenceType (REFERENCE_TYPE_HUMAN_TOKEN) وreferenceContent (قيمة humanToken التي تم الحصول عليها مسبقًا).

الاستجابات

200 OK

الحقل	النوع	الوصف
id	string (UUID)	معرّف العملية. استخدمه لاسترجاع العملية مجددًا عبر الحصول على العملية.
state	string	حالة العملية — راجع تفسير النتيجة. في تدفقات API Only فقط.
token	string	رمز العملية المُنشأة، يمكنك استخدامه لفتح تجربة Journey SDK. فقط في تدفقات Human Token Journey (humantoken، humantoken+revalidation).
link	string	عنوان URL لرحلة Human Token Journey: أرسِل المستخدم إليه. في تدفقات Human Token Journey فقط (humantoken، humantoken+revalidation).
data.​humanToken.​value	string	معرّف مستقر وغير شفاف للوجه (حتى 100 حرف). يُحلَّل الشخص ذاته دائمًا إلى القيمة نفسها. في تدفقات API Only فقط (بدون إعادة التحقق).
data.​humanTokenMatch	string	"true" إذا تطابقت الصورة الشخصية مع humanToken المُشار إليه، و"false" في حال عدم التطابق. في تدفق +revalidation API Only فقط.

تفسير النتيجة

state	المعنى	ما يجب فعله
PROCESS_STATE_FINISHED	data.humanToken.value غير فارغة: شخص حقيقي، مع Human Token.	ابحث عن value في سجلاتك: إن وُجدت، فهو مستخدم عائد أو تكرار محتمل؛ وإن لم توجد، فهو شخص جديد.
PROCESS_STATE_FINISHED	لا يوجد data.humanToken، أو value فارغة: غير حاسمة.	تعامل معها على أنها غير حاسمة. لا تخزّن value فارغة ولا تطابقها أبدًا؛ أعد محاولة العملية أو ارفضها، وفقًا لقواعد عملك.
PROCESS_STATE_FAILED	فشلت عملية التعرّف.	أعد محاولة العملية أو ارفضها، وفقًا لقواعد عملك.
PROCESS_STATE_CREATED	تم إنشاء العملية.	انتظر. استرجع النتيجة لاحقًا عبر الحصول على العملية.
PROCESS_STATE_CANCELED	أُلغيت العملية.	أنشئ عملية جديدة، إذا كان المستخدم لا يزال بحاجة إلى التحقق.

تحذير

تحقق دائمًا من أن data.humanToken.value ليست فارغة قبل استخدامها.

رموز الأخطاء

ملاحظة

لا يزال تأكيد رمز حالة HTTP الذي يُعاد عندما يكون مفتاح الوصول في الترويسة x-unico-accesskey مفقودًا أو غير صالح جاريًا. راجع المصادقة.

400 Bad Request

الرمز	الرسالة	الوصف
3	invalid flow	عندما لا يكون التدفق المحدد موجودًا.
3	INVALID_IMAGE	عندما لا تكون الصورة بترميز base64 صالح، أو تبدو كمحاولة حقن.
3	IMAGE_TOO_LARGE	عندما تتجاوز الصورة الحجم الأقصى البالغ 800 KB.
3	UNSUPPORTED_IMAGE_FORMAT	عندما لا تكون صيغة الصورة PNG أو JPEG أو WebP.
3	MISSING_IMAGE	عندما تكون الصورة مطلوبة لهذا التدفق ولم تُرسَل.
3	INVALID_REQUEST	عندما يكون جسم الطلب فارغًا (null) أو يتعذّر تفسيره.
9	monthly process limit of <monthly_limit> reached for this tenant	عند الوصول إلى حد الاستخدام الشهري.
9	PROCESS_FAILED	عندما تصل العملية إلى حالة فشل نهائية أثناء إنشائها.

403 Forbidden

الرمز	الرسالة	الوصف
7	PERMISSION_DENIED	عندما تكون بيانات الاعتماد صالحة لكنها غير مخوّلة بتنفيذ هذا الإجراء.

429 Too Many Requests

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

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

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

تحذير

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

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

500 Internal Server Error

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

للاطلاع على القائمة الكاملة لرموز نقطة النهاية هذه، راجع مرجع إنشاء عملية في Human API.

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

• احفظ قيمة humanToken إلى جانب سجل المستخدم لديك للتعرف على الشخص ذاته في استدعاءات Human Token اللاحقة.
• لاسترجاع العملية مجددًا، لأغراض التدقيق أو الدعم، استخدم الحصول على العملية.