跳转到主要内容

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

本指南介绍如何在 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 标准（浅色背景、面部居中、无遮挡识别的配件、适当的光照）。
  • 推荐尺寸：1920x1080 或 1080x1920 比例。
  • 最大大小：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 值
值描述
0未指定
1巴西 — CPF
2墨西哥 — CURP
3Unico 内部标识符
4美国 — SSN
5巴西 — 护照
6阿根廷 — 护照
7阿根廷 — DNI
8尼日利亚 — NIN
9智利 — RUN
10厄瓜多尔 — NI
11美国 — 护照
12危地马拉 — CUI
13乌拉圭 — CI
15电子邮件地址
16印度尼西亚 — NIK
17电话号码
18美国 — 驾驶执照

重要说明​

  • 自拍照必须符合 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)，使用重试/退避控制进行重新处理。
最后更新 于