跳转到主要内容

创建流程

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

  • 入职/新用户注册 — 通过将用户面部与 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

请求​

请求头
请求头值
AuthorizationBearer <access_token>（参见认证）
APIKEY已配置的 API 密钥 — 定义活动产品和启用的功能。
Content-Typeapplication/json
请求体参数
字段类型必填描述
subject.duiTypeinteger是文档类型标识符。请参阅下方的 duiType 值。
subject.codestring是subject.duiType 定义的标识符值。不含点或破折号。
subject.namestring否全名。
subject.genderstring否M 或 F。
subject.birthDatestring (ISO 8601)否出生日期（YYYY-MM-DD）。
subject.emailstring否电子邮件地址。
subject.phonestring否E.164 格式电话号码。
subject.clientReferencestring有条件您系统中用户的唯一标识符。**多账号能力必填。**在您的库中唯一，最多 256 个字符，不含空格。
useCasestring否操作上下文，例如 Onboarding。
subsidiaryIdstring否分支机构 ID — 仅当存在多个分支机构时才需要。
imageBase64string是前端采集的自拍照，base64 格式。
duiType 值
国家代码描述
BR1巴西 CPF
MX2墨西哥 CURP
US4美国 SSN
BR5巴西护照
AR6阿根廷护照
AR7阿根廷 DNI
NG8尼日利亚 NIN
CL9智利 RUN
EC10厄瓜多尔 NI
US11美国护照
GT12危地马拉 CUI
UY13乌拉圭 CI
BR14巴西 CNPJ
ZZ15电子邮件地址
ID16印度尼西亚 NIK
ZZ17电话号码
US18美国驾驶执照
NG20尼日利亚银行验证号码（BVN）
US21美国护照卡
US22美国聚碳酸酯护照
US23美国身份证
TR24土耳其身份证号码（TCKN）
MX25墨西哥 RFC（自然人）
CO26哥伦比亚 NIT
PE27秘鲁 RUC
CA28加拿大 SIN
DK29丹麦 CPR
GB30英国国民保险号码（NINO）
PL31波兰 PESEL
SE32瑞典个人号码（PNR）
CH33瑞士 AHV/AVS 号码
AT34奥地利税号（STNR）
FI35芬兰个人身份代码（HETU）
BE36比利时国家号码（NN）
IT37意大利税务代码（CF）
SE38瑞典协调号码（Samordningsnummer）
NO39挪威国民身份号码（Fødselsnummer）
PE40秘鲁 DNI
DE41德国税务识别号码（IdNr）
NL42荷兰公民服务号码（BSN）
NG43尼日利亚 BVN 令牌（哈希）
NG44尼日利亚 NIN 令牌（哈希）
PT45葡萄牙税务识别号码（NIF）
FR46法国税务参考号码（SPI）
IE47爱尔兰个人公共服务号码（PPSN）
LU48卢森堡国民身份号码（Matricule）
AR49阿根廷驾驶证（Licencia Nacional de Conducir）
ES50西班牙外国人身份号码（NIE）
ES51西班牙国民身份证（DNI）
CL52智利护照
CO53哥伦比亚护照
PE54秘鲁护照
CO55哥伦比亚驾驶证（Licencia de Conducción）
CO56哥伦比亚公民身份证（Cédula de Ciudadanía）
CL57智利驾驶证（Licencia de Conducir）
MX58墨西哥驾驶证（Licencia de Conducir）
—0未指定
—3Unico 内部标识符
图像要求
  • 最低分辨率：640 × 480（HD 标准）
  • 最大文件大小：800 KB（建议使用 JPEG92 压缩）
  • 接受的格式：PNG、JPEG、WebP
  • 来自 SDK 的 JWT 令牌在 10 分钟后过期，且只能使用一次

示例​

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..."
  }'

响应​

200 OK

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

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

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}
字段类型描述
idstring (UUID)流程标识符。使用获取流程进行重新查询。
statusinteger1（处理中）、3（成功完成）、5（错误）。
可能的结果值
idCloud.resultMeaningRecommended action
approvedReal person and validated identity.Proceed with the flow.
deniedIdentity not validated, liveness check failed, or extreme risk identified.End the flow or redirect to an alternative flow.
critical-riskCritical risk level identified.End the flow or route to manual review.
high-riskHigh risk level identified.Route to manual review or an alternative flow.
retryInsufficient capture or score to evaluate.Ask the user for a new capture.
inconclusiveNot enough evidence for a verdict.Route to manual review or an alternative flow.

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

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

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

巴西的集成可能会收到开放式的、按功能划分的结果。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.resultstringyes、no、inconclusive — 参见身份验证。
riskLevel.resultstringapproved、reproved、risk-critical、risk-high、inconclusive — 参见下方的可能值或欺诈风险分类。
idFace.resultstringFOUND — 参见 人脸标识符。
idFace.personIdstring人脸的稳定不透明标识符，与 idFace.result = FOUND 一同返回。当图像中无法识别出人脸时，请求会失败，返回错误 20532，而不是返回 idFace 字段块。
identityFraudsters.resultstring已弃用。 请改用 riskLevel。正在进行集成的客户可在与项目团队协调迁移工作的同时继续使用此字段。
government.serprointegerSerpro 相似度分数（0-100、-1、-2）。仅在巴西可用。参见 Serpro 相似度返回。
livenessinteger1（通过）、2（未通过） — 参见活体检测。
riskLevel.result — 可能的值
值含义
approved为证件持有人本人的面部，且未发现与欺诈相关的证据。
reproved建议拒绝，因为检测到多个欺诈指标。
risk-critical建议拒绝，但最终决定由您自行判断。严重风险表示我们发现了至少 2 项强有力的欺诈证据。
risk-high同样建议拒绝，但决定权仍在您手中。高风险表示我们发现了至少 1 项强有力的欺诈证据。
inconclusive未发现强有力的欺诈证据，因此无法得出是否存在相关风险的结论。
信息

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

错误代码​

代码消息描述
40221This 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 密钥未启用流程复用。
20900O base64 informado não é válido.base64 参数无效。可能的原因：不是图像或是注入尝试。
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.上传图像的分辨率过低。
20532No face detected in image.未能在提交的图像中检测到人脸。
20513The referenced process was not found.referenceProcessId 指向的流程不存在或不再可访问。
20512The referenced process is not available for reuse.参考流程存在但不可重用。
20509The subject.name field is invalid.subject.name 包含无效字符。
20508The subject.gender field is invalid.subject.gender 必须为 M 或 F。
20507O parâmetro subject.code é inválido.非标准或不存在的 CPF。
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.图像大小超过 800 KB；压缩为 JPEG92。
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.base64 格式无效或不受支持。
20065The referenceProcessId field is invalid.referenceProcessId 不是有效的 UUID。
20062The useCase field is invalid.useCase 字段中有无法识别的值。
20024The referenceProcessId field is missing.未提供 referenceProcessId 参数，且未发送 references 作为替代。不适用于 Cardholder Verification —— 其 referenceProcessId 从不被视为必填校验；未满足的复用条件会返回 unsure，而不会导致请求失败。
20533The card field is missing.Cardholder Verification：未提供 card 对象。
20534The card.bin field is missing.Cardholder Verification：未提供 card.bin。
20535The card.last4 field is missing.Cardholder Verification：未提供 card.last4。
20536The card data is invalid.Cardholder Verification：卡片数据被判定为无效并被拒绝。
20021The subject.phone field is invalid.subject.phone 格式无效（IDD + 区号 + 号码，13 个字符）。
20019The subject.birthDate field is invalid.subject.birthDate 不符合 ISO 8601 格式（YYYY-MM-DD）。
20009O parâmetro imagebase64 não foi informado.缺少自拍图像参数。
20008The subject.email field is invalid.subject.email 中的电子邮件格式无效。
20006O parâmetro subject.name não foi informado.缺少 subject.name 参数。
20005O parâmetro subject.code não foi informado.缺少 subject.code 参数。
20004O parâmetro subject não foi informado.缺少 subject 参数。
20003The request body is missing or invalid.空或无效的请求体。
20002O parâmetro APIKey não foi informado.请求头中缺少 APIKEY 参数。
20001O parâmetro authtoken não foi informado.请求头中缺少集成令牌参数。
10508The JWT with the captured face has already been used.JWT 只能使用一次。
10507The JWT with the captured face is expired.JWT 已过期；必须在 10 分钟内发送。
10506The imageBase64 field is not a valid JWT from SDK.imageBase64 不是由 SDK 生成的有效 JWT。

下一步​

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