Интеграция с вашим бэкендом

Чек-лист для вызова 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 и помните, что поле может отсутствовать. См. Intelligence.

5. Обработка сбоев

• Не повторяйте автоматически 500 и 502 при создании. См. Ошибки и повторы.
• Повторяйте 503 при создании с тем же correlationId, а также любой сбой при GET, с нарастающей задержкой.
• 409 означает, что correlationId уже занят. Никогда не используйте его повторно.
• Настройте оповещение о повторяющихся 503: это значит, что Human Plugin не может достучаться до своей базы данных.

Эксплуатационные ожидания

• Вызывайте Human Plugin из той же сети, что и контейнер. Завершайте TLS перед ним, если путь проходит через недоверенные сети.
• Одна установка Human Plugin — это одна граница изоляции. Разным клиентам, брендам или средам, которые не должны делить intelligence, нужны отдельные установки и базы данных, у каждой со своим intelligence.