Onboarding Webhooks

所有 onboarding 事件都遵循平台的标准 webhook 信封格式（相同的投递格式、认证、重试和幂等机制）。本页记录 accreditation 专属的事件。

事件列表

事件	触发时机
`accreditation.pf.created`	PF accreditation 已创建。
`accreditation.pj.created`	PJ accreditation 已创建。
`accreditation.biometry.link.created`	为某人生成了人脸采集链接（按人发出；重试时重新发出）。
`accreditation.acceptance.link.created`	为某人生成了条款确认链接（仅自带生物识别流程）。
`accreditation.consent.link.created`	因该 CPF 已有账户而生成了授权链接（重试时会重新发出）。
`account.shared_access.granted`	经持有人授权，另一个 tenant 开始操作您已在操作的账户。
`accreditation.updated`	accreditation 的每次状态转换。进度的事实来源。
`accreditation.active`	账户成功开立 — `accountId` 可以操作。
`accreditation.failed`	流程结束，未开立账户。

建议

订阅 accreditation.updated 作为进度的事实来源，将 accreditation.active / accreditation.failed 作为系统中的终态触发器。链接类事件用于自动化向最终用户交付链接。

callbackUri 不能替代这些事件

如果您使用返回您的 App，URI 中携带的 outcome 只是界面提示：它出现在地址栏中，持有人本人即可修改。请仅用它决定用户返回时展示哪个页面。任何会在您系统中产生实际影响的触发，仍应来自这里 — 或来自 GET /v1/accreditations/{accreditationId}。

`accreditation.updated`

在每次状态转换时发出，包含之前的状态、当前状态和每个人的详情。

{
  "id": "evt_acr_upd_001",
  "type": "accreditation.updated",
  "occurredAt": "2026-07-07T18:20:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "previousStatus": "PENDING_BIOMETRY",
    "status": "INTEGRATING",
    "persons": [
      {
        "cpf": "12345678901",
        "name": "Maria da Silva",
        "biometryStatus": "APPROVED"
      }
    ]
  }
}

`data` 字段	说明
`accreditationId`	Accreditation ID。
`type`	`pf` 或 `pj`。
`document`	持有人的 CPF（PF）或 CNPJ（PJ）。
`previousStatus` / `status`	状态转换（词汇见概览）。
`persons[]`	每人详情：`cpf`、`name`、`biometryStatus`（`PENDING`、`APPROVED`、`FAILED`、`EXPIRED`），BYO 流程中还有 `acceptanceStatus`（`PENDING`、`ACCEPTED`）。
`errorReason`	`status = FAILED` 时存在。

`accreditation.biometry.link.created`

为某人生成人脸采集链接时发出（创建 accreditation 时及每次重试时）。

{
  "id": "evt_acr_link_001",
  "type": "accreditation.biometry.link.created",
  "occurredAt": "2026-07-07T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "biometryLink": "https://cadastro.unico.app/process/abc123...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

PJ 中此事件按股东逐一发出 — 使用 cpf 判断每个链接应交付给谁。

`accreditation.acceptance.link.created`

仅自带生物识别流程。为某人生成确认链接时发出。

{
  "id": "evt_acr_acc_001",
  "type": "accreditation.acceptance.link.created",
  "occurredAt": "2026-07-07T18:05:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "acceptanceLink": "https://tenant.api.corpx.com/v1/accreditations/accept/tok_...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

`accreditation.consent.link.created`

当所填 CPF 已有账户且 accreditation 以 PENDING_CONSENT 创建时发出：此时不是新开账户，而是需要持有人授权您操作其已有账户。请将 consentLink 交付给持有人。每次重试都会重新发出。

{
  "id": "acr-acr_5c4b3a2f1e0d-consent-12345678901-1",
  "type": "accreditation.consent.link.created",
  "occurredAt": "2026-07-23T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_5c4b3a2f1e0d",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "consentId": "cns_8f2a1c9d4b70",
    "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
    "linkExpiresAt": "2026-07-30T18:00:00Z",
    "status": "PENDING_CONSENT"
  }
}

流程详情见已有账户的持有人。

`account.shared_access.granted`

当持有人授权新的 tenant 也可操作某账户时，发给原先已在操作该账户的各个 tenant。您的权限不变 — 该事件的作用是让您知道该账户现在也会被他人动账。

{
  "id": "acr-acr_5c4b3a2f1e0d-shared-tenant-acme",
  "type": "account.shared_access.granted",
  "occurredAt": "2026-07-23T18:40:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
    "tenantId": "tenant-acme",
    "partnerAccountId": "hld_7c1e...",
    "grantedAt": "2026-07-23T18:40:00Z",
    "reason": "account_holder_authorized_another_tenant"
  }
}

`data` 字段	说明
`accountId`	您的账户（您已在使用的标识符），不是新加入 tenant 的那个。
`partnerAccountId`	清算方的持有人标识 — 用于证明是同一个账户。
`grantedAt`	持有人授权的时间。
`reason`	`account_holder_authorized_another_tenant`。

不认识这笔授权？

若该共享与您的业务不符，请联系支持：持有人可以撤销已授予的权限，撤销后被撤销 tenant 对该账户的调用返回 403。

`accreditation.active`

成功的终态事件 — 账户可以操作。

{
  "id": "evt_acr_active_001",
  "type": "accreditation.active",
  "occurredAt": "2026-07-07T18:25:41.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "ACTIVE",
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8"
  }
}

若该 accreditation 来自授权（consent）流程，data 会额外包含两个字段：

`data` 字段	说明
`sharedAccount`	`true` — 该账户已经存在，且持有人此前授权的各方继续保留操作权限。余额与对账单为共享。
`partnerAccountId`	清算方的持有人标识，所有获授权 tenant 相同，便于对账。

`accreditation.failed`

失败的终态事件 — 流程结束且未开立账户。

{
  "id": "evt_acr_failed_001",
  "type": "accreditation.failed",
  "occurredAt": "2026-07-08T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "FAILED",
    "errorReason": "biometry_expired",
    "errorMessage": "Facial biometrics not completed within the 7-day deadline"
  }
}

常见的 errorReason 值：

`errorReason`	含义
`biometry_failed`	人脸生物识别被拒。
`cancelled`	集成方通过 `POST /v1/accreditations/{id}/cancel` 取消（仍处于 `PENDING_BIOMETRY` 或 `PENDING_CONSENT`）。
`biometry_expired`	人脸链接过期未完成。
`evidence_invalid`	BYO 证据未通过合作方验证（BYO 流程）。
`acceptance_timeout`	未在期限内确认条款（BYO 流程）。
`review_rejected`	事先审核被拒。
`partner_rejected`	开户时被清算方拒绝。
`consent_declined`	持有人拒绝授权访问其已有账户。
`consent_expired`	持有人未在期限内完成授权（链接 7 天，流程 30 天）。
`consent_facial_failed`	身份验证未能确认该人为 CPF 持有人。
`consent_link_failed`	无法准备或完成授权（例如申请与授权之间持有人数据不一致）。请联系支持。
`castle_deny`	设备风险分析拦截了确认 —— BYO 条款确认与携带授权都适用。请联系支持。
`existing_partner_account`	已有账户的 CPF/CNPJ。携带流程为人工办理：持有人需向支持团队申请。对 PF，若您的租户已开通自动携带，则不会出现该原因 — 改为使用 `consentLink`。PJ 没有托管授权页面流程。

`accreditation.pf.created` / `accreditation.pj.created`

在 accreditation 创建时（工作流启动）发出，作为 POST 的异步确认。可在门户（Settings → Webhooks）或通过对 subscription 的 PUT 订阅。

{
  "id": "acr-acr_1a2b3c4d5e6f-created",
  "type": "accreditation.pj.created",
  "occurredAt": "2026-07-07T18:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_1a2b3c4d5e6f",
    "type": "pj",
    "document": "12345678000199",
    "status": "PENDING_BIOMETRY",
    "biometryMode": "external"
  }
}

事件列表​

accreditation.updated​

accreditation.biometry.link.created​

accreditation.acceptance.link.created​

accreditation.consent.link.created​

account.shared_access.granted​

accreditation.active​

accreditation.failed​

accreditation.pf.created / accreditation.pj.created​