---
title: 集成您的后端
description: 后端服务应如何调用 Human Plugin：需要保存什么、如何轮询、如何读取结果以及如何处理失败。
canonical: https://developer.unico.io/zh-CN/human-plugin/integrations/backend
locale: zh-CN
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` 的句柄 |
| 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 一起用于您的决策，并注意它可能不存在。请参阅[智能信息](/zh-CN/human-plugin/get-started/intelligence)。

## 5. 失败处理

- 不要在创建时自动重试 `500` 或 `502`。请参阅[错误与重试](/zh-CN/human-plugin/api-reference/errors-and-retries)。
- 创建时遇到 `503`，请使用相同的 `correlationId` 并采用退避策略重试；`GET` 上的任何失败也同样处理。
- `409` 表示该 `correlationId` 已被占用。切勿复用。
- 对重复出现的 `503` 发出告警：这意味着 Human Plugin 无法连接其数据库。

## 运维预期

- 请从与容器相同的网络调用 Human Plugin。如果链路经过不受信任的网络，请在其前端终止 TLS。
- 一个 Human Plugin 安装就是一个隔离边界。不得共享智能信息的不同客户、品牌或环境，需要使用各自独立的安装和数据库，并各自拥有自己的智能信息。