Validação de Documento por Foto — RG, CNH, CIN, CRLV, passaporte e outros
Lê o documento aberto por imagem (RG, CIN, CNH, CPF, CRLV, CRNM e RNE, CTPS, passaporte e carteiras profissionais e militares), avalia a qualidade da foto, compara com a base oficial e devolve alertas de fraude. A imagem enviada não fica guardada.
POST/v1/documento-validacao/consultas
- Órgão
- Base oficial do documento
- Prazo máximo
- 60 s
- Não entrega
Campos do corpo
imagemobrigatórioBase64 (JPEG, PNG, WEBP ou PDF), até 5 MB
O documento aberto, com frente e verso na mesma imagem (documento de uma face só, como o passaporte ou a CNH digital, vai inteiro). JPEG, PNG ou PDF (só a primeira página é lida) em base64, até 5 MB; aceita o prefixo
data:image/...;base64,. WEBP não é aceito.referenciaopcionalTexto, até 80
Seu identificador. Volta na resposta, no webhook e no histórico.
filtroopcionalObjeto
Devolve só os itens de
detalhe.itensque batem:{"campo": valor}.ordenaropcionalNome de um campo do item
-na frente para a ordem decrescente.limiteopcionalInteiro de 1 a 1000
Quantos itens devolver.
Resultados possíveis
dadosfoto_reprovada
Decida pelo campo codigo. Consulta que o órgão não respondeu volta como sem_retorno ou em_processamento e não é cobrada.
Observações
- Uma imagem por consulta. Fotografe ou escaneie o documento aberto, com as duas faces visíveis. Não há campo
verso: enviarversodevolve422pedindo o documento aberto emimagem. - Documentos lidos: RG (modelos antigos e novos), CIN, CNH (física e digital), CPF, CRLV, CRNM e RNE, CTPS, passaporte, carteiras de conselhos profissionais e documentos militares. O tipo e a face são reconhecidos sozinhos e voltam em "Tipo de documento" e "Lado".
- A foto passa por duas conferências antes da leitura:
1. Grátis, na entrada: análise de imagem. Foto JPEG ou PNG com lado maior abaixo de 500 px ou com algum destes problemas é recusada: contraste baixo, documento cortado (parte fora da foto), documento longe (pequeno na foto), documento torto (foto inclinada), foto borrada ou desfocada, foto clara demais, foto escura demais, foto tremida, reflexo sobre o documento. A resposta é 422 (campo_invalido), com os motivos no detail; nada é consultado nem cobrado. PDF segue direto para a conferência 2.
2. Qualidade da foto: nitidez, brilho, contraste, resolução e enquadramento, com critério mais fino. Foto fora do padrão não é lida e volta foto_reprovada, cobrada a R$ 0,34 (não o preço da leitura), com resultado "Foto reprovada" e os motivos em detalhe.dados ("Motivos"). Arquivo ou resolução acima do recomendado, sozinhos, não reprovam.
- Motivos possíveis em
foto_reprovada:arquivo acima do tamanho recomendado,contraste baixo,documento fechado: veio só a frente,documento fechado: veio só o verso,documento pequeno na foto (longe ou mal enquadrado),foto borrada ou desfocada,foto escura demais,nenhum dado encontrado na imagem,resolução acima da recomendada,resolução baixa. - Foto sem nenhum documento legível (outra coisa na imagem) também volta
foto_reprovada(R$ 0,34), com o motivo "nenhum dado encontrado na imagem". - Documento fechado reprova. RG, CIN, CNH física e RNE/CRNM têm duas faces: lidos só pela frente ou só pelo verso, voltam
foto_reprovada("documento fechado: veio só a frente" ou "…só o verso"), a R$ 0,34. - Para gastar menos: no seu app, guie a captura com uma moldura na câmera, peça boa luz e evite flash sobre documento plastificado. Cada foto recusada na entrada é grátis; cada
foto_reprovadacusta R$ 0,34. Passaporte, cartão e comprovante do CPF e CNH digital têm uma face só e passam inteiros. CRLV, CTPS, carteiras profissionais e militares não são reprovados pela face. resultadoresume a leitura: "Documento lido, sem alertas da fonte" ou "Documento lido, com N alertas da fonte".- Em
detalhe.dados: status da leitura, "Qualidade da foto: dentro do padrão", dados lidos (nome, CPF, nascimento, filiação, números, validade), a comparação com a base oficial ("Nome confere (%)", "Nascimento confere") e a idade e o gênero estimados pela foto. Os campos lidos variam com o tipo de documento; campo sem rótulo próprio vem com o nome montado em português (ex.: "Número de passaporte", "Data de emissão"). - Em
detalhe.itens: um item por alerta, com o títuloAlerta <código>e o motivo emDescrição. A gravidade abaixo é a que o portal usa para a cor; a decisão de aceitar o documento é sua.
| Código | O que significa | Gravidade |
|---|---|---|
| -735 | Baixa qualidade na classificação visual dos elementos do documento | atenção |
| -901 | Data de nascimento do documento diverge do cadastro oficial | atenção |
| -902 | Idade calculada inferior a 18 anos | informativo |
| -903 | Idade calculada superior a 100 anos | informativo |
| -904 | Idade na primeira habilitação inferior a 18 anos | informativo |
| -905 | Idade na primeira habilitação superior a 100 anos | informativo |
| -906 | Primeira habilitação posterior à data de validade | informativo |
| -907 | Documento vencido | atenção |
| -908 | Validade expira em 60 dias ou menos | informativo |
| -909 | CNH com validade superior a 5 anos para condutor entre 50 e 70 anos | informativo |
| -910 | Data de nascimento posterior à data de validade | informativo |
| -911 | Data de expedição posterior à data de validade | informativo |
| -912 | Data de nascimento posterior à data de expedição | informativo |
| -913 | Primeira habilitação posterior à data de expedição | informativo |
| -914 | Primeira habilitação anterior à data de nascimento | informativo |
| -922 | CNH com validade superior a 3 anos para condutor com mais de 70 anos | informativo |
| -923 | CNH com validade superior a 10 anos para condutor com menos de 50 anos | informativo |
| -924 | Informações suspeitas ou potencialmente fraudulentas, com base no histórico de fraudes | grave |
| -925 | Imagem já enviada em processamento anterior | grave |
| -927 | Baixo risco de fraude com base em ocorrências anteriores | informativo |
| -928 | Risco moderado de fraude com base em ocorrências anteriores | atenção |
| -929 | Alto risco de fraude com base em ocorrências anteriores | grave |
| -930 | CIN com data de expedição anterior a 2022 | atenção |
| -931 | CNH no modelo anterior expedida após 2022 ou CNH V2 expedida antes de 2022 | atenção |
| -933 | Várias marcas d'água SEM VALOR no documento | grave |
- Arquivo que não pôde ser processado volta
dados_divergentes"Documento não lido", sem cobrança, com o código e o motivo emdetalhe.explicacao— por exemplo "código -915: imagem grande demais", "código -916: formato de arquivo não aceito", "código -920: PDF corrompido", "código -918: erro ao processar a imagem". - O corpo aceita até 8 MB neste produto. A imagem não é gravada.
- Com a chave de teste a conferência grátis é a mesma da produção; a de qualidade é simulada: PNG ou JPEG com o lado maior entre 500 e 800 px volta
foto_reprovada("resolução baixa"); as demais voltamdados.