跳转到主要内容

重新处理与生物识别库导入

本指南介绍如何在 Unico 平台上执行重新处理或生物识别库导入。内容详细说明了按照平台最佳实践进行有效、安全集成所需的技术和运营要求。

范围​

本材料涵盖两种类型的流程：

  • 重新处理：对已经通过客户和 Unico 库的用户的生物识别记录进行重新处理，用于重新评估或系统间迁移。
  • 生物识别库导入：初始上传或更新包含自拍照的库，用于身份验证和/或风险分类目的。
  • 文档库导入：与自拍照一起上传文档库，用于 Facematch 或 CPF Match 验证目的（仅限巴西）。

前提条件​

  • 客户必须与 Unico 签署有效合同或保密协议，并处于集成阶段（经治理团队批准的除外）。
  • 项目将遵循正式的 TPS（每秒事务数）协议。参见下方的 TPS 协议。
  • 获取生产凭证前，必须完成完整的集成验收测试，以确保数据质量、payload 合规性和稳定性能。
  • 必须为重新处理或导入创建专用服务账户（例如 "Reprocessing" 或 "Legacy_Import"）。
  • 将为重新处理/导入创建专用 API Key。
  • （可选） 可以为重新处理/导入创建专用子公司。此参数在 payload 中标识为 subsidiaryId。参见下方的 Payload 参数。
  • API Key 和服务账户将在约定期限到期或处理完成后被停用。

可用能力​

能力描述
身份验证验证提交的自拍照是否属于标识符的实际持有人。
欺诈风险分类检查与该面部相关的欺诈行为历史记录。
Facematch验证文档照片是否与提交的自拍照匹配。
CPF Match BrazilBrazil only验证提供的 CPF 是否与文档上印刷的 CPF 号码匹配。注意：并非所有 RG 都印有 CPF。

自拍照要求​

  • 必须以 base64 格式提交。
  • 图像必须符合 ICAO 标准（浅色背景、面部居中、无遮挡识别的配件、适当的光照）。
  • 推荐尺寸：1080x1920（竖屏）或 1920x1080（横屏）。
  • 最大大小：800 KB（如需要请使用 JPEG 92 压缩）。
  • 方向：竖屏。

文档要求​

  • 支持的文档类型：参见文档采集与重用 — 支持的文档。
  • 图像必须包含文档的正面和背面，完全可见且无裁剪。
  • 文档必须清晰可读 — 清晰、光照良好，无遮挡。

TPS 协议​

  • 本项目约定的最大 TPS 为 10 TPS。
  • 将请求均匀分布在时间上，而不是大批量发送。
  • 未经 Unico 团队正式批准，不得超过此限制。
  • 超过限制的请求可能会被自动丢弃或阻止。
  • 如需临时增加，需要事先正式协商。

集成​

端点​

环境基础 URL访问说明
Staginghttps://api.id.uat.unico.app开放测试必需
Productionhttps://api.id.unico.app仅在验收通过后需要严格的 TPS 控制

必需的请求头​

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

Payload 参数​

{
  "subject": {
    "duiType": 1,
    "code": "11032395702",
    "name": "User Name",
    "email": "[email protected]",
    "phone": "21998571922",
    "birthDate": "30/07/1989",
    "gender": "M"
  },
  "useCase": "Reprocessamento/Importação",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR...",
  "document": {
    "purpose": "Reprocessamento",
    "documentId": "doc-001",
    "files": [
      {
        "data": "doc_base64_frente",
        "faceDocumentMatch": true
      },
      {
        "data": "doc_base64_verso"
      }
    ]
  }
}
字段类型必需描述
subjectobject是用户标识数据。
subject.duiTypeinteger是文件类型标识符。参见下方的 duiType 值。
subject.codestring是CPF 或其他用户标识符。
subject.namestring是用户全名。
subject.emailstring否用户电子邮件。
subject.phonestring否用户电话号码。
subject.birthDatestring否用户出生日期（DD/MM/YYYY）。
subject.genderstring否用户性别（M 或 F）。
useCasestring是用例名称（"Reprocessamento" 或 "Importação de base"）。
subsidiaryIdstring否子公司 UUID（由 Unico 提供）。
imageBase64base64是用户自拍照转换为 base64 格式。
documentobject否与流程关联的文件数据。
document.purposestring否文件用途（例如，"Reprocessamento"）。
document.documentIdstring否文件标识符。
document.filesarray否文件图像列表。
document.files[].database64否文件图像转换为 base64 格式。
document.files[].faceDocumentMatchboolean否指示文件中的面部是否与提交的自拍照匹配。
duiType 值
国家代码描述
BR1巴西 CPF
BR5巴西护照
MX2墨西哥 CURP
AR6阿根廷护照
AR7阿根廷 DNI
US4美国 SSN
US11美国护照
US18美国驾驶执照
ID16印度尼西亚 NIK
NG8尼日利亚 NIN
CL9智利 RUN
EC10厄瓜多尔 NI
GT12危地马拉 CUI
UY13乌拉圭 CI
ZZ15电子邮件地址
ZZ17电话号码
MX25墨西哥 RFC（自然人）
CO26哥伦比亚 NIT
PE27秘鲁 RUC
CA28加拿大 SIN
DK29丹麦 CPR
GB30英国国民保险号码（NINO）
PL31波兰 PESEL
SE32瑞典个人号码（PNR）
AT34奥地利税号（STNR）
FI35芬兰个人身份代码（HETU）
—0未指定
—3Unico 内部标识符

重要说明​

  • 自拍照必须符合 ICAO 标准，具备适当的质量和光照。
  • 自拍照必须为 base64 格式。
  • 避免在没有 TPS 控制的情况下批量提交，这可能触发速率限制（参见下方的错误处理）。
  • 请始终先在 staging 环境中测试数据和集成。

响应​

成功 — 200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  }
}
字段类型描述
idstring流程标识符。请保存以备将来查询或后续实施 1:1 验证时使用。
statusinteger事务状态。
unicoId.resultstring身份验证能力响应。
identityFraudsters.resultstring欺诈风险分类能力响应。

图像处理错误

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

常见错误

4xx 范围的代码表示所提供数据的验证错误。5xx 范围的代码表示服务器端故障。

HTTP 代码错误类型可能原因建议操作
400Bad Request无效的 payload验证结构和内容。
401Unauthorizedtoken 过期或无效重新生成 token。
403ForbiddenAPI Key 不正确或权限不足验证凭证。
429Too Many Requests请求速率超出限制等待并遵守 TPS 限制。
500+Internal Server Error内部故障等待几秒后重试；如持续出现请提交工单。

错误处理​

  • 必须仔细监控 Rate Limit (HTTP 429)。请求过载可能阻塞管道。
  • 始终遵守与 Unico 约定的 TPS（参见 TPS 协议）。
  • 对于持续性故障 (5xx)，使用重试/退避控制进行重新处理。
最后更新 于