开户流程 (Onboarding)
Accreditation（开户认证） API 让您能够以编程方式为您的最终客户开设账户 — 包括个人（PF）和企业（PJ）— 并通过人脸生物识别完成身份验证。
Onboarding API 正在受控发布中。集成前请联系我们的支持团队为您的 tenant 启用。
工作原理
整个流程分为四个主要阶段：
- 身份验证（人脸生物识别） — 每个相关自然人（PF 的持有人；PJ 的每位股东）都必须通过人脸生物识别完成身份验证。
- 公司文件（仅 PJ） — 按
company.legalForm通过POST /v1/accreditations/{id}/documents上传必填 PDF（可与生物识别并行）。详见 PJ 开户。 - 审核 — 根据不同的流程，开户会被自动批准，或需要分析师的事先审核。
- 在清算方开立账户 — 批准后，账户被开立并自动绑定到您的 tenant。您会收到最终的
accountId，即可开始操作（PIX、boleto、对账单等）。
对于 PF，如果该 CPF 已是账户持有人，则没有需要新开的账户。对于已开通自动携带的租户（需合同约定，默认不开通），accreditation 以 PENDING_CONSENT 创建，并返回一个链接，供持有人本人授权您操作其已有账户 — 授权前需完成身份验证并披露余额。未开通时，accreditation 会以 existing_partner_account 失败，携带需向支持团队申请。参见已有账户的持有人。
有两种生物识别流程：
| 流程 | 工作方式 | 审批 |
|---|---|---|
| CorpX 生物识别（默认） | 我们为每个人生成一个人脸采集链接（由 Unico 提供技术支持）。您将链接交付给最终用户，用户在浏览器或手机上完成采集流程。 | PF：人脸验证通过后自动批准。PJ：需事先审核。 |
| 自带生物识别（备选） | 您已通过合作平台（Unico、SERPRO、IDWALL、SUMSUB、ClearSale、CAF、Valid）采集了人脸生物识别数据，将导出的证据 + 元数据发送给我们进行验证。最终用户需在我们托管的页面上确认开户条款。 | 始终需要事先审核。 需要在您的 tenant 上专门启用。 |
使用 CorpX 生物识别的默认流程是最简单的路径：您只需将链接交付给最终用户并等待 webhook。自带生物识别流程需要额外启用 — 参见自带生物识别。
状态机
每个 accreditation 都会经历以下状态机：
状态说明
| 状态 | 含义 | 集成方应采取的操作 |
|---|---|---|
PENDING_BIOMETRY | 等待一人或多人完成人脸生物识别。 | 将人脸（或确认）链接交付给每个待处理的人。必要时重发。 |
PENDING_CONSENT | 仅 PF，且仅在已开通自动携带时：该 CPF 已有账户，无需新开账户 — 需持有人授权您操作其已有账户。 | 将 consentLink 交付给持有人。详见已有账户的持有人。 |
BIOMETRY_APPROVED | 所有生物识别均已通过。过渡状态。 | 无 — 等待下一个 webhook。 |
PENDING_REVIEW | 等待分析师事先审核。 | 无 — 等待。通常 1 个工作日内完成。 |
INTEGRATING | 正在清算方开立账户。过渡状态。 | 无 — 等待。 |
ACTIVE | 账户已开立，可以操作。 | 保存 accountId 并开始操作。 |
FAILED | 流程结束，未开立账户。 | 检查 errorReason。根据原因，重试生物识别或用更正后的数据创建新的 accreditation。 |
跟踪进度
您有两种互补的方式跟踪每个 accreditation：
- Webhook（推荐） —
accreditation.updated事件在每次状态转换时发出，此外还有特定事件（人脸链接创建、账户激活、失败）。参见 Onboarding Webhooks。 - 轮询 —
GET /v1/accreditations/pf和GET /v1/accreditations/pj返回聚合状态和每个人的详情（生物识别状态、链接、过期时间）。
可选字段 callbackUri 会在持有人完成其步骤后把他带回您的应用，并把处理结果带在 URI 上 — 这对体验有帮助，但不能替代上述两种方式中的任何一种。参见返回您的应用。
与 tenant 的绑定
CPF/CNPJ 仅在生物识别（或 BYO 确认）通过后才会绑定到 tenant。在 PENDING_BIOMETRY 期间没有 accountId，且 POST 不会去重：用同一证件号重复请求会创建新的 accreditation（201）。请用 POST /v1/accreditations/{id}/cancel 取消放弃的待处理流程（FAILED / errorReason=cancelled）。
确认之后，清算账户会自动绑定到创建该 accreditation 的 tenant。对您自己的 tenant 已 claim 的证件号再次 POST 会返回 409 already_accredited。
多个 tenant 共享账户
当持有人通过授权流程分别授权多个 tenant 时（参见已有账户的持有人），同一个 PF 账户可由多个 tenant 操作。此时：
- 这是同一个账户 — 余额、对账单与 Pix 密钥均为共享。每个 tenant 有各自指向它的
accountId。 - 所有获授权的 tenant 都会收到每笔动账的 webhooks。非经您 API 发起的操作（由其他获授权 tenant 或持有人发起）会带
external: true。 - 新 tenant 获得授权时，此前的授权不会被撤销。如果您已在操作该账户并收到
account.shared_access.granted，说明另一个 tenant 也开始操作它 — 若与您的业务不符，请联系支持。 - 持有人可通过支持撤销其中任一授权；撤销后，被撤销 tenant 对该账户的调用返回
403。