自带生物识别 (BYO)

默认情况下，开户的身份验证使用 CorpX 生物识别 — 我们生成人脸采集链接并管理整个流程。如果您已通过合作平台采集了客户的人脸生物识别数据，可以使用备选的 **BYO（Bring Your Own biometrics，自带生物识别）**流程：您将平台导出的证据发送给我们，我们直接向合作方验证其真实性。

必须启用

BYO 流程默认关闭。需要我们的团队在您的 tenant 上按提供商逐一启用 — 请联系支持并告知您使用的平台。未启用时，biometry 对象会被 422 拒绝。

支持的平台

提供商	`provider` 值
Unico	`unico`
SERPRO	`serpro`
IDWALL	`idwall`
SUMSUB	`sumsub`
ClearSale	`clearsale`
CAF	`caf`
Valid	`valid`

每个平台有自己的导出格式。您发送导出的文件 + 元数据 JSON（通常包含允许我们直接向合作方查询该验证有效性的哈希或 ID）。

与默认流程的差异

	CorpX 生物识别（默认）	自带生物识别 (BYO)
人脸采集	我们生成链接	已在您的平台完成
验证	流程内自动完成	我们向合作方核验有效性
开户条款确认	内嵌在流程中	我们托管的确认链接，按人发放
PF 审批	自动	必须事先审核
PJ 审批	事先审核	事先审核

流程

第 1 步：发送证据

首先，注册证据并获取上传 URL：

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/biometry-evidence" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clearsale",
    "fileName": "export-customer-12345.zip",
    "contentType": "application/zip"
  }'

{
  "evidenceId": "evd_5f4e3d2c1b0a",
  "uploadUrl": "https://kyc-archive.s3.sa-east-1.amazonaws.com/staging/...",
  "uploadExpiresAt": "2026-07-07T19:00:00Z",
  "scanStatus": "PENDING",
  "info": "O arquivo enviado passa por verificação de tipo, antivírus e sanitização antes de ser arquivado (poucos segundos). Arquivos infectados ou corrompidos são recusados e não ficam disponíveis."
}

然后通过 PUT 将平台导出的文件上传到 uploadUrl（预签名 URL，有效期 1 小时）：

curl -X PUT "{uploadUrl}" \
  -H "Content-Type: application/zip" \
  --data-binary @export-customer-12345.zip

文件被接收后 PUT 立即返回 200，但归档不是即时的：每个上传都会经过真实类型检测（依据文件头字节，而非扩展名）、病毒扫描和净化处理。PDF 会被栅格化，图片会被重新编码；被感染、损坏或类型不符的文件会被拒绝，不会进入审核。

第 2 步：携带 `biometry` 对象创建 accreditation

使用与 PF 和 PJ 相同的端点，在人员上包含 biometry 对象（PF 放在 person 内；PJ 放在每个 partners[] 项内）：

{
  "person": {
    "name": "Maria da Silva",
    "cpf": "12345678901",
    "birthDate": "1990-05-20",
    "email": "maria@email.com",
    "phone": "+5511999998888",
    "biometry": {
      "provider": "clearsale",
      "evidenceId": "evd_5f4e3d2c1b0a",
      "metadata": {
        "transactionHash": "8f7a6b5c4d3e2f1a...",
        "sessionId": "cs-session-998877"
      }
    }
  },
  "address": { "...": "..." }
}

字段	说明
`biometry.provider`	采集生物识别的平台（见上表）。须在您的 tenant 上启用。
`biometry.evidenceId`	第 1 步返回的 ID。
`biometry.metadata`	自由格式 JSON，包含允许我们向合作方验证证据的数据（哈希、会话/交易 ID 等）。具体格式取决于提供商 — 启用时支持团队会告知所需字段。

每个 accreditation 单一模式

同一个 accreditation 只使用一种生物识别模式：要么所有人都用 CorpX 生物识别（默认），要么所有人都用 BYO。PJ 使用 BYO 时，须为所有股东提供 biometry 对象。

第 3 步：开户条款确认

由于采集不是在我们的流程中完成的，每位自然人都需要在我们托管的页面上确认开户条款 — 以此形成正式的同意记录（确认人的日期/时间、IP 和设备信息）。

证据验证通过后，您会收到 accreditation.acceptance.link.created webhook，其中包含每人一个确认链接。同一 URL 会出现在 GET / POST 响应的 persons[].acceptanceLink（令牌已生成时）。
将链接交付给最终用户。页面会展示您的品牌（与我们的支持团队配置的 logo 和配色）以及开户条款。
确认链接 7 天后过期；使用重试端点重新生成。

在 iframe 中嵌入确认页面

您可以在自己的站点中通过 <iframe> 嵌入确认页面。默认情况下会被浏览器拦截 —— 我们的 HTML 响应会返回 Content-Security-Policy: frame-ancestors 'none'。如需放开，请联系支持团队并告知您站点的 HTTPS Origin（例如 https://app.yourcompany.com）；我们会将其加入您 tenant 的允许列表，CSP 将变为 frame-ancestors https://app.yourcompany.com ...。

允许列表规则：

仅支持 https://（http:// 一律不接受，包括测试环境）。
支持的写法：https://host、https://host:port 或 https://*.host（通配符仅允许在首个标签）。
每个 tenant 最多 10 个 Origin。

启用后的嵌入示例：

<iframe
  src="https://tenant.api.corpx.com/v1/accreditations/accept/tok_..."
  style="width: 100%; height: 720px; border: 0;"
  title="开户确认"
></iframe>

第 4 步：事先审核与开户

所有人的证据验证通过且确认记录完成后，accreditation 进入 PENDING_REVIEW — BYO 流程中即使 PF 也必须事先审核。批准后流程与默认流程完全相同：INTEGRATING → ACTIVE，webhook 也相同。

常见失败原因

在 POST 的 HTTP 响应中立即拒绝：

代码	HTTP	含义	处理方式
`provider_not_enabled`	422	提供商未在您的 tenant 上启用。	联系支持启用。
`unsupported_provider`	422	`provider` 不在受支持列表中。	请使用平台表中的取值之一。
`evidence_not_found`	422	`biometry.evidenceId` 不存在或不属于您的 tenant。	请先完成第 1 步再创建 accreditation。
`mixed_biometry_mode`	422	PJ 中部分股东使用 BYO、部分使用默认流程。	为所有股东发送 `biometry`，或都不发送。

随后通过 accreditation.failed webhook 结束流程（errorReason）：

`errorReason`	含义	处理方式
`evidence_invalid`	合作方未确认证据有效。	检查元数据中的哈希/ID 并重新发送。
`acceptance_timeout`	用户未在期限内确认。	重试以重新生成链接。
`castle_deny`	设备风险分析拦截了确认。	请联系支持。
`review_rejected`	事先审核被拒。	联系支持了解详情。

支持的平台​

与默认流程的差异​

流程​

第 1 步：发送证据​

第 2 步：携带 biometry 对象创建 accreditation​

第 3 步：开户条款确认​

在 iframe 中嵌入确认页面​

第 4 步：事先审核与开户​

常见失败原因​