Validação de documentos

Document Validation é o serviço que analisa o Documento de identidade (e, opcionalmente, uma selfie) e determina se são autênticos e consistentes entre si. O serviço se integra como parte do ecossistema de APIs de Facephi.

A partir do documento (e, se fornecida, a selfie), o serviço executa um conjunto de validações antifraude e devolve um diagnóstico único:

• APPROVED: o documento (e, se for o caso, a correspondência com a selfie) supera as validações.

• DECLINED: é detectada uma inconsistência, manipulação ou descumprimento de qualidade/formato que impede validar o documento.

• DOUBTFUL: a análise não é conclusiva. O documento não é confirmado como autêntico nem é rejeitado, e a decisão fica a cargo do consumidor. Só aparece na modalidade automática.

Natureza assíncrona

Document Validation é um serviço assíncrono: a chamada que inicia a validação não bloqueia aguardando o resultado. Responde imediatamente com um identificador de transação (transactionId) e o consumidor obtém o resultado por meio de consultas de estado (polling).

Modalidades do serviço

Document Validation é oferecido em duas modalidades, definidas no cadastro do serviço e não escolhidas por requisição:

• Automática: o diagnóstico é emitido integralmente pelo motor antifraude de Facephi. Quando a análise não chega a uma conclusão, a transação termina com diagnostic = DOUBTFUL e seu rejectionReason correspondente.

• Híbrida: quando a análise inicial não é conclusiva, o caso passa por uma verificação adicional escalonada antes de ser resolvido. O diagnóstico final é sempre APPROVED ou DECLINED: esta modalidade não retorna DOUBTFUL. Os códigos de razão 600 a 603 aparecem apenas aqui.

Se você não sabe qual a sua integração tem, consulte o suporte.

Fluxo de integração

A inicialização (Token, operação e upload de assets) é comum a todos os serviços que trabalham por referência e está desenvolvida em Fluxo comum. A partir daí:

1. Concluir os passos prévios do Fluxo comum, incluindo a subida dos assets do documento e, opcionalmente, a selfie.

2. Iniciar a validação enviando as fileKeys obtidas tal como estão, com o operationId no cabeçalho operation-id. O serviço responde imediatamente com um transactionId.

3. Consultar o estado da transação por meio de polling até obter um estado terminal.

A cadência de sondagem recomendada está em Boas práticas, e o detalhe da resposta terminal em Resposta de resultado.

Document Validation trabalha exclusivamente por referência: não aceita o conteúdo dos assets em linha. O modelo de referência comum a toda a API está em Armazenamento.

Mudança de rotas. A validação documental agora é publicada em /document/validate. As rotas anteriores continuam sendo atendidas para não quebrar as integrações existentes, mas estão obsoletas e deixarão de ser documentadas:

O contrato não muda: mesmos cabeçalhos, mesmo corpo da requisição e mesmas respostas. Só muda a rota.

Rota anterior	Rota atual
POST /daf/validate	POST /document/validate
GET /daf/{transactionId}	GET /document/validate/{transactionId}
POST /daf/fraud-report	POST /document/validate/fraud-report