---
title: دمج الواجهة الخلفية
description: كيف يجب أن تستدعي خدمة في الواجهة الخلفية Human Plugin — ما الذي يجب تخزينه، وكيفية الاستعلام الدوري، وكيفية قراءة النتيجة، وكيفية التعامل مع الإخفاقات.
canonical: https://developer.unico.io/ar/human-plugin/integrations/backend
locale: ar
generated_by: markdown-export
---

# دمج الواجهة الخلفية

قائمة التحقق لاستدعاء Human Plugin من خدمة على جانب الخادم.

صُمّم Human Plugin ليُستدعى من الواجهة الخلفية لديك فقط. لا تعرضه للمتصفحات أو تطبيقات الجوال: فهو لا يملك مصادقة للطلبات الواردة.

## 1. الإنشاء

### curl

```bash
curl -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "onboarding-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'
```

### Node.js

```javascript
const response = await fetch(`${process.env.HUMAN_PLUGIN_URL}/v1/processes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flow: 'api+humantoken',
    clientId: 'client-a',
    correlationId: 'onboarding-001',
    credential: { type: 'DUI_TYPE_NG_BVN', value: documentNumber },
    imageBase64,
  }),
  signal: AbortSignal.timeout(60_000),
});

const body = await response.json();
if (response.status !== 201) {
  // body is { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;
```

اضبط مهلة العميل على **60 ثانية على الأقل**: فقد يستغرق الإنشاء حتى 30 ثانية للمعالجة، إضافةً إلى خطوات قاعدة البيانات. يأتي `id` في استجابة الإنشاء فقط، لذلك قد يفقد العميل الذي يتخلى مبكرًا عملية تكتمل لاحقًا.

## 2. احتفظ بما ستحتاجه لاحقًا

| احتفظ بـ | السبب |
| --- | --- |
| `id` | المعرّف المستخدم في `GET` |
| `token` و`link` الخاصان بـ Journey، إن وُجدا | يُعادان فقط في استجابة الإنشاء، ولا يخزّنهما Human Plugin أبدًا |
| `correlationId` الخاص بك | يجب أن يكون فريدًا. أنشئ معرّفًا جديدًا لكل محاولة، بما في ذلك إعادة المحاولة، إلا بعد الخطأ `503` |

## 3. اقرأ النتيجة

1. إذا كانت `state` هي `PROCESS_STATE_FINISHED`، فاقرأ النتيجة من `data`: `humanToken` (أو `humanTokenMatch` في إعادة التحقق) و`liveness` و`ndocs`. الاكتمال لا يعني الموافقة.
2. إذا كانت `state` هي `PROCESS_STATE_CREATED`، فاستعلم دوريًا عن `GET /v1/processes/{id}` مع تأخير تصاعدي حتى تتغير. لا شيء آخر يقدّم العملية.
3. إذا كانت `state` هي `PROCESS_STATE_FAILED`، فقد انتهت العملية دون نتيجة. ابدأ عملية جديدة إن كان تدفقك يسمح بذلك.

## 4. استفد من الذكاء

يخبرك `data.ndocs` بما فعله الشخص معك: مع كم من عملائك ومستنداتك ظهر، ومتى. استخدمه في قرارك مع Human Token، وتذكّر أنه قد يكون غائبًا. راجع [الذكاء](/ar/human-plugin/get-started/intelligence).

## 5. التعامل مع الإخفاقات

- لا تعد محاولة `500` أو `502` عند الإنشاء تلقائيًا. راجع [الأخطاء وإعادة المحاولة](/ar/human-plugin/api-reference/errors-and-retries).
- أعد محاولة `503` عند الإنشاء بنفس `correlationId`، وأي إخفاق في `GET`، مع تأخير تصاعدي.
- يعني `409` أن `correlationId` مستخدم بالفعل. لا تعيد استخدام معرّف أبدًا.
- أطلق تنبيهًا عند تكرار `503`: فهذا يعني أن Human Plugin لا يستطيع الوصول إلى قاعدة بياناته.

## توقعات التشغيل

- استدعِ Human Plugin من الشبكة نفسها التي توجد فيها الحاوية. أنهِ TLS أمامه إذا كان المسار يعبر شبكات غير موثوقة.
- تثبيت واحد من Human Plugin هو حدّ عزل واحد. العملاء أو العلامات التجارية أو البيئات المختلفة التي يجب ألا تتشارك الذكاء تحتاج إلى تثبيتات وقواعد بيانات منفصلة، لكلٍّ منها ذكاؤه الخاص.