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

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

Markdown

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

1. الإنشاء

curl

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

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، وتذكّر أنه قد يكون غائبًا. راجع الذكاء.

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

• لا تعد محاولة 500 أو 502 عند الإنشاء تلقائيًا. راجع الأخطاء وإعادة المحاولة.
• أعد محاولة 503 عند الإنشاء بنفس correlationId، وأي إخفاق في GET، مع تأخير تصاعدي.
• يعني 409 أن correlationId مستخدم بالفعل. لا تعيد استخدام معرّف أبدًا.
• أطلق تنبيهًا عند تكرار 503: فهذا يعني أن Human Plugin لا يستطيع الوصول إلى قاعدة بياناته.

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

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