Aparência
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.
Fluxo do link
- O cliente (ou o sócio, na PJ) chama
POST /access/register/identity-validation— devolve umtokene umlink. - 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 consultaGET /access/register/identity-validation/{token}(pública, semdocument/register_id) e exige um navegador de celular com câmera. - A página chama
POST /access/register/identity-validation/{token}/liveness-session— abre a sessão de Face Liveness e devolve umsession_id. - O componente
FaceLivenessDetector(Amplify UI) usa essesession_idpra guiar a pessoa pelo desafio de prova de vida, transmitindo vídeo direto pro Rekognition — não passa pelo nosso back-end. - 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}/verifycom as duas fotos + osession_id. - 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 osRegisterDocumentidentity_front/identity_back/selfie. Já devolve o resultado na mesma resposta:completed(prova de vida confirmada, com confiança suficiente) oufailed(sessão reprovada/expirada, confiança baixa, ou o provider reportou erro). GET /access/register/identity-validation(autenticado porregister_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
| Status | Significado |
|---|---|
pending | Sessão ainda não criada (não aparece na prática — vira link_generated na hora da criação) |
link_generated | Link gerado, aguardando a pessoa concluir a prova de vida e enviar a foto do documento |
in_progress | Reservado para um provedor assíncrono (não usado pelo fluxo atual) |
completed | Prova de vida confirmada, com confiança suficiente — validação concluída (estado definitivo) |
failed | Sessão de liveness reprovada/expirada, confiança baixa, ou o provedor reportou erro — pode tentar de novo no mesmo link |
expired | Link 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).