Biometria Própria (BYO)

Por padrão, a verificação de identidade do onboarding usa a biometria CorpX — nós geramos o link de captura facial e cuidamos de toda a jornada. Se você já coleta biometria facial dos seus clientes com uma plataforma parceira, pode usar o fluxo alternativo BYO (Bring Your Own biometrics): você envia a evidência exportada pela sua plataforma e nós validamos a autenticidade diretamente no parceiro.

Habilitação obrigatória

O fluxo BYO é desabilitado por padrão. Ele precisa ser habilitado no seu tenant, provedor a provedor, pelo nosso time — entre em contato com o suporte informando qual plataforma você usa. Sem a habilitação, o objeto biometry é rejeitado com 422.

Plataformas suportadas

Provedor	Valor de `provider`
Unico	`unico`
SERPRO	`serpro`
IDWALL	`idwall`
SUMSUB	`sumsub`
ClearSale	`clearsale`
CAF	`caf`
Valid	`valid`

Cada plataforma tem seu próprio formato de exportação. Você envia o arquivo exportado + um JSON de metadados (tipicamente contendo a hash ou o ID que nos permite consultar a validade daquela verificação diretamente no parceiro).

Diferenças em relação ao fluxo padrão

	Biometria CorpX (padrão)	Biometria própria (BYO)
Captura facial	Link gerado por nós	Já feita na sua plataforma
Validação	Automática na jornada	Consultamos a validade no parceiro
Termo de aceite	Embutido na jornada	Link de aceite hospedado por nós, por pessoa
Aprovação PF	Automática	Análise prévia obrigatória
Aprovação PJ	Análise prévia	Análise prévia

Fluxo

Passo 1: Enviar a evidência

Primeiro, registre a evidência e receba uma URL de upload:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/biometry-evidence" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "clearsale",
    "fileName": "export-cliente-12345.zip",
    "contentType": "application/zip"
  }'

{
  "evidenceId": "evd_5f4e3d2c1b0a",
  "uploadUrl": "https://kyc-archive.s3.sa-east-1.amazonaws.com/staging/...",
  "uploadExpiresAt": "2026-07-07T19:00:00Z",
  "scanStatus": "PENDING",
  "info": "O arquivo enviado passa por verificação de tipo, antivírus e sanitização antes de ser arquivado (poucos segundos). Arquivos infectados ou corrompidos são recusados e não ficam disponíveis."
}

Depois, suba o arquivo exportado pela sua plataforma via PUT na uploadUrl (URL presignada, válida por 1 hora):

curl -X PUT "{uploadUrl}" \
  -H "Content-Type: application/zip" \
  --data-binary @export-cliente-12345.zip

O PUT responde 200 assim que o arquivo é recebido, mas o arquivamento não é imediato: todo upload passa por verificação do tipo real (magic bytes, não a extensão), antivírus e sanitização. PDFs são rasterizados e imagens re-encodadas; arquivos infectados, corrompidos ou com tipo diferente do esperado são recusados e não ficam disponíveis para a análise.

Passo 2: Criar a accreditation com o objeto `biometry`

Use os mesmos endpoints de PF e PJ, incluindo o objeto biometry na pessoa (no PF, dentro de person; no PJ, dentro de cada item de partners[]):

{
  "person": {
    "name": "Maria da Silva",
    "cpf": "12345678901",
    "birthDate": "1990-05-20",
    "email": "maria@email.com",
    "phone": "+5511999998888",
    "biometry": {
      "provider": "clearsale",
      "evidenceId": "evd_5f4e3d2c1b0a",
      "metadata": {
        "transactionHash": "8f7a6b5c4d3e2f1a...",
        "sessionId": "cs-session-998877"
      }
    }
  },
  "address": { "...": "..." }
}

Campo	Descrição
`biometry.provider`	Plataforma que coletou a biometria (tabela acima). Precisa estar habilitada no seu tenant.
`biometry.evidenceId`	ID retornado no Passo 1.
`biometry.metadata`	JSON livre com os dados que permitem validar a evidência no parceiro (hash, ID de sessão/transação etc.). O formato exato depende do provedor — nosso suporte informa os campos exigidos na habilitação.

Modo único por accreditation

Uma mesma accreditation usa um único modo de biometria: ou todas as pessoas com biometria CorpX (padrão), ou todas com biometria própria. No PJ com BYO, envie o objeto biometry para todos os sócios.

Passo 3: Termo de aceite

Como a captura não aconteceu na nossa jornada, cada pessoa física precisa confirmar os termos de abertura de conta em uma página hospedada por nós — é o que garante o registro formal do consentimento (data/hora, IP e dispositivo de quem aceitou).

Após a validação da evidência, você recebe o webhook accreditation.acceptance.link.created com um link de aceite por pessoa. O mesmo URL aparece em persons[].acceptanceLink no GET / resposta do POST (quando o token já foi emitido).
Entregue o link ao usuário final. A página exibe a sua marca (logomarca e cores, configuradas junto ao nosso suporte) e os termos de abertura.
O aceite expira em 7 dias; use o endpoint de retry para regenerar.

Embutir o aceite em iframe

Você pode embutir a página de aceite dentro do seu próprio site em um <iframe>. Por padrão isso é bloqueado — nós enviamos Content-Security-Policy: frame-ancestors 'none' na resposta HTML. Para liberar, informe ao suporte os origins HTTPS do seu site (ex.: https://app.suaempresa.com); habilitamos no allowlist do seu tenant e a CSP passa a incluir frame-ancestors https://app.suaempresa.com ....

Regras do allowlist:

Apenas https:// (http:// não é aceito, mesmo em dev).
Formato aceito: https://host, https://host:port ou https://*.host (wildcard só no primeiro label).
Até 10 origins por tenant.

Exemplo de embed depois de habilitado:

<iframe
  src="https://tenant.api.corpx.com/v1/accreditations/accept/tok_..."
  style="width: 100%; height: 720px; border: 0;"
  title="Aceite de abertura de conta"
></iframe>

{
  "type": "accreditation.acceptance.link.created",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "cpf": "12345678901",
    "acceptanceLink": "https://tenant.api.corpx.com/v1/accreditations/accept/tok_...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

Passo 4: Análise prévia e abertura

Com evidências validadas e aceites registrados de todas as pessoas, a accreditation entra em PENDING_REVIEW — no fluxo BYO a análise prévia é obrigatória inclusive para PF. Depois da aprovação, o processo segue idêntico ao fluxo padrão: INTEGRATING → ACTIVE, com os mesmos webhooks.

Motivos comuns de falha

Recusado na hora, na resposta HTTP do POST:

Código	HTTP	Significado	O que fazer
`provider_not_enabled`	422	Provedor não habilitado no seu tenant.	Solicite a habilitação ao suporte.
`unsupported_provider`	422	`provider` fora da lista aceita.	Use um dos valores da tabela de plataformas.
`evidence_not_found`	422	O `biometry.evidenceId` não existe ou não é do seu tenant.	Faça o Passo 1 antes de criar a accreditation.
`mixed_biometry_mode`	422	PJ com parte dos sócios em BYO e parte no fluxo padrão.	Envie `biometry` para todos os sócios, ou para nenhum.

Encerrando a accreditation depois, no webhook accreditation.failed (errorReason):

`errorReason`	Significado	O que fazer
`evidence_invalid`	O parceiro não confirmou a validade da evidência.	Verifique a hash/ID nos metadados e reenvie.
`acceptance_timeout`	O usuário não confirmou o aceite dentro do prazo.	Faça retry para regenerar o link.
`castle_deny`	A análise de dispositivo barrou o aceite.	Entre em contato com o suporte.
`review_rejected`	Rejeitada na análise prévia.	Entre em contato com o suporte para detalhes.

Plataformas suportadas​

Diferenças em relação ao fluxo padrão​

Fluxo​

Passo 1: Enviar a evidência​

Passo 2: Criar a accreditation com o objeto biometry​

Passo 3: Termo de aceite​

Embutir o aceite em iframe​

Passo 4: Análise prévia e abertura​

Motivos comuns de falha​