Skip to navigation

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:

  1. 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.
  2. 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.
  3. Análise — dependendo do fluxo, a abertura é aprovada automaticamente ou passa por análise prévia de um analista.
  4. 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.

FluxoComo funcionaAprovação
Biometria CorpXLink 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:

PF cujo CPF já tem conta Titular autoriza (identidadeverificada) Recusa, expiração ou identidadenão confirmada Biometria aprovada (todas as pessoas) Reprovada ou expirada PF com biometria CorpX (automático) toda PJ (e PF sinalizada para análise) Aprovada pelo analista Rejeitada Conta aberta no liquidante Rejeitada pelo liquidante POST /v1/accreditations/pf ou /pj PENDING_BIOMETRY PENDING_CONSENT ACTIVE FAILED BIOMETRY_APPROVED INTEGRATING PENDING_REVIEW

Status

StatusSignificadoAção esperada do integrador
PENDING_BIOMETRYAguardando 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_CONSENTSó 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_APPROVEDTodas as biometrias aprovadas. Estado transitório.Nenhuma — aguarde o próximo webhook.
PENDING_REVIEWAguardando análise prévia de um analista.Nenhuma — aguarde. O prazo típico é de 1 dia útil.
INTEGRATINGConta sendo aberta no liquidante. Estado transitório.Nenhuma — aguarde.
ACTIVEConta aberta e pronta para operar.Guarde o accountId e comece a operar.
FAILEDProcesso 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).

Biometria centralizada

Alguns tenants não usam o link da Unico nem o objeto biometry. A abertura cria a verificação no provedor de biometria do próprio tenant e a conta chega pronta: você não chama o liquidante.

  • Não envie biometry. A resposta é 422 biometry_not_accepted.
  • PJ exige exatamente um sócio com isAdministrator: true (422 administrator_required). Só essa pessoa faz a captura e recebe biometryLink; os demais sócios não têm link, e o retry para eles responde 422 administrator_required.
  • Sem conta própria do tenant no provedor, a verificação abre na conta da CorpX. A criação só responde 503 kyc_not_configured quando nenhuma das duas está configurada.
  • O 201 traz persons[].biometryLink, a página hospedada. Ao fim da captura ela volta ao seu callbackUri com outcome (biometry_approved, biometry_pending, biometry_failed, biometry_expired), como na biometria CorpX. Quem tem app próprio pede um token em POST /v1/accreditations/{id}/capture e relê os blobs do FaceTec nas rotas públicas /start e /session. O passo a passo do link, do SDK, do pedido do pacote (bundle id, application id, domínios) e das linguagens está no guia de captura facial. O app não fala com o provedor.
  • Documento societário, nesse modo, vai em contentBase64 (PDF de até 4 MB) no POST .../documents, e só os kinds company_articles, company_proof_of_address e financial_statements. Sem o campo, 422 document_body_required; outro kind, 422 invalid_kind; recusado pelo provedor, 422 document_not_accepted.
  • A revisão, quando existe, é no provedor; o status fica em PENDING_REVIEW até a decisão. Decidir por aqui responde 409 review_in_kyc_provider.
  • FAILED traz um destes errorReason: kyc_rejected, kyc_expired, kyc_cancelled (cancelada no provedor), kyc_misconfigured, kyc_unavailable, kyc_not_configured, document_claimed_elsewhere (outro credenciamento do mesmo documento seguiu antes), account_opening_timeout (identidade aprovada, conta não chegou em 7 dias) ou cancelled (seu POST .../cancel).

Portabilidade e consent não mudam: CPF que já tem conta continua no fluxo de autorização, quando ele está habilitado.

Próximos passos