Abertura de contas

Webhooks de Onboarding

Todos os eventos de onboarding seguem o envelope padrão de webhooks da plataforma (mesmo formato de entrega, autenticação, retries e idempotência). Esta página documenta os eventos específicos de accreditation.

Eventos

EventoQuando é emitido
accreditation.pf.createdUma accreditation PF foi criada.
accreditation.pj.createdUma accreditation PJ foi criada.
accreditation.biometry.link.createdUm link de captura facial foi gerado para uma pessoa (emitido por pessoa; reemitido em retry).
accreditation.acceptance.link.createdUm link de aceite de termos foi gerado para uma pessoa (somente em fluxos habilitados sob demanda pela CorpX).
accreditation.consent.link.createdUm link de autorização foi gerado porque o CPF já tem conta (reemitido em retry).
account.shared_access.grantedOutro tenant passou a operar uma conta que você já operava, autorizado pelo titular.
accreditation.updatedToda transição de estado da accreditation. Fonte de verdade do progresso.
accreditation.activeConta aberta com sucesso — accountId pronto para operar.
accreditation.failedProcesso encerrado sem abertura de conta.
Recomendação

Assine accreditation.updated como fonte de verdade do progresso, e use accreditation.active / accreditation.failed como gatilhos terminais no seu sistema. Os eventos de link servem para automatizar a entrega dos links aos usuários finais.

O callbackUri não substitui estes eventos

Se você usa o retorno ao seu app, o outcome que chega na URI é uma dica de interface: ele viaja na barra de endereço e o próprio titular pode editá-lo. Use-o só para escolher que tela mostrar quando o usuário voltar. Todo gatilho com efeito no seu sistema continua vindo daqui — ou de GET /v1/accreditations/{accreditationId}.

accreditation.updated

Emitido em toda transição de estado, com o status anterior, o atual e o detalhe por pessoa.

{
  "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"
      }
    ]
  }
}
Campo do dataDescrição
accreditationIdID da accreditation.
typepf ou pj.
documentCPF (PF) ou CNPJ (PJ) do titular.
previousStatus / statusTransição de estado (vocabulário da Visão Geral).
persons[]Detalhe por pessoa: cpf, name, biometryStatus (PENDING, APPROVED, FAILED, EXPIRED) e, quando houver termo de aceite, acceptanceStatus (PENDING, ACCEPTED).
errorReasonPresente quando status = FAILED.

accreditation.biometry.link.created

Emitido quando um link de captura facial é gerado para uma pessoa (na criação da accreditation e em cada retry).

{
  "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"
  }
}

No PJ, este evento é emitido uma vez por sócio — use o cpf para saber a quem entregar cada link.

accreditation.acceptance.link.created

Emitido quando um link de aceite de termos é gerado para uma pessoa. Só ocorre em fluxos habilitados sob demanda pela CorpX; no fluxo padrão este evento não é emitido.

{
  "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

Emitido quando o CPF informado já tem conta e a accreditation nasce em PENDING_CONSENT: em vez de abrir conta nova, o titular precisa autorizar que você opere a conta existente. Entregue o consentLink a ele. Reemitido a cada retry.

{
  "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"
  }
}

Detalhes da jornada em Titular que já tem conta.

accreditation.active

Evento terminal de sucesso — a conta está pronta para operar.

{
  "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"
  }
}

Quando a accreditation veio do fluxo de consent, o data traz dois campos adicionais:

Campo do dataDescrição
sharedAccounttrue — a conta já existia e continua sendo operada por quem o titular já havia autorizado. Saldo e extrato são compartilhados.
partnerAccountIdIdentificador do titular no liquidante, comum a todos os tenants autorizados. Útil para reconciliação.

account.shared_access.granted

Emitido para os tenants que já operavam uma conta quando o titular autoriza um novo tenant a operá-la também. O seu acesso não muda — este evento existe para você saber que a conta passou a ser movimentada por mais alguém.

{
  "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"
  }
}
Campo do dataDescrição
accountIdA sua conta (o identificador que você já usa), não a do tenant que entrou.
partnerAccountIdTitular no liquidante — é o que evidencia que se trata da mesma conta.
grantedAtMomento da autorização do titular.
reasonaccount_holder_authorized_another_tenant.
Não reconheceu?

Se o compartilhamento não faz sentido para o seu caso, acione o suporte: o titular pode revogar o acesso concedido, e a partir da revogação as chamadas do tenant revogado para aquela conta respondem 403.

accreditation.failed

Evento terminal de falha — o processo foi encerrado sem abertura de conta.

{
  "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": "Biometria facial não concluída dentro do prazo de 7 dias"
  }
}

Valores comuns de errorReason:

errorReasonSignificado
biometry_failedBiometria facial reprovada.
biometry_expiredLink de facial expirou sem conclusão.
evidence_invalidEvidência de biometria externa não validada no parceiro (fluxos habilitados sob demanda).
acceptance_timeoutTermo de aceite não confirmado dentro do prazo (fluxos habilitados sob demanda).
cancelledCancelada pelo integrador via POST /v1/accreditations/{id}/cancel (ainda em PENDING_BIOMETRY ou PENDING_CONSENT).
review_rejectedRejeitada na análise prévia.
partner_rejectedRejeitada pelo liquidante na abertura da conta.
partner_validation_failedO liquidante recusou um dado do cadastro. Veja o bloco partner abaixo.
partner_unavailableIndisponibilidade do liquidante. É transitório: reenvie o credenciamento.
consent_declinedO titular recusou autorizar o acesso à conta que já tinha.
consent_expiredO titular não concluiu a autorização no prazo (link de 7 dias, jornada de 30 dias).
consent_facial_failedA verificação de identidade não confirmou que a pessoa é a titular do CPF.
consent_link_failedNão foi possível preparar ou concluir a autorização (ex.: dados do titular divergentes entre o pedido e a autorização). Acione o suporte.
castle_denyA análise de dispositivo barrou o aceite — tanto no termo de aceite quanto na autorização de portabilidade. Acione o suporte.
existing_partner_accountCPF/CNPJ que já tem conta. A portabilidade é manual: o titular deve solicitá-la ao suporte. Em PF, se o seu tenant tiver a portabilidade automática habilitada, este motivo não ocorre — o caminho é o consentLink. Para PJ não existe fluxo de autorização em página.

Quando a recusa vem do liquidante, data traz também o bloco partner com o que ele informou — o mesmo bloco aparece em GET /v1/accreditations/{id}, para consulta e webhook não divergirem:

"partner": {
  "code": "request.body.invalid",
  "field": "address.number",
  "message": "A solicitação é inválida: O número não pode exceder 10 caracteres."
}

As três chaves são opcionais: o bloco reflete o que o liquidante enviou, e há recusas que chegam só com message. Use-o em log e suporte — a decisão do seu código continua sendo por errorReason.

accreditation.pf.created / accreditation.pj.created

Emitidos na criação da accreditation (início do workflow), como confirmação assíncrona do POST. Assine-os no portal (Settings → Webhooks) ou via PUT na subscription.

{
  "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"
  }
}