---
title: 创建流程
description: POST /v1/processes：通用字段、校验限制、流程字段，以及包含 Human Token 和情报的 201 响应。
canonical: https://developer.unico.io/zh-CN/human-plugin/api-reference/create-process
locale: zh-CN
generated_by: markdown-export
---

# 创建流程

启动一个流程，并获取 Human Token 和此人的情报。

`POST /v1/processes`

使用其中一种[流程](#flows)启动一个流程，并返回 `id`、`state` 以及 `data` 中的结果：Human Token 和此人的[情报](/zh-CN/human-plugin/get-started/intelligence)，即 `data.ndocs`。

## 调用之前

- Human Plugin 正在运行，且 `GET /health/ready` 返回 `200`。
- 您的访问密钥已为您使用的[流程](#flows)启用。
- 如果您发送证件，其 `type` 在[属性目录](/zh-CN/human-plugin/additional-resources/attribute-catalog)中。

<a id="flows"></a>

## 流程

`flow` 字段决定该流程要做什么。Human Plugin 运行以下流程，分为两种集成模式：

- **API Only**：您的后端在 `imageBase64` 中发送自拍，创建请求直接返回结果。
- **Human Token Journey**：用户在采集旅程中拍摄自拍，并返回到您的 `callbackUri`。创建请求返回 `token` 和 `link`，您通过[获取流程](/zh-CN/human-plugin/api-reference/get-process)读取结果。

| Flow | Description | Possible result | Integration components required |
| --- | --- | --- | --- |
| `api+humantoken` | 通过您的后端接收自拍并生成 Human Token，即唯一的人脸标识符。响应即为最终结果：无需采集，也无需第二次调用。 | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API |
| `humantoken` | 在采集旅程中拍摄自拍并进行活体检测，然后生成 Human Token。创建请求返回 `token` 和 `link`；采集结束后再读取结果。 | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |
| `humantoken+revalidation` | 拍摄自拍，并将人脸与您预期的 Human Token 进行比对。返回是否为同一人，例如用于敏感操作之前。 | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |

`clientId`、`correlationId` 和 `credential` 在所有流程中都相同。

## 请求

```json
{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}
```

### 通用字段

| 字段 | 必填 | 限制（字节） | 说明 |
| --- | --- | --- | --- |
| `flow` | 是 | 64 | [流程](#flows)之一 |
| `clientId` | 是 | 128 | 您为该客户设置的 id。情报会统计不同取值的数量 |
| `correlationId` | 是 | 128 | 您对该流程的引用。**唯一**：与其他流程已有的值相同（无论其状态如何）都会以 `409` 拒绝 |
| `credential` | 是，但可为空 | | 键必须存在。见下文 |
| `credential.type` | 提供证件时 | | 属性目录中的代码，精确且区分大小写 |
| `credential.value` | 提供证件时 | 64 | 证件号码 |

`flow`、`clientId` 和 `correlationId` 必须是字符串，不得包含控制字符，也不得有首尾空白。无效值会被拒绝，绝不会被改写。

### `credential` 字段

- **提供证件时：** 一个恰好包含 `type` 和 `value` 的对象，两者均为字符串，且必须同时发送。
- **不提供证件时：** `null` 或 `{}`。该流程仍会在情报中计为一次交易和一个客户。
- **省略，或为包含空字符串的对象：** 以 `400 MISSING_CREDENTIAL_TYPE` 拒绝。这样可以在处理任何内容之前发现拼写错误的键。
- `credential` 内的其他任何键都会被拒绝。

### 流程字段

各流程在通用字段之外增加的内容：

| 字段 | 流程 | 必填 | 取值 |
| --- | --- | --- | --- |
| `imageBase64` | `api+humantoken` | 是 | base64 编码的自拍。PNG、JPEG 或 WebP，最大 800 KB |
| `callbackUri` | `humantoken`、`humantoken+revalidation` | 是 | 采集结束后用户返回的位置：您的某个页面，或您应用的 URL scheme |
| `references` | `humantoken+revalidation` | 是 | 一项，包含您预期的 Human Token，如上例所示 |

Human Plugin 不会存储这些字段，拼写错误的可选字段可能被忽略而不报错。

使用 `api+humantoken` 时，请提供正面、光线充足且仅含一张人脸的自拍。不是图像的值会被拒绝，且该流程会被存储为失败：参见[流程拒绝](#flow-refusals)。

使用 `humantoken+revalidation` 时，结果中包含 `humanTokenMatch`，而不是 `humanToken`：

- `"true"`：是同一个人。该流程会计入此人，`ndocs` 描述此人。
- 其他任何值，或非活体采集：未得到确认。该流程不计入任何人，也没有 `ndocs`。

两种情况都会返回 `PROCESS_STATE_FINISHED`：请读取 `humanTokenMatch`。参见[获取流程](/zh-CN/human-plugin/api-reference/get-process#finished-and-failed-processes)。

Human Plugin 保留了少数名称，使用它们会以 `400 INVALID_REQUEST` 拒绝，例如 `clientReference`。Human Plugin 自有字段的其他拼写也会被拒绝，例如 `client_id`、`correlation_id` 或 `Flow`：只会读取 `flow`、`clientId`、`correlationId` 和 `credential`，且必须拼写完全一致。

### 请求体规则

- 一个 JSON 对象，最大 **2 MiB**（大致够放一张 base64 编码的自拍）。更大的请求体会以 `400 REQUEST_TOO_LARGE` 拒绝。
- JSON 对象之后不得有任何内容。

## 响应

`201 Created`，并带有 `Location: /v1/processes/<id>`。

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}
```

- `id` 是 Human Plugin 的 UUID。每个被接受的请求都会创建一个新的。
- `state` 是本地状态。参见[生命周期](/zh-CN/human-plugin/api-reference/process-lifecycle)。
- `humantoken` 和 `humantoken+revalidation` 返回 `PROCESS_STATE_CREATED`，并带有 `token` 和 `link`。它们**只返回一次**且不会被存储：请自行保存。参见 [Human Token Journey](/zh-CN/human-plugin/integrations/human-token-journey) 以及适用于您平台的采集指南。
- `data.ndocs` 是此人的情报。它可能不存在：参见[情报](/zh-CN/human-plugin/get-started/intelligence)。

<a id="result"></a>

### `data` 中的结果

已完成的流程在 `data` 中包含以下字段。Journey 流程在采集后您[读取该流程](/zh-CN/human-plugin/api-reference/get-process)时返回这些字段。

| 字段 | 何时 | 取值 |
| --- | --- | --- |
| `humanToken` | `api+humantoken`、`humantoken` | 此人是谁：`value` 是 Human Token，`status` 为 `validated` 表示已生成 |
| `humanTokenMatch` | `humantoken+revalidation` | 当与 `references` 中的 Human Token 是同一人时为 `"true"` |
| `liveness` | 检查活体的流程，例如 Journey 流程 | 采集来自真人时 `value` 为 `live`，否则为 `not_live`；检查已执行时 `status` 为 `validated` |
| `ndocs` | 存在此人的情报时 | 此人的[情报](/zh-CN/human-plugin/get-started/intelligence) |

Journey 的结果如下所示：

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}
```

在信任结果之前请先检查 `liveness`：如果为 `not_live`，请将该采集视为失败，并请用户重试。`not_live` 的流程不会计入任何人的情报。

## 错误

| 状态 | `message` | 含义 |
| --- | --- | --- |
| 400 | `INVALID_REQUEST`、`REQUEST_TOO_LARGE` | 不是单个 JSON 对象、使用了保留字段、类型错误，或请求体超过 2 MiB |
| 400 | `MISSING_<FIELD>`、`INVALID_<FIELD>` | 必填字段缺失或格式错误，例如 `MISSING_CLIENT_ID` |
| 401 | 空（`""`） | Unico 拒绝了您的访问密钥：缺失、错误或已失效。该流程会被存储为失败。请检查 `HUMAN_API_ACCESS_KEY` |
| 409 | `CORRELATION_ID_ALREADY_USED` | 已有其他流程使用该 `correlationId`。未存储也未发送任何内容 |
| 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` 不在目录中。未存储也未发送任何内容 |
| 4xx | 流程的 `message` | 流程拒绝了请求，例如图像无效。参见[流程拒绝](#flow-refusals) |
| 502 | `UPSTREAM_UNAVAILABLE` | 未能及时确认该流程 |
| 503 | `DATABASE_UNAVAILABLE` | 数据库故障。未处理任何内容 |
| 500 | `INTERNAL` | 意外错误 |

<a id="flow-refusals"></a>

### 流程拒绝

当流程拒绝请求时，创建请求返回 `4xx`，原因写在 `message` 中，采用通常的[信封](/zh-CN/human-plugin/api-reference/errors-and-retries)。最常见的有：

| `message` | 原因 |
| --- | --- |
| `invalid flow` | `flow` 不是为您的账户启用的流程 |
| `INVALID_IMAGE`（`400`） | 使用 `api+humantoken` 但没有 `imageBase64` |
| `INVALID_REQUEST`（`400`） | `imageBase64` 不是 base64 编码的图像 |
| `IMAGE_TOO_LARGE` | 图像超过 800 KB |
| `UNSUPPORTED_IMAGE_FORMAT` | 图像不是 PNG、JPEG 或 WebP |
| `PERMISSION_DENIED`（`403`） | 您的访问密钥未为此流程启用 |

被拒绝的流程会被存储为失败。请修正请求，并使用新的 `correlationId` 创建新的流程。

在添加重试逻辑之前，请阅读[错误与重试](/zh-CN/human-plugin/api-reference/errors-and-retries)：新的尝试需要新的 `correlationId`。

## 下一步

[获取流程](/zh-CN/human-plugin/api-reference/get-process)