集成您的后端

从服务端调用 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 的句柄
Journey 的 token 和 link（如有）	仅在创建响应中返回，Human Plugin 不会存储
您的 correlationId	它必须唯一。每次尝试（包括重试）都要生成新的 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 安装就是一个隔离边界。不得共享智能信息的不同客户、品牌或环境，需要使用各自独立的安装和数据库，并各自拥有自己的智能信息。