Abertura de Contas (Onboarding)

As APIs de Accreditation permitem abrir contas para os seus clientes finais — pessoas físicas (PF) e pessoas jurídicas (PJ) — de forma programática, com verificação de identidade por biometria facial.

Habilitação

As APIs de onboarding estão em rollout controlado. Solicite a habilitação para o seu tenant ao nosso time de suporte antes de integrar.

Como funciona

O processo tem três grandes etapas:

Verificação de identidade (biometria facial) — cada pessoa física envolvida (o titular no PF; cada sócio no PJ) precisa ter a identidade verificada por biometria facial.
Documentos societários (só PJ) — envie os PDFs exigidos pelo company.legalForm via POST /v1/accreditations/{id}/documents (em paralelo com a biometria). Detalhes em Abertura PJ.
Análise — dependendo do fluxo, a abertura é aprovada automaticamente ou passa por análise prévia de um analista.
Abertura da conta no liquidante — após aprovação, a conta é aberta e vinculada automaticamente ao seu tenant. Você recebe o accountId definitivo e pode começar a operar (PIX, boletos, extrato etc.).

CPF que já tem conta

Para PF, se o CPF já for correntista não existe conta nova a abrir. Para tenants com portabilidade automática habilitada (depende de contrato; não vem ligada), a accreditation nasce em PENDING_CONSENT e devolve um link para o titular autorizar que você opere a conta que ele já tem — com verificação de identidade e divulgação de saldo antes do aceite. Sem essa habilitação, a accreditation falha com existing_partner_account e a portabilidade é solicitada ao suporte. Veja Titular que já tem conta.

A verificação de identidade usa a biometria CorpX: nós geramos um link de captura facial (powered by Unico) para cada pessoa. Você entrega o link ao usuário final, que faz a jornada de captura no navegador ou celular.

Fluxo	Como funciona	Aprovação
Biometria CorpX	Link de captura facial por pessoa, gerado por nós e entregue por você.	PF: automática após a facial aprovada. PJ: análise prévia.

O que você precisa fazer

Entregar o link ao usuário final e aguardar os webhooks. O resto da jornada — captura, validação, abertura da conta — acontece do nosso lado.

Máquina de estados

Toda accreditation percorre a seguinte máquina de estados:

Status

Status	Significado	Ação esperada do integrador
`PENDING_BIOMETRY`	Aguardando a biometria facial de uma ou mais pessoas.	Entregue o link de facial (ou de aceite) a cada pessoa pendente. Reenvie se necessário.
`PENDING_CONSENT`	Só PF, e só com portabilidade automática habilitada: o CPF já tem conta, então não há conta nova a abrir — o titular precisa autorizar você a operar a conta existente.	Entregue o `consentLink` ao titular. Detalhes em Titular que já tem conta.
`BIOMETRY_APPROVED`	Todas as biometrias aprovadas. Estado transitório.	Nenhuma — aguarde o próximo webhook.
`PENDING_REVIEW`	Aguardando análise prévia de um analista.	Nenhuma — aguarde. O prazo típico é de 1 dia útil.
`INTEGRATING`	Conta sendo aberta no liquidante. Estado transitório.	Nenhuma — aguarde.
`ACTIVE`	Conta aberta e pronta para operar.	Guarde o `accountId` e comece a operar.
`FAILED`	Processo encerrado sem abertura de conta.	Verifique `errorReason`. Em `consent_*`, o titular não autorizou (ou não concluiu) o acesso à conta que já tinha. Nos demais casos, retry de biometria ou nova accreditation.

Acompanhando o progresso

Você tem duas formas complementares de acompanhar cada accreditation:

Webhooks (recomendado) — o evento accreditation.updated é emitido a cada transição de estado, além de eventos específicos (link de facial criado, conta ativa, falha). Veja Webhooks de Onboarding.
Polling — GET /v1/accreditations/pf e GET /v1/accreditations/pj retornam o status agregado e o detalhe por pessoa (estado da biometria, link, expiração).

O campo opcional callbackUri traz o titular de volta ao seu app quando ele termina a etapa dele, com o desfecho na URI — útil para a experiência, mas não substitui nenhuma das duas formas acima. Veja Retorno ao seu app.

Vínculo com o seu tenant

O CPF/CNPJ só é atrelado ao tenant após a biometria ser confirmada. Enquanto PENDING_BIOMETRY, não há accountId e o POST não deduplica: repetir com o mesmo documento cria outra accreditation (201). Use POST /v1/accreditations/{id}/cancel para encerrar pendências abandonadas (FAILED / errorReason=cancelled).

Depois da confirmação, a conta aberta no liquidante fica automaticamente vinculada ao tenant que criou a accreditation — sem passo adicional de ativação. Um novo POST com o documento já claimado pelo seu próprio tenant retorna 409 already_accredited.

Conta compartilhada entre tenants

Uma conta PF pode ser operada por mais de um tenant, quando o titular autoriza cada um deles pelo fluxo de consent (Titular que já tem conta). Nesse caso:

É a mesma conta — saldo, extrato e chaves Pix são compartilhados. Cada tenant tem seu próprio accountId apontando para ela.
Todos os tenants autorizados recebem os webhooks de cada movimento. Operações originadas fora da sua API (por outro tenant autorizado ou pelo próprio titular) chegam com external: true.
Autorizações anteriores não são revogadas quando um novo tenant é autorizado. Se você já operava a conta e recebe account.shared_access.granted, outro tenant passou a operá-la também — se isso não faz sentido para o seu caso, fale com o suporte.
O titular pode revogar qualquer um dos acessos pelo suporte; a partir daí as chamadas do tenant revogado para aquela conta respondem 403.

Arquivos comprobatórios

GET /v1/accreditations/{accreditationId}/artifacts devolve as evidências arquivadas do processo: os PDFs societários que você enviou, o documento de identidade capturado na biometria (unico_id_document, em geral o RG em PDF) e, quando o provedor libera, a selfie (unico_selfie) e o JWT do conjunto probatório (unico_evidence_set). Cada item já vem com uma downloadUrl pré-assinada, válida por cerca de 10 minutos.

curl -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: $TENANT" \
  https://api.corpx.com/v1/accreditations/acr_891418ce2f67/artifacts

{
  "accreditationId": "acr_891418ce2f67",
  "count": 2,
  "items": [
    {
      "artifactId": "art_7c1d90f2ab34",
      "kind": "unico_evidence_set",
      "cpf": "12345678901",
      "fileName": "unico_evidence_set.jwt",
      "contentType": "application/jwt",
      "sizeBytes": 14203,
      "createdAt": "2026-08-15T18:42:03Z",
      "scanStatus": "APPROVED",
      "metadata": { "unicoProcessId": "cst_3bd257e7201d441379256746" },
      "downloadUrl": "https://..."
    }
  ]
}

downloadUrl só aparece com scanStatus: "APPROVED": todo upload passa por checagem de tipo, antivírus e sanitização antes de ser arquivado. Enquanto o arquivo está em PENDING, consulte de novo em alguns segundos.

Habilitação e escopo

A rota entrega biometria do titular, então depende de dois interruptores independentes:

a feature kyc_artifacts precisa estar habilitada no seu tenant (fale com o suporte — exige previsão contratual), senão a resposta é 403 feature_disabled;
a credencial precisa carregar o escopo kyc.read. O escopo genérico read não é aceito, de propósito: nenhuma credencial existente passa a baixar rosto de cliente sem uma decisão explícita.

Os mesmos arquivos aparecem no detalhe da accreditation no seu backoffice, para quem tem a permissão backoffice:accreditations (nesse caso não há escopo envolvido, só a feature).