创建流程

该端点处理两种用例，它们共享相同的路径，但在请求体参数、功能和响应字段上有所不同：

Onboarding — 通过将用户面部与 Unico 的身份数据库进行比对来验证用户身份（需要 subject.code）。
Transactional — 通过面对面比对来验证与之前流程是否为同一人（需要 referenceProcessId 或包含自拍/流程 ID 的 references 数组）。

激活的用例由请求头中发送的 APIKEY 决定。

完整集成流程请参阅 API 概览。

端点

环境	URL
生产环境	`POST https://api.id.unico.app/processes/v1`
沙盒环境	`POST https://api.id.uat.unico.app/processes/v1`

请求

请求头

请求头	值
`Authorization`	`Bearer <access_token>`（参见身份验证）
`APIKEY`	已配置的 API 密钥——定义激活的用例和启用的能力。
`Content-Type`	`application/json`

请求体参数

Onboarding
Transactional

字段	类型	必填	描述
`subject.code`	string	是	CPF（巴西）或 CURP（墨西哥）。
`subject.name`	string	是	全名。
`subject.gender`	string	否	`M` 或 `F`。
`subject.birthDate`	string (ISO 8601)	否	出生日期（`YYYY-MM-DD`）。
`subject.email`	string	否	电子邮件地址。
`subject.phone`	string	否	E.164 格式电话号码。
`useCase`	string	否	操作上下文，例如 `Onboarding`。
`imageBase64`	string	是	前端采集的自拍图像，base64 格式。

字段	类型	必填	描述
`references`	array	条件必填	用于 1:1 验证流程的参考输入。每个元素包含 `referenceType`（`REFERENCE_TYPE_IMAGE_BASE64` 或 `REFERENCE_TYPE_PROCESS_ID`）和 `referenceContent`（base64 编码图像或流程 UUID）。
`referenceProcessId`	string	条件必填	已弃用。请使用 `references` 代替。用于比对的参考 Onboarding 流程的 ID。如果参考流程是由 Unico 执行的，请使用 `authenticationInfo.authenticationId`。
`imageBase64`	string	是	前端采集的自拍图像，base64 格式。
`subject`	object	否	用户信息容器。
`subject.code`	string	否	CPF（巴西）或 CURP（墨西哥）。
`subject.name`	string	否	用户全名。
`subject.gender`	string	否	`M` 或 `F`。
`subject.birthDate`	string (ISO 8601)	否	出生日期（`YYYY-MM-DD`）。
`subject.email`	string	否	电子邮件地址。
`subject.phone`	string	否	E.164 格式电话号码。
`useCase`	string	否	操作上下文，例如 `Transactional`。
`subsidiaryId`	string	否	分支机构 ID——仅在存在多个分支机构时必填。

信息

对于此用例，无法与欺诈风险分类进行编排。结果始终在 POST 响应中同步返回。

图像要求

最低分辨率：640 × 480（HD 标准）
最大文件大小：800 KB（推荐使用 JPEG92 压缩）
支持格式：PNG、JPEG、WebP
SDK 生成的 JWT 令牌在 10 分钟后过期，且只能使用一次

示例

Onboarding — cURL
Onboarding — Node.js
Transactional — cURL
Transactional — Node.js

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

响应

Onboarding
Transactional

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

字段	类型	描述
`id`	string (UUID)	流程标识符。与获取流程配合使用可进行二次查询。
`status`	integer	`1`（处理中），`3`（成功完成），`5`（错误）。所有可能的值请参阅获取流程。
`unicoId.result`	string	`yes`、`no`、`inconclusive`——参见身份验证。
`identityFraudsters.result`	string	`yes`、`inconclusive`——参见欺诈风险分类。
`government.serpro`	integer	Serpro 相似度评分（0–100、-1、-2）。参见Serpro 相似度返回。
`liveness`	integer	`1`（通过），`2`（失败）——参见活体检测。

信息

当 unicoId.result = inconclusive 且欺诈风险分类编排处于激活状态时，流程可能返回 status: 1（处理中）。请轮询获取流程或使用 webhook 获取最终结果。

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

字段	类型	描述
`id`	string (UUID)	流程标识符。
`status`	integer	`3`（成功完成），`5`（错误）。所有可能的值请参阅获取流程。
`biometryToken.result`	boolean	如果提交的面部与参考流程匹配则为 `true`，否则为 `false`。
`liveness`	integer	`1`（通过），`2`（失败）——参见活体检测。

400 Bad Request

请求体格式错误、图像无效或缺少必填字段。参见下方错误代码。

403 Forbidden

Bearer 令牌或 APIKEY 缺失、已过期或无效。参见身份验证。

409 Conflict

提供的 processId 在此租户中已存在。参见下方错误代码。

429 Too Many Requests

已达到速率限制。请在 Retry-After 响应头指示的时间间隔后重试。参见速率限制。

错误代码

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

代码	消息	描述
`20900`	O base64 informado não é válido.	base64 参数无效。可能原因：不是图像或是注入攻击。
`20807`	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	上传图像的分辨率过低。
`20513`	The referenced process was not found.	`referenceProcessId` 指向的流程不存在或不再可访问。
`20512`	The referenced process is not available for reuse.	引用的流程存在但不可用于复用。
`20509`	The subject.name field is invalid.	`subject.name` 包含无效字符。
`20508`	The subject.gender field is invalid.	`subject.gender` 必须为 `M` 或 `F`。
`20507`	O parâmetro subject.code é inválido.	CPF 格式非标准或不存在。
`20506`	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	图像大小超过 800 KB；请压缩为 JPEG92。
`20505`	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	base64 格式无效或不支持。
`20065`	The referenceProcessId field is invalid.	`referenceProcessId` 不是有效的 UUID。
`20062`	The useCase field is invalid.	`useCase` 字段中的值无法识别。
`20024`	The referenceProcessId field is missing.	未提供 `referenceProcessId` 参数，且未以 `references` 作为替代方案发送。
`20021`	The subject.phone field is invalid.	`subject.phone` 格式无效（国际区号 + 区号 + 号码，共 13 位字符）。
`20019`	The subject.birthDate field is invalid.	`subject.birthDate` 不符合 ISO 8601 格式（`YYYY-MM-DD`）。
`20009`	O parâmetro imagebase64 não foi informado.	缺少自拍图像参数。
`20008`	The subject.email field is invalid.	`subject.email` 中的邮箱格式无效。
`20006`	O parâmetro subject.name não foi informado.	缺少 subject.name 参数。
`20005`	O parâmetro subject.code não foi informado.	缺少 subject.code 参数。
`20004`	O parâmetro subject não foi informado.	缺少 subject 参数。
`20003`	The request body is missing or invalid.	负载为空或无效。
`20002`	O parâmetro APIKey não foi informado.	请求头中缺少 APIKEY 参数。
`20001`	O parâmetro authtoken não foi informado.	请求头中缺少集成令牌参数。
`10508`	The JWT with the captured face has already been used.	JWT 只能使用一次。
`10507`	The JWT with the captured face is expired.	JWT 已过期；必须在 10 分钟内发送。
`10506`	The imageBase64 field is not a valid JWT from SDK.	`imageBase64` 不是 SDK 生成的有效 JWT。

代码	消息	描述
`30017`	User does not have permission to perform this action.	JWT 格式错误或用户无权执行此操作。
`10502`	O token informado está expirado.	access-token 已过期。
`10501`	O token informado é inválido.	身份验证令牌无效。
`10201`	O AppKey informado é inválido.	APIKEY 无效或不存在。

代码	消息	描述
`20073`	The processID already exists.	提供的 `processId` 在此租户中已存在。

代码	消息	描述
`99999`	Internal failure! Try again later	发生内部错误。

下一步

查询 Onboarding 流程结果，请参阅获取流程。
Document 和年龄验证操作，请参阅本节中的对应页面。

端点​

请求​

示例​

响应​

错误代码​

下一步​

端点

请求

示例

响应

错误代码

下一步