创建流程 | Unico Developer Portal

创建流程POST

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

Markdown

POST /v1/processes

使用其中一种流程启动一个流程，并返回 id、state 以及 data 中的结果：Human Token 和此人的情报，即 data.ndocs。

调用之前

Human Plugin 正在运行，且 GET /health/ready 返回 200。
您的访问密钥已为您使用的流程启用。
如果您发送证件，其 type 在属性目录中。

流程

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

API Only：您的后端在 imageBase64 中发送自拍，创建请求直接返回结果。
Human Token Journey：用户在采集旅程中拍摄自拍，并返回到您的 callbackUri。创建请求返回 token 和 link，您通过获取流程读取结果。

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

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

请求

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

通用字段

字段	必填	限制（字节）	说明
`flow`	是	64	流程之一
`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 时，请提供正面、光线充足且仅含一张人脸的自拍。不是图像的值会被拒绝，且该流程会被存储为失败：参见流程拒绝。

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

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

两种情况都会返回 PROCESS_STATE_FINISHED：请读取 humanTokenMatch。参见获取流程。

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>。

{
  "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 是本地状态。参见生命周期。
humantoken 和 humantoken+revalidation 返回 PROCESS_STATE_CREATED，并带有 token 和 link。它们只返回一次且不会被存储：请自行保存。参见 Human Token Journey 以及适用于您平台的采集指南。
data.ndocs 是此人的情报。它可能不存在：参见情报。

`data` 中的结果

已完成的流程在 data 中包含以下字段。Journey 流程在采集后您读取该流程时返回这些字段。

字段	何时	取值
`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`	存在此人的情报时	此人的情报

Journey 的结果如下所示：

{
  "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`	流程拒绝了请求，例如图像无效。参见流程拒绝
502	`UPSTREAM_UNAVAILABLE`	未能及时确认该流程
503	`DATABASE_UNAVAILABLE`	数据库故障。未处理任何内容
500	`INTERNAL`	意外错误

流程拒绝

当流程拒绝请求时，创建请求返回 4xx，原因写在 message 中，采用通常的信封。最常见的有：

`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 创建新的流程。

在添加重试逻辑之前，请阅读错误与重试：新的尝试需要新的 correlationId。

下一步

获取流程

调用之前​

流程​

请求​

通用字段​

credential 字段​

流程字段​

请求体规则​

响应​

data 中的结果​

错误​

流程拒绝​

下一步​