---
title: إنشاء عملية
description: POST /v1/processes — الحقول المشتركة وحدود التحقق وحقول التدفق واستجابة 201 مع Human Token والمعلومات.
canonical: https://developer.unico.io/ar/human-plugin/api-reference/create-process
locale: ar
generated_by: markdown-export
---

# إنشاء عملية

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

`POST /v1/processes`

تبدأ عملية بأحد [التدفقات](#flows) وتردّ بـ `id` و`state` والنتيجة في `data`: Human Token و[معلومات](/ar/human-plugin/get-started/intelligence) الشخص، `data.ndocs`.

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

- Human Plugin قيد التشغيل و`GET /health/ready` يردّ بـ `200`.
- مفتاح الوصول لديك مفعَّل للـ[تدفق](#flows) الذي تستخدمه.
- إذا أرسلت وثيقة، فإن `type` الخاص بها موجود في [كتالوج السمات](/ar/human-plugin/additional-resources/attribute-catalog).

<a id="flows"></a>

## التدفقات

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

- **API Only**: ترسل واجهتك الخلفية السيلفي في `imageBase64`، ويردّ الإنشاء بالنتيجة.
- **Human Token Journey**: يلتقط الشخص السيلفي في رحلة الالتقاط ويعود إلى `callbackUri` الخاص بك. يردّ الإنشاء بـ `token` و`link`، وتقرأ النتيجة عبر [استرجاع عملية](/ar/human-plugin/api-reference/get-process).

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

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

## الطلب

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

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

| الحقل | مطلوب | الحد (بايت) | ملاحظات |
| --- | --- | --- | --- |
| `flow` | نعم | 64 | أحد [التدفقات](#flows) |
| `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` سيلفي أماميًا جيد الإضاءة لوجه واحد. تُرفَض أي قيمة ليست صورة، وتُخزَّن العملية كفاشلة: راجع [حالات رفض التدفق](#flow-refusals).

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

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

يُعاد `PROCESS_STATE_FINISHED` في الحالتين: اقرأ `humanTokenMatch`. راجع [استرجاع عملية](/ar/human-plugin/api-reference/get-process#finished-and-failed-processes).

يحجز 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>`.

```json
{
  "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` هي الحالة المحلية. راجع [دورة الحياة](/ar/human-plugin/api-reference/process-lifecycle).
- يردّ `humantoken` و`humantoken+revalidation` بـ `PROCESS_STATE_CREATED` مع `token` و`link`. يُعادان **مرة واحدة** ولا يُخزَّنان أبدًا: احتفظ بهما. راجع [Human Token Journey](/ar/human-plugin/integrations/human-token-journey) ودليل الالتقاط الخاص بمنصتك.
- `data.ndocs` هي معلومات الشخص. قد تكون غائبة: راجع [المعلومات](/ar/human-plugin/get-started/intelligence).

<a id="result"></a>

### النتيجة في `data`

تحتوي العملية المنتهية على هذه الحقول في `data`. تعيدها تدفقات Journey عندما [تقرأ العملية](/ar/human-plugin/api-reference/get-process) بعد الالتقاط.

| الحقل | متى | القيمة |
| --- | --- | --- |
| `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` | عند وجود معلومات عن الشخص | [معلومات](/ar/human-plugin/get-started/intelligence) الشخص |

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

```json
{
  "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` الخاصة بالتدفق | رفض التدفق الطلب، مثل صورة غير صالحة. راجع [حالات رفض التدفق](#flow-refusals) |
| 502 | `UPSTREAM_UNAVAILABLE` | تعذّر تأكيد العملية في الوقت المناسب |
| 503 | `DATABASE_UNAVAILABLE` | فشلت قاعدة البيانات. لم تُعالَج أي عملية |
| 500 | `INTERNAL` | خطأ غير متوقع |

<a id="flow-refusals"></a>

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

عندما يرفض تدفق ما الطلب، يردّ الإنشاء بـ `4xx` مع السبب في `message`، ضمن [الغلاف](/ar/human-plugin/api-reference/errors-and-retries) المعتاد. الأكثر شيوعًا:

| `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` جديد.

اقرأ [الأخطاء وإعادة المحاولة](/ar/human-plugin/api-reference/errors-and-retries) قبل إضافة منطق إعادة المحاولة: تحتاج المحاولة الجديدة إلى `correlationId` جديد.

## التالي

[استرجاع عملية](/ar/human-plugin/api-reference/get-process)