创建流程

MarkdownChatGPTClaude

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

• 入职/新用户注册 — 通过将用户面部与 Unico 的身份库进行比对来验证用户身份（需要 subject.duiType + subject.code）。
• 交易认证 — 通过面对面比对验证是否为先前流程中的同一人（需要 referenceProcessId 或包含自拍/流程 ID 的 references 数组）。
• Cardholder Verification — 无需任何自拍采集，确认一张卡片属于其声明的持卡人（需要 subject.code + card）。可选择通过 referenceProcessId 重用先前已验证的流程以触发重用条件；如果没有该字段，响应会默认返回 unsure 结果。参见 Cardholder Verification 能力。

活动产品由请求头中发送的 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 格式电话号码。
subject.clientReference	string	有条件	您系统中用户的唯一标识符。**多账号能力必填。**在您的库中唯一，最多 256 个字符，不含空格。
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_AR_DNI、DUI_TYPE_BR_CPF、DUI_TYPE_ID_NIK、DUI_TYPE_MX_CURP、DUI_TYPE_NG_NIN、DUI_TYPE_US_SSN。
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 响应中同步返回。

Cardholder Verification

字段	类型	必填	描述
subject.duiType	integer	是	文档类型标识符。请参阅下方的 duiType 值。目前仅支持 DUI_TYPE_BR_CPF。
subject.code	string	是	被验证持卡人的 CPF。不含点或破折号。
card.bin	string	有条件	卡片的前 6 或 8 位数字（BIN）。与 card.last4 一起为必填。
card.last4	string	有条件	卡片的后 4 位数字。与 card.bin 一起为必填。
card.name	string	否	卡片上印刷的持卡人姓名。
referenceProcessId	string (UUID)	否	要重用的先前已验证流程的 ID——该流程需针对同一 CPF 具有已通过的身份验证或活体检测结果。该功能的当前版本基于重用机制：如果缺少此字段，触发条件永远不会满足，响应会默认返回标准的 unsure 结果——请求本身不会失败。
useCase	string	否	操作上下文，例如 CardholderVerification。
subsidiaryId	string	否	分支机构 ID — 仅当存在多个分支机构时才需要。

信息

此产品不会发送 imageBase64 — Cardholder Verification 完全在后端运行，没有自拍采集步骤。

duiType 值

国家	代码	描述
AR	6	阿根廷护照
AR	7	阿根廷 DNI
AR	49	阿根廷驾驶证（Licencia Nacional de Conducir）
AT	34	奥地利税号（STNR）
BE	36	比利时国家号码（NN）
BR	1	巴西 CPF
BR	5	巴西护照
BR	14	巴西 CNPJ
CA	28	加拿大 SIN
CH	33	瑞士 AHV/AVS 号码
CL	9	智利 RUN
CL	52	智利护照
CL	57	智利驾驶证（Licencia de Conducir）
CO	26	哥伦比亚 NIT
CO	53	哥伦比亚护照
CO	55	哥伦比亚驾驶证（Licencia de Conducción）
CO	56	哥伦比亚公民身份证（Cédula de Ciudadanía）
DE	41	德国税务识别号码（IdNr）
DK	29	丹麦 CPR
EC	10	厄瓜多尔 NI
ES	50	西班牙外国人身份号码（NIE）
ES	51	西班牙国民身份证（DNI）
FI	35	芬兰个人身份代码（HETU）
FR	46	法国税务参考号码（SPI）
GB	30	英国国民保险号码（NINO）
GT	12	危地马拉 CUI
ID	16	印度尼西亚 NIK
IE	47	爱尔兰个人公共服务号码（PPSN）
IT	37	意大利税务代码（CF）
LU	48	卢森堡国民身份号码（Matricule）
MX	2	墨西哥 CURP
MX	25	墨西哥 RFC（自然人）
MX	58	墨西哥驾驶证（Licencia de Conducir）
NG	8	尼日利亚 NIN
NG	20	尼日利亚银行验证号码（BVN）
NG	43	尼日利亚 BVN 令牌（哈希）
NG	44	尼日利亚 NIN 令牌（哈希）
NL	42	荷兰公民服务号码（BSN）
NO	39	挪威国民身份号码（Fødselsnummer）
PE	27	秘鲁 RUC
PE	40	秘鲁 DNI
PE	54	秘鲁护照
PL	31	波兰 PESEL
PT	45	葡萄牙税务识别号码（NIF）
SE	32	瑞典个人号码（PNR）
SE	38	瑞典协调号码（Samordningsnummer）
TR	24	土耳其身份证号码（TCKN）
US	4	美国 SSN
US	11	美国护照
US	18	美国驾驶执照
US	21	美国护照卡
US	22	美国聚碳酸酯护照
US	23	美国身份证
UY	13	乌拉圭 CI
ZZ	15	电子邮件地址
ZZ	17	电话号码
—	0	未指定
—	3	Unico 内部标识符

图像要求

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

压缩请求

API 支持使用标准的 Content-Encoding HTTP 请求头以压缩方式发送请求体。此功能为可选项，并完全向后兼容：不发送该请求头的客户端仍将按原方式正常工作。

支持的格式

编码	Content-Encoding 请求头	状态
Gzip	gzip	✅ 推荐
Deflate	deflate	✅ 支持
不压缩	(无该请求头)	✅ 支持（默认行为）

推荐

请使用 gzip。它在各种语言和 HTTP 库中拥有最广泛的通用支持，避免了其他格式实现中可能存在的歧义。

对于具有较大请求体的请求（例如大量 JSON 负载、base64 编码的图像上传、批量提交），建议使用压缩。对于小型请求，压缩带来的开销可能无法带来实质性收益。

如何发送压缩请求

1. 使用所选算法压缩请求体（例如序列化后的 JSON）。
2. 将压缩后的请求体作为二进制字节在请求中发送。
3. 附上与所用算法匹配的 Content-Encoding 请求头（gzip 或 deflate）。
4. 保持 Content-Type 描述原始内容格式（例如 application/json），而不是传输编码。

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

提示

对于 Python 示例，请使用 data= 参数，而不是 json=。json= 参数会自动序列化负载，但不会对其进行压缩。

使用 deflate 压缩时： 上述流程完全相同——只需更改压缩调用和 Content-Encoding 的值。

语言	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate（来自 qpdf），然后使用 -H "Content-Encoding: deflate"
Python	使用 zlib.compress(data) 代替 gzip.compress(data)
.NET (C#)	使用 System.IO.Compression.DeflateStream 代替 GZipStream

deflate 在实践中存在歧义

HTTP 的 deflate 内容编码在规范上是一个 zlib 流（RFC 1950），但一些客户端和服务器历史上会发送或期望原始 DEFLATE（RFC 1951）。本 API 期望的是标准的 zlib 封装流——即 zlib.compress()（Python）或 DeflateStream（.NET）默认产生的输出。如果不确定，建议优先使用 gzip，它不存在这种歧义。

错误行为

如果 Content-Encoding 携带了不受支持的值，或请求体已损坏或与声明的编码不符，API 将返回 400 Bad Request，并附带表示请求体解压失败的消息。

常见问题

如果我不想使用压缩，需要做任何更改吗？ 不需要。Content-Encoding 支持是附加功能——不携带该请求头的请求将继续照常被处理。

这会影响 API 的响应吗？ 不会。此功能仅涉及客户端发送的请求体（请求）。响应压缩（API 返回的内容）由 Accept-Encoding 请求头单独控制。

应该选择哪种格式？ 请使用 gzip，除非您的环境中存在特定限制需要使用其他格式。

示例

入职/新用户注册 — 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();

Cardholder Verification — 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"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification — 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'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

响应

入职/新用户注册

200 OK

该合约是统一的——idCloud.result 字段承载了所用功能的整合判定结果。

Unico 将已执行功能的结果整合为单一的 idCloud.result，可直接用于决定您流程的下一步——无需自行编排各项结果。

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

字段	类型	描述
id	string (UUID)	流程标识符。使用获取流程进行重新查询。
status	integer	1（处理中）、3（成功完成）、5（错误）。

可能的结果值

idCloud.result	含义	建议操作
approved	真实人员且身份已验证。	继续该流程。
denied	身份未验证、活体检测失败，或识别到极端风险。	结束该流程或跳转至备用流程。
critical-risk	识别到严重风险级别。	结束该流程或转至人工审核。
high-risk	识别到高风险级别。	转至人工审核或备用流程。
retry	采集数据或评分不足，无法评估。	请用户重新进行采集。
inconclusive	证据不足，无法做出判定。	转至人工审核或备用流程。

返回的值取决于您 APIKey 中配置的配方。各配方可返回的结果值请参见流程。

巴西的客户可能会按功能接收响应

整体响应结构保持不变——单一结果为默认方式。

巴西的集成可能会收到开放式的、按功能划分的结果。APIKey 中启用的每项功能都会在响应中新增相应的字段块——未启用功能的字段则会被省略。

{
  "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 项目经理以启用或调整功能。

字段	类型	描述
unicoId.result	string	yes、no、inconclusive — 参见身份验证。
riskLevel.result	string	approved、reproved、risk-critical、risk-high、inconclusive — 参见下方的可能值或欺诈风险分类。
idFace.result	string	FOUND — 参见 人脸标识符。
idFace.personId	string	人脸的稳定不透明标识符，与 idFace.result = FOUND 一同返回。当图像中无法识别出人脸时，请求会失败，返回错误 20532，而不是返回 idFace 字段块。
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 来获取最终结果。

墨西哥的客户可能会收到 RENAPO Verification 块

响应结构保持不变，并新增 idGov 块。

在墨西哥启用了 RENAPO Verification 的集成，会额外收到一个 idGov 块，其中包含 RENAPO 为用户 CURP 所持有的记录。它是与身份结果相互独立的答复。

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

字段	类型	描述
idGov	object	CURP 对应的 RENAPO 记录。未启用该功能时不存在。RENAPO 未响应时为 {}。仅限墨西哥。参见 RENAPO Verification。

交易认证

200 OK

该合约是统一的——idCloud.result 字段承载了所用功能的整合判定结果。

Unico 将已执行功能的结果整合为单一的 idCloud.result，可直接用于决定您流程的下一步——无需自行编排各项结果。

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

字段	类型	描述
id	string (UUID)	流程标识符。
status	integer	3（成功完成）、5（错误）。有关所有可能的值，请参阅获取流程。

可能的结果值

idCloud.result	含义	建议操作
approved	真实人员且身份已验证。	继续该流程。
denied	身份未验证、活体检测失败，或识别到极端风险。	结束该流程或跳转至备用流程。
critical-risk	识别到严重风险级别。	结束该流程或转至人工审核。
high-risk	识别到高风险级别。	转至人工审核或备用流程。
retry	采集数据或评分不足，无法评估。	请用户重新进行采集。
inconclusive	证据不足，无法做出判定。	转至人工审核或备用流程。

返回的值取决于您 APIKey 中配置的配方。各配方可返回的结果值请参见流程。

巴西的客户可能会按功能接收响应

整体响应结构保持不变——单一结果为默认方式。

巴西的集成可能会收到开放式的、按功能划分的结果。APIKey 中启用的每项功能都会在响应中新增相应的字段块——未启用功能的字段则会被省略。

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

字段	类型	描述
biometryToken.result	boolean	如果提交的面部与参考流程匹配则为 true；否则为 false。
liveness	integer	1（通过）、2（未通过） — 参见活体检测。

Cardholder Verification

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "cardholderVerification": {
    "result": "approved"
  }
}

字段	类型	描述
id	string (UUID)	流程标识符。
status	integer	1（处理中）、3（成功完成）、5（错误）。有关所有可能的值，请参阅获取流程。
cardholderVerification.result	string	approved — CPF 与该卡片属于同一人。unsure — 复用条件未满足，或验证本身无法得出结论。当 status 尚未达到 3 时不存在此字段。参见 Cardholder Verification。

错误代码

400 Bad Request

代码	消息	描述
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	复用流程（referenceProcessId/bioTokenId，无图片）被拒绝，因为此 API 密钥未启用流程复用。
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.	上传图像的分辨率过低。
20532	No face detected in image.	未能在提交的图像中检测到人脸。
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 作为替代。不适用于 Cardholder Verification —— 其 referenceProcessId 从不被视为必填校验；未满足的复用条件会返回 unsure，而不会导致请求失败。
20533	The card field is missing.	Cardholder Verification：未提供 card 对象。
20534	The card.bin field is missing.	Cardholder Verification：未提供 card.bin。
20535	The card.last4 field is missing.	Cardholder Verification：未提供 card.last4。
20536	The card data is invalid.	Cardholder Verification：卡片数据被判定为无效并被拒绝。
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

Bearer 令牌或 APIKEY 缺失、过期或无效。请参阅认证。

代码	消息	描述
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 已存在于此租户中。

429 Too Many Requests

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

最佳实践：

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

警告

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

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

500 Internal Server Error

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

下一步

• 有关查询入职流程结果，请参阅获取流程。
• 要查看所有配方组合及其可能的结果值，请参阅流程。
• 有关文档和年龄验证操作，请参阅本节中的相应页面。