إنشاء عمليةPOST

ابدأ عملية واحصل على Human Token ومعلومات الشخص.

Markdown

POST /v1/processes

تبدأ عملية بأحد التدفقات وتردّ بـ id وstate والنتيجة في data: Human Token ومعلومات الشخص، data.ndocs.

قبل الاستدعاء

• Human Plugin قيد التشغيل وGET /health/ready يردّ بـ 200.
• مفتاح الوصول لديك مفعَّل للـتدفق الذي تستخدمه.
• إذا أرسلت وثيقة، فإن type الخاص بها موجود في كتالوج السمات.

التدفقات

يحدد الحقل flow ما تفعله العملية. يشغّل Human Plugin هذه التدفقات، ضمن نموذجَي تكامل:

• API Only: ترسل واجهتك الخلفية السيلفي في imageBase64، ويردّ الإنشاء بالنتيجة.
• Human Token Journey: يلتقط الشخص السيلفي في رحلة الالتقاط ويعود إلى callbackUri الخاص بك. يردّ الإنشاء بـ token وlink، وتقرأ النتيجة عبر استرجاع عملية.

Flow	Description	Possible result	Integration components required	Example
api+humantoken	يستقبل سيلفي عبر واجهتك الخلفية وينشئ Human Token، وهو معرّف وجه فريد. الاستجابة نهائية: لا التقاط ولا استدعاء ثانٍ.	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	يلتقط سيلفي في رحلة الالتقاط، مع فحص لايفنس، وينشئ Human Token. يعيد الإنشاء `token` و`link`؛ اقرأ النتيجة عند انتهاء الالتقاط.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	يلتقط سيلفي ويقارن الوجه بـ Human Token الذي تتوقعه. يعيد ما إذا كان الشخص نفسه أم لا، مثلًا قبل إجراء حساس.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId وcorrelationId وcredential هي نفسها في كل تدفق.

الطلب

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

الحقول المشتركة

الحقل	مطلوب	الحد (بايت)	ملاحظات
flow	نعم	64	أحد التدفقات
clientId	نعم	128	معرّفك للعميل. تحتسب المعلومات القيم المتمايزة
correlationId	نعم	128	مرجعك لهذه العملية. فريد: يُرفَض بالخطأ 409 أي معرّف تملكه عملية أخرى، أيًّا كانت حالتها
credential	نعم، لكن قد يكون فارغًا		يجب أن يكون المفتاح موجودًا. انظر أدناه
credential.type	عند وجود وثيقة		رمز من كتالوج السمات، دقيق وحساس لحالة الأحرف
credential.value	عند وجود وثيقة	64	رقم الوثيقة

يجب أن تكون flow وclientId وcorrelationId نصوصًا، بلا محارف تحكم وبلا مسافات في البداية أو النهاية. تُرفَض القيم غير الصالحة ولا يُعاد كتابتها أبدًا.

الحقل credential

• مع وثيقة: كائن يحتوي بالضبط على type وvalue، وكلاهما نص، يُرسَلان معًا.
• بدون وثيقة: null أو {}. تُحتسب العملية مع ذلك كمعاملة وكعميل في المعلومات.
• محذوف، أو كائن بقيم نصية فارغة: يُرفَض بالخطأ 400 MISSING_CREDENTIAL_TYPE. يكشف هذا المفتاح المكتوب بخطأ إملائي قبل معالجة أي شيء.
• أي مفتاح آخر داخل credential يُرفَض.

حقول التدفق

ما يضيفه كل تدفق إلى الحقول المشتركة:

الحقل	التدفق	مطلوب	القيمة
imageBase64	api+humantoken	نعم	السيلفي بصيغة base64. PNG أو JPEG أو WebP، حتى 800 KB
callbackUri	humantoken, humantoken+revalidation	نعم	المكان الذي يعود إليه الشخص عند انتهاء الالتقاط: صفحة تابعة لك، أو مخطط URL لتطبيقك
references	humantoken+revalidation	نعم	عنصر واحد يحمل Human Token الذي تتوقعه، كما في المثال أعلاه

لا يخزّن Human Plugin هذه الحقول، وقد يُتجاهَل حقل اختياري مكتوب بخطأ إملائي دون أي خطأ.

استخدم مع api+humantoken سيلفي أماميًا جيد الإضاءة لوجه واحد. تُرفَض أي قيمة ليست صورة، وتُخزَّن العملية كفاشلة: راجع حالات رفض التدفق.

مع humantoken+revalidation، تحتوي النتيجة على humanTokenMatch بدلًا من humanToken:

• "true": هو الشخص نفسه. تُحتسب العملية لهذا الشخص، ويصفه ndocs.
• أي قيمة أخرى، أو التقاط غير حي: لم يتأكد ذلك. لا تُحتسب العملية لأحد، ولا يوجد ndocs.

يُعاد PROCESS_STATE_FINISHED في الحالتين: اقرأ humanTokenMatch. راجع استرجاع عملية.

يحجز Human Plugin بعض الأسماء ويرفضها بالخطأ 400 INVALID_REQUEST، مثل clientReference. وكذلك أي تهجئة أخرى لحقول Human Plugin نفسها، مثل client_id أو correlation_id أو Flow: لا تُقرأ إلا flow وclientId وcorrelationId وcredential، مكتوبةً بهذا الشكل بالضبط.

قواعد الجسم

• كائن JSON واحد، بحد أقصى 2 MiB (يكفي تقريبًا لسيلفي بصيغة base64). يُرفَض الجسم الأكبر بالخطأ 400 REQUEST_TOO_LARGE.
• يجب ألا يأتي أي شيء بعد كائن JSON.

الاستجابة

201 Created، مع Location: /v1/processes/<id>.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id هو UUID الخاص بـ Human Plugin. كل طلب مقبول ينشئ معرّفًا جديدًا.
• state هي الحالة المحلية. راجع دورة الحياة.
• يردّ humantoken وhumantoken+revalidation بـ PROCESS_STATE_CREATED مع token وlink. يُعادان مرة واحدة ولا يُخزَّنان أبدًا: احتفظ بهما. راجع Human Token Journey ودليل الالتقاط الخاص بمنصتك.
• data.ndocs هي معلومات الشخص. قد تكون غائبة: راجع المعلومات.

النتيجة في data

تحتوي العملية المنتهية على هذه الحقول في data. تعيدها تدفقات Journey عندما تقرأ العملية بعد الالتقاط.

الحقل	متى	القيمة
humanToken	api+humantoken, humantoken	من هو الشخص: value هي Human Token، وstatus هي validated عند إنشائه
humanTokenMatch	humantoken+revalidation	"true" عندما يكون الشخص نفسه صاحب Human Token الموجود في references
liveness	التدفقات التي تفحص لايفنس، مثل تدفقات Journey	value هي live عندما يأتي الالتقاط من شخص حي، أو not_live عندما لا يكون كذلك؛ وstatus هي validated عند إجراء الفحص
ndocs	عند وجود معلومات عن الشخص	معلومات الشخص

تبدو نتيجة Journey هكذا:

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

تحقق من liveness قبل الوثوق بالنتيجة: مع not_live، اعتبر الالتقاط فاشلًا واطلب من الشخص المحاولة مجددًا. العملية ذات not_live لا تُحتسب ضمن معلومات أي شخص.

الأخطاء

الحالة	message	المعنى
400	INVALID_REQUEST, REQUEST_TOO_LARGE	ليس كائن JSON واحدًا، أو حقل محجوز، أو نوع خاطئ، أو جسم أكبر من 2 MiB
400	MISSING_<FIELD>, INVALID_<FIELD>	حقل مطلوب مفقود أو مشوَّه، مثل MISSING_CLIENT_ID
401	فارغة ("")	رفضت Unico مفتاح الوصول: مفقود أو خاطئ أو لم يعد صالحًا. تُخزَّن العملية كفاشلة. تحقق من HUMAN_API_ACCESS_KEY
409	CORRELATION_ID_ALREADY_USED	عملية أخرى تملك correlationId نفسه. لا يُخزَّن أو يُرسَل شيء
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type ليس في الكتالوج. لا يُخزَّن أو يُرسَل شيء
4xx	message الخاصة بالتدفق	رفض التدفق الطلب، مثل صورة غير صالحة. راجع حالات رفض التدفق
502	UPSTREAM_UNAVAILABLE	تعذّر تأكيد العملية في الوقت المناسب
503	DATABASE_UNAVAILABLE	فشلت قاعدة البيانات. لم تُعالَج أي عملية
500	INTERNAL	خطأ غير متوقع

حالات رفض التدفق

عندما يرفض تدفق ما الطلب، يردّ الإنشاء بـ 4xx مع السبب في message، ضمن الغلاف المعتاد. الأكثر شيوعًا:

message	السبب
invalid flow	flow ليس تدفقًا مفعَّلًا لحسابك
INVALID_IMAGE (400)	api+humantoken بدون imageBase64
INVALID_REQUEST (400)	imageBase64 ليست صورة بصيغة base64
IMAGE_TOO_LARGE	الصورة أكبر من 800 KB
UNSUPPORTED_IMAGE_FORMAT	الصورة ليست PNG أو JPEG أو WebP
PERMISSION_DENIED (403)	مفتاح الوصول لديك غير مفعَّل لهذا التدفق

تُخزَّن العملية المرفوضة كفاشلة. صحّح الطلب وأنشئ عملية جديدة بـ correlationId جديد.

اقرأ الأخطاء وإعادة المحاولة قبل إضافة منطق إعادة المحاولة: تحتاج المحاولة الجديدة إلى correlationId جديد.

التالي

استرجاع عملية