创建流程

此端点处理两个共享相同路径但在请求体参数、功能和响应字段上不同的用例：

• 入职/新用户注册 — 通过将用户面部与 Unico 的身份库进行比对来验证用户身份（需要 subject.duiType + subject.code）。
• 交易认证 — 通过面对面比对验证是否为先前流程中的同一人（需要 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

请求体参数

入职/新用户注册

字段	类型	必填	描述
subject.duiType	integer	是	文档类型标识符。请参阅下方的 duiType 值。
subject.code	string	是	subject.duiType 定义的标识符值。不含点或破折号。
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。
subsidiaryId	string	否	分支机构 ID — 仅当存在多个分支机构时才需要。
imageBase64	string	是	前端采集的自拍照，base64 格式。

交易认证

字段	类型	必填	描述
references	array	有条件	1:1 验证流程的参考输入。每个项目包含 referenceType（REFERENCE_TYPE_IMAGE_BASE64 或 REFERENCE_TYPE_PROCESS_ID）和 referenceContent（base64 编码的图像或流程 UUID）。
referenceProcessId	string	有条件	已弃用。 请改用 references。要比对的参考入职流程的 ID。如果参考是 by-Unico 流程，请使用 authenticationInfo.authenticationId。
imageBase64	string	是	前端采集的自拍照，base64 格式。
subject	object	否	用户信息容器。
subject.duiType	string	否	标识符类型。可能的值：DUI_TYPE_BR_CPF、DUI_TYPE_MX_CURP、DUI_TYPE_US_SSN、DUI_TYPE_NG_NIN、DUI_TYPE_AR_DNI、DUI_TYPE_ID_NIK。
subject.code	string	否	subject.duiType 定义的标识符值。不含点或破折号。
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 响应中同步返回。

duiType 值

国家	代码	描述
BR	1	巴西 CPF
BR	5	巴西护照
MX	2	墨西哥 CURP
AR	6	阿根廷护照
AR	7	阿根廷 DNI
US	4	美国 SSN
US	11	美国护照
US	18	美国驾驶执照
ID	16	印度尼西亚 NIK
NG	8	尼日利亚 NIN
CL	9	智利 RUN
EC	10	厄瓜多尔 NI
GT	12	危地马拉 CUI
UY	13	乌拉圭 CI
ZZ	15	电子邮件地址
ZZ	17	电话号码
MX	25	墨西哥 RFC（自然人）
CO	26	哥伦比亚 NIT
PE	27	秘鲁 RUC
CA	28	加拿大 SIN
DK	29	丹麦 CPR
GB	30	英国国民保险号码（NINO）
PL	31	波兰 PESEL
SE	32	瑞典个人号码（PNR）
AT	34	奥地利税号（STNR）
FI	35	芬兰个人身份代码（HETU）
—	0	未指定
—	3	Unico 内部标识符

图像要求

• 最低分辨率：640 × 480（HD 标准）
• 最大文件大小：800 KB（建议使用 JPEG92 压缩）
• 接受的格式：PNG、JPEG、WebP
• 来自 SDK 的 JWT 令牌在 10 分钟后过期，且只能使用一次

示例

入职/新用户注册 — cURL

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": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

入职/新用户注册 — Node.js

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: {
      duiType: 1,
      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

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

交易认证 — Node.js

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({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

响应

入职/新用户注册

200 OK

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

响应字段取决于您的 APIKey

以上示例展示了所有可能的功能字段。您的实际响应仅包含在 APIKey 配置中已启用功能的字段——未启用功能的字段将被完全省略。请联系您的 Unico 项目经理以启用或调整功能。

字段	类型	描述
id	string (UUID)	流程标识符。使用获取流程进行重新查询。
status	integer	1（处理中）、3（成功完成）、5（错误）。
unicoId.result	string	yes、no、inconclusive — 参见身份验证。
riskLevel.result	string	approved、reproved、risk-critical、risk-high、inconclusive — 参见下方的可能值或欺诈风险分类。
idFace.result	string	FOUND、NOT_FOUND — 参见 Face Identifier。
idFace.personId	string	人脸的稳定不透明标识符。仅当 idFace.result = FOUND 时存在。
identityFraudsters.result	string	已弃用。 请改用 riskLevel。正在进行集成的客户可在与项目团队协调迁移工作的同时继续使用此字段。
government.serpro	integer	Serpro 相似度分数（0-100、-1、-2）。仅在巴西可用。参见 Serpro 相似度返回。
liveness	integer	1（通过）、2（未通过） — 参见活体检测。

riskLevel.result — 可能的值

值	含义
approved	为证件持有人本人的面部，且未发现与欺诈相关的证据。
reproved	建议拒绝，因为检测到多个欺诈指标。
risk-critical	建议拒绝，但最终决定由您自行判断。严重风险表示我们发现了至少 2 项强有力的欺诈证据。
risk-high	同样建议拒绝，但决定权仍在您手中。高风险表示我们发现了至少 1 项强有力的欺诈证据。
inconclusive	未发现强有力的欺诈证据，因此无法得出是否存在相关风险的结论。

信息

当 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

已达到速率限制。当您的系统收到 HTTP 429 错误时，您必须实施机制以防止级联故障并避免加重限制。

最佳实践：

• 冷却期（退避）： 立即停止或限制系统中的后续请求。不要在紧密循环中持续重试失败的请求。
• 队列和限流： 在您端缓冲或排队传出请求，以在重新发送之前控制流量。
• 指数退避与抖动： 重试时，以指数方式增加尝试之间的等待时间（例如 1 秒、2 秒、4 秒、8 秒），并添加小的随机延迟（"抖动"）以防止所有排队请求在完全相同的毫秒重试的"群体效应"。

警告

在未退避的情况下持续请求被限速的端点会延长限制期并严重影响系统的运行吞吐量。在您端正确限制请求可确保更平稳、更具弹性的集成。

有关默认限制、增加请求和其他详细信息，请参阅速率限制。

错误代码

400 Bad Request

代码	消息	描述
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 格式无效（IDD + 区号 + 号码，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。

403 Forbidden

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

409 Conflict

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

500 Internal Server Error

代码	消息	描述
99999	Internal failure! Try again later	出现内部错误时。

下一步

• 有关查询入职流程结果，请参阅获取流程。
• 有关文档和年龄验证操作，请参阅本节中的相应页面。