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
PDF
Não entrega

Campos do corpo

  • imagemobrigatório

    Base64 (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.

  • referenciaopcional

    Texto, até 80

    Seu identificador. Volta na resposta, no webhook e no histórico.

  • filtroopcional

    Objeto

    Devolve só os itens de detalhe.itens que batem: {"campo": valor}.

  • ordenaropcional

    Nome de um campo do item

    - na frente para a ordem decrescente.

  • limiteopcional

    Inteiro 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: enviar verso devolve 422 pedindo o documento aberto em imagem.
  • 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_reprovada custa 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.
  • resultado resume 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ítulo Alerta <código> e o motivo em Descriçã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 em detalhe.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 voltam dados.