Skip to content

Abertura de Conta — Validação de Identidade ​

Etapa de verificação de identidade (documento + prova de vida), exigida antes de uma solicitação ficar pronta para análise (READY_FOR_ANALYSIS). Para o contrato completo dos endpoints, ver a Referência de Endpoints.

Prova de vida via Amazon Rekognition Face Liveness

IDENTITY_VALIDATION_PROVIDER=aws (padrão) usa o Amazon Rekognition Face Liveness — o navegador transmite vídeo ao vivo direto pra AWS (via o componente FaceLivenessDetector da Amplify UI), que confirma que há uma pessoa real diante da câmera (não uma foto, vídeo gravado ou máscara). A AWS não compara a selfie contra a foto do documento — só atesta a prova de vida. As fotos do documento (frente e verso) são só armazenadas (upload simples, sem checagem da AWS). IDENTITY_VALIDATION_PROVIDER=local desativa a chamada à AWS (sempre aprova) — útil só para desenvolvimento/teste sem custo.

Documento oficial = documento verificado por prova de vida

As fotos de frente/verso enviadas aqui, quando a validação pertence a quem responde pelos documentos oficiais do register (titular na PF, sócio legal_representative na PJ), substituem os RegisterDocument do tipo identity_front/identity_back — e a ReferenceImage do Rekognition vira o selfie. Isso é intencional: antes, esses 3 documentos eram enviados separadamente pelo computador (upload comum, sem câmera, sem prova de vida), desconectados da pessoa que de fato validou o rosto no celular. Agora só existe um envio — pelo celular, junto com a prova de vida — e ele é a própria evidência oficial. Ver Referência de Endpoints.

Só funciona no celular

A tela pública de validação exige acesso à câmera do dispositivo — por isso só funciona em navegador de celular. Acessar pelo computador mostra uma mensagem pedindo para abrir o link no celular.

Infraestrutura AWS necessária (fora do código)

Além da chave IAM (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, já usada por S3/SMS) ter rekognition:CreateFaceLivenessSession e rekognition:GetFaceLivenessSessionResults liberadas, o front-end (fastgivr-portal) precisa de um Cognito Identity Pool com identidade não-autenticada habilitada, cujo papel IAM tenha rekognition-streaming:StartFaceLivenessSession liberado — é assim que o componente da Amplify UI recebe credenciais temporárias da AWS pra transmitir o vídeo direto do navegador, sem passar pelo nosso back-end. Nada disso é provisionado pelo código — é uma configuração manual na conta AWS.

GET /access/clock — hora do servidor ​

Endpoint auxiliar, sem relação direta com a Abertura de Conta: devolve { "now": <milissegundos> }. O front-end usa isso pra calcular o systemClockOffset do Face Liveness — se o relógio do celular do usuário estiver adiantado/atrasado, a assinatura das requisições de streaming pro Rekognition é rejeitada. Sem autenticação, sem parâmetros.

Por que cada sócio tem sua própria validação (Pessoa Jurídica) ​

Diferente das demais etapas (dados da empresa, endereço, documentos — que são da empresa como um todo), a validação de identidade é individual por pessoa física envolvida:

  • Pessoa Física: uma única validação, do titular da solicitação.
  • Pessoa Jurídica: uma validação por sócio cadastrado (POST /access/register/partners) — não existe uma validação "da empresa". Uma solicitação PJ só fica pronta para análise quando todos os sócios tiverem concluído a sua.

Por isso as fotos do documento (frente e verso) são capturadas na própria tela pública da validação, e não numa etapa de Documentos separada. Só a validação de quem responde pelos documentos oficiais (o titular na PF, o sócio legal_representative na PJ) grava os RegisterDocument identity_front/identity_back/selfie do register — um sócio comum na PJ também fotografa o próprio documento aqui, mas só como evidência da sua validação individual, sem virar documento oficial da empresa.

  1. O cliente (ou o sócio, na PJ) chama POST /access/register/identity-validation — devolve um token e um link.
  2. O link é enviado a quem vai fazer a validação (hoje, um link "solto" — a forma de entrega, e-mail/SMS/tela do portal, é decisão do front-end). A página que o link abre consulta GET /access/register/identity-validation/{token} (pública, sem document/register_id) e exige um navegador de celular com câmera.
  3. A página chama POST /access/register/identity-validation/{token}/liveness-session — abre a sessão de Face Liveness e devolve um session_id.
  4. O componente FaceLivenessDetector (Amplify UI) usa esse session_id pra guiar a pessoa pelo desafio de prova de vida, transmitindo vídeo direto pro Rekognition — não passa pelo nosso back-end.
  5. Concluído o desafio, a pessoa fotografa a frente e o verso do documento e a página envia POST /access/register/identity-validation/{token}/verify com as duas fotos + o session_id.
  6. O back-end consulta o resultado da sessão de liveness na AWS, guarda as fotos do documento e a ReferenceImage (o frame que a própria AWS escolheu como prova, não a foto que o usuário tirou), e — se a validação pertence a quem responde pelos documentos oficiais do register — também atualiza os RegisterDocument identity_front/identity_back/selfie. Já devolve o resultado na mesma resposta: completed (prova de vida confirmada, com confiança suficiente) ou failed (sessão reprovada/expirada, confiança baixa, ou o provider reportou erro).
  7. GET /access/register/identity-validation (autenticado por register_id+document) pode ser consultado a qualquer momento pelo wizard de cadastro para saber o status atual.

Existe também POST /access/register/identity-validation/callback (idempotente, identificado só pelo token) — pensado para um provedor assíncrono baseado em webhook. Não é usado pelo fluxo com Rekognition (que é resolvido direto em verify, depois que o front-end já concluiu a sessão), mas continua disponível para um provedor futuro que funcione nesse modelo. Exige o cabeçalho X-Callback-Secret com o valor de IDENTITY_VALIDATION_CALLBACK_SECRET; com a variável vazia (padrão), o callback fica desligado (403).

Status possíveis ​

StatusSignificado
pendingSessão ainda não criada (não aparece na prática — vira link_generated na hora da criação)
link_generatedLink gerado, aguardando a pessoa concluir a prova de vida e enviar a foto do documento
in_progressReservado para um provedor assíncrono (não usado pelo fluxo atual)
completedProva de vida confirmada, com confiança suficiente — validação concluída (estado definitivo)
failedSessão de liveness reprovada/expirada, confiança baixa, ou o provedor reportou erro — pode tentar de novo no mesmo link
expiredLink expirou sem conclusão (24h)

Gerar uma nova sessão para quem já tem uma em link_generated/in_progress reaproveita a existente em vez de criar outra — evita múltiplos links ativos para a mesma pessoa. Uma sessão failed/expired, ao ser gerada de novo, cria uma nova tentativa (com um novo token/link) — usado quando o link inteiro expira, não para o caso comum de "reprovou, tenta de novo" (ver abaixo).

Idempotência e nova tentativa após falha ​

callback não reprocessa uma validação que já está num estado terminal (completed/failed) — a resposta continua 200, mas o status/resultado gravado não muda (é o comportamento esperado de um webhook, que pode reenviar a mesma notificação).

verify é diferente: só completed é definitivo. Um failed pode ser reprocessado no mesmo token/link — a pessoa gera uma nova sessão de liveness (POST .../liveness-session) e chama verify de novo, sem precisar de um link novo. Isso é intencional: a maioria das reprovações é só uma checagem que não bateu o limite de confiança (iluminação ruim, movimento, etc.), não motivo pra invalidar o link inteiro.

Impacto no status da solicitação ​

Ver Status da Solicitação para a regra completa — em resumo, a validação de identidade concluída (do titular na PF, de todos os sócios na PJ) é, junto com dados, endereço, telefone e documentos, um dos requisitos para account_status alcançar PENDING (aguardando análise do backoffice).