返回您的应用（callbackUri）

在开户与携带（portability）流程中，持有人会离开您的应用，在我们的页面上完成人脸采集（或授权），最后停留在 CorpX 的完成页上。可选字段 callbackUri 让这个环节形成闭环：该步骤结束后，持有人会被带回您的应用或网站，并且处理结果就带在这个 URI 上。

两种流程都适用，因为它们都通过同一个端点进入：

• PF 开户（POST /v1/accreditations/pf）与 PJ 开户（POST /v1/accreditations/pj）；
• 自动携带，使用的同样是 POST /v1/accreditations/pf。

前提条件：登记该 URI

该 URI 必须事先为您的 tenant 登记。请联系 CorpX 支持团队，准确告知您将使用的 URI（或多个 URI）——登记由我们的团队完成。

比对是精确匹配的。如果您登记的是 https://app.yourcompany.com/onboarding/done，那么您必须发送这个字符串；我们只会在末尾追加结果参数。不支持通配符，也不做前缀匹配：https://app.yourcompany.com/onboarding/done/extra 属于另一个 URI，需要单独登记。

发送未登记的 URI 会拒绝本次创建，返回 400 invalid_callback_uri —— 您会当场知道，而不是等持有人走完整个流程之后才发现。

可接受的形式

https://	https://app.yourcompany.com/onboarding/done
您应用的自定义 scheme（deeplink，深度链接）	yourcompany://onboarding/done

不被接受的形式

• 无 TLS 的 http://，以及任何会被浏览器执行或从磁盘读取的 scheme（javascript:、data:、file:、blob:）；
• 内嵌凭证（https://user:password@...）；
• localhost、内网地址（10.x、192.168.x、172.16–31.x、169.254.x、::1、fd00::/8）以及本地后缀（.local、.internal）；
• https 中使用字面 IP 地址 —— 请使用域名；
• 片段标识符（#），因为它会在参数之前终止该 URI；
• 没有域名的主机（https://intranet/）。

如何发送

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/pf" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{
    "person": { "...": "..." },
    "address": { "...": "..." },
    "callbackUri": "https://app.yourcompany.com/onboarding/done"
  }'

该字段是可选的。不填写时一切照旧：持有人会停留在 CorpX 的完成页上，与此前一致。

被接受的 URI 也会在 POST 的响应以及 GET /v1/accreditations/{id} 中通过 callbackUri 返回。

返回时携带的参数

参数	何时出现	说明
accreditationId	始终	与您在创建时收到的 accreditationId 相同。
outcome	始终	该步骤的处理结果（见下表）。
personId	针对单个人的步骤（生物识别与确认）	该人在此 accreditation 中的标识符，自创建起即通过 persons[].personId 返回。我们绝不会在 URI 中传送 CPF：URI 会留在浏览器历史、代理日志和应用遥测中。
remainingPeople	涉及多人的 accreditation	还有多少人尚未完成该步骤。0 表示这是最后一个。

某位 PJ 股东完成人脸采集、且仍有一位股东待处理时的返回示例：

https://app.yourcompany.com/onboarding/done?accreditationId=acr_9f8e7d6c5b4a&outcome=biometry_approved&personId=prs_3b1c9a7f2e4d&remainingPeople=1

outcome 取值说明

负面结果沿用您在 webhook 中已经处理的那套 errorReason 字符串。

outcome	何时出现
biometry_approved	人脸生物识别通过。
biometry_pending	自拍已提交，但在持有人返回的那一刻结果仍在分析中。这是最常见的情况 —— 结果随后会通过 webhook 送达。
biometry_failed	人脸生物识别未通过。可以重试。
biometry_expired	生物识别链接已过期。可以重试。
acceptance_recorded	自带生物识别（BYO）流程的确认已记录。
acceptance_expired	确认链接已过期。
acceptance_blocked	确认在设备风险分析中被拦截。
consent_accepted	持有人授权了携带。
consent_declined	持有人拒绝了。
consent_expired	授权链接已过期。
consent_identity_failed	持有人的身份验证未通过。
consent_blocked	授权在设备风险分析中被拦截。
error	我方发生了预期之外的故障。请不要据此对流程下任何结论；请查询该 accreditation。

biometry_approved 不等于账户已激活

在开户流程中，完成生物识别并不等于完成 accreditation：后面还有审核、与清算机构的对接以及激活。biometry_approved 加上 remainingPeople=0 只表示生物识别这一步结束了 —— 仅此而已。

只有当 accreditation.active webhook 送达（或 GET /v1/accreditations/{id} 返回 ACTIVE）并带上 accountId 时，账户才可以开始操作。

这些参数不能证明任何事情

它们出现在地址栏中，持有人本人就可以修改。它们没有签名：这只是给界面用的提示，让您的应用在用户返回时决定展示哪个界面。

任何会产生实际效果的决定 —— 放行权限、把注册标记为完成、开启某项操作 —— 都必须依据：

• webhook（accreditation.updated、accreditation.active、accreditation.failed），或者
• 调用 GET /v1/accreditations/{accreditationId} 查询。

请把这次返回理解为"用户回到了我的应用，结果大概是这样"，并通过服务器到服务器的通道去确认。

有多位股东的 PJ

每位股东都有各自的链接，因此每位股东都会产生各自的返回，并带上完成者的 personId。remainingPeople 说明是否还有人未完成，并且恰好有一次返回带有 remainingPeople=0。

对您的应用而言，有两点很重要：

• remainingPeople=0 表示没有待处理项了，而不是所有人都通过了。被拒的股东可以重做生物识别，在他重做之前不计为待处理。每个人的单独状态通过 GET 中的 persons[].biometryStatus 返回。
• 单个人的结果（outcome）与整体情况（remainingPeople）是两类不同的信息，特意放在一起返回。

不会发生跳转的情况

在以下情况下，持有人会停留在我们的完成页上，且不会报错：

• 该 accreditation 没有 callbackUri；
• 该 URI 在流程进行途中被从白名单中移除 —— 授权会在跳转的那一刻重新校验，移除立即生效；
• 无法拼装出返回用的 URI。

这些情况下 accreditation 仍会正常推进；只是不会跳回而已。由于真正的结果通过 webhook 送达，不会有任何信息丢失。

Deeplink 与浏览器

跳转是通过我们的一个页面、以可见链接的方式完成的，而不是 HTTP 重定向：应用自定义 scheme 并不能在所有浏览器中可靠地穿过重定向。如果应用未安装，持有人看到的是该链接和结果提示，而不是浏览器的错误页面。