CNH Digital

Processo de envio de CNH Digital e respostas esperadas.

Aqui você vai encontrar toda a estrutura de requisição Request e retorno Response dos serviços relacionados ao Captcha/Document e Captcha/Document/Result, com foco nos status 200 (sucesso) e possíveis erros.

Captcha/Document

Request

POST
https://hml.certiface.com.br/facecaptcha/service/captcha/document

Headers	Descrição
Content-Type	application/json

Request example

{
    "appkey": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw",
    "qrcode": "ivBORimg=="
}

Body Params

Body	Descrição
appkey	Appkey gerada pelo método "/appkey".
qrcode	Arquivo de imagem contendo o QRCode da CNH Digital, ou PDF exportado pelo app "CNH Digital", ou binário do QRCode extraído por aplicativo ou serviço de leitura de QRCode

Responses

Status Code	Descrição
200	OK
401	Dados faltantes na requisição ou fora do padrão esperado.
500	Falha interna do servidor.

Response HTTP 200

Headers	Descrição
Content-Type	application/json

Response example

{
"appkey":"eyJh,a132a13456sac.XE-xckY",
"codigoDocumento":21615
}

Response Body

Quando o serviço captcha/document é executado, os seguintes campos são retornados:

Body	Descrição
appkey	Chave de autenticação da aplicação utilizada na requisição.
codigoDocumento	Código único gerado para o documento processado.

Captcha/Document/Result

Request

POST
https://hml.certiface.com.br:8443/facecaptcha/service/captcha/document/result

Headers	Descrição
Content-Type	application/x-www-form-urlencoded

Request example

appkey: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw"

Body Params

Body	Descrição
appkey	Appkey gerada pelo método "/appkey".

Responses

Status Code	Descrição
200	OK
401	Dados faltantes na requisição ou fora do padrão esperado.
500	Erro interno

Response HTTP 200

Headers	Descrição
Content-Type	application/json

Response Example

{
  "status":"Completo",
  "idExternoCliente":"ABCD1234",
  "analiseDocumento": {
    "idExterno":"7f8813b4-59ce-4f36-ab1a-33c8c42cafbc",
    "ticket":"8e7892e2-b182-4234-a0b5-bb7bdd8d6e21",
    "statusProcessamento":4,
    "responseClientDadosOcrDTO":{
      "responseClientCNHOcrDTO":{
        "documento":"CNH Digital",
        "formato":"QR Code",
        "extensao":"Imagem",
        "nome":"NOME E SOBRENOME",
        "docOrigem":"12345678 RG BR",
        "cpf":"12345678911",
        "dtNascimento":"01/01/2001",
        "dtNascimentoFormatada":"2001-01-01",
        "filiacao":"NOME MAE NOME PAI",
        "categoria":"E",
        "numeroRegistro":"098765432",
        "validade":"01/01/2030",
        "primeiraHabilitacao":"01/01/2019",
        "local":"CIDADE - UF",
        "renach":"BR0123456",
        "nomePai":"NOME PAI",
        "nomeMae":"NOME MAE",
        "observacao":"EAR"
      }
    },
    "biometriaDocumento":{
      "serpro":{
        "codigo":"200",
        "causa":"Validacao positiva",
        "score":"0.9876"
      }
    }
  },
  "certifaceID":{
    "aprovado":true,
    "codigo":203,
    "conhecido":true,
    "protocolo":202599995555,
    "scoreBiometrico":98.7
  },
  "dataCriacaoAppkey":"2025-10-01 09:00:00",
  "facecaptcha":{
    "causa":"CERTIFACE",
    "codID":1.2,
    "protocolo":202599997777,
    "validado":true
  },
  "fotos":{
    "facecaptcha":{
      "frontal":"/9j/4AIMG/Z"
    },
    "documento":[
      {
        "descricao":"CNH DIGITAL",
        "imagem":"iVBIMG="
      }
    ]
  }
}

Response Body

Quando o serviço captcha/document/result é executado, os seguintes campos são retornados:

Body	Descrição
status	Status da execução do serviço.
idExternoCliente	Identificador externo do cliente.
analiseDocumento	Objeto com dados e resultado da análise do documento.
certifaceID	Resultado da validação biométrica feita pela Certiface.
dataCriacaoAppkey	Data e hora de criação da Appkey.
facecaptcha	Dados do processo de validação facial via Captcha.
fotos	Imagens capturadas durante o processo.

Tabelas

Tabela do objeto "analiseDocumento"

Objeto	Tipo	Descrição
idExterno	string	Identificador único da análise do documento.
ticket	string	Código de acompanhamento do processamento.
statusProcessamento	number	Status numérico do processamento.
responseClientDadosOcrDTO	object	Resultado da leitura OCR do documento.
biometriaDocumento	object	Dados da validação biométrica do documento.

Tabela do objeto _"responseClientCNHOcrDTO"

Objeto	Tipo	Descrição
documento	string	CNH Digital
formato	string	QR Code ou Documento
extensao	string	Imagem, PDF ou Binario
nome	string	Nome completo do titular do documento.
docOrigem	string	Documento de origem (RG, CPF etc.).
cpf	string	CPF do titular.
dtNascimento	string	Data de nascimento.
dtNascimentoFormatada	string	Data de nascimento formatada (ISO).
filiacao	string	Nome dos responsáveis (pai e mãe).
categoria	string	Categoria do documento.
numeroRegistro	string	Número de registro do documento.
validade	string	Data de validade do documento.
primeiraHabilitacao	string	Data da primeira habilitação.
local	string	Local de emissão (Cidade - UF).
renach	string	Código RENACH.
nomePai	string	Nome do pai.
nomeMae	string	Nome da mãe.
observacao	string	Observações adicionais.

Tabela do objeto _"biometriaDocumento.serpro"

Objeto	Tipo	Descrição
codigo	string	Código do resultado da validação biométrica.
causa	string	Mensagem referente ao código.
score	string	Grau de similaridade facial (0 a 1).

Tabela Código Serpro

Código	Causa	Descrição da causa Serpro
200	Validação positiva	Biometria validada corretamente com o documento (faces similares).
300	Validação negativa	Biometria não validada corretamente com o documento (similaridade baixa).
400	Face não encontrada	Face não encontrada no tratamento do documento.

🚧
Homologação
Em homologação, os retornos positivo e negativo da validação Serpro
estão limitados a um conjunto específico de CPFs de teste. Qualquer outro CPF
retorna Serpro não encontrado.

Consulte a lista de CPFs de teste
Retorno positivo (validação positiva)

CPF
15929792038
25178629078
34963067005
44707559077
57742988097
Retorno negativo (validação negativa)

CPF
69680042081
77571154006
80277279011
91995827088
07034479046
Demais CPFs
Qualquer CPF fora das listas acima retorna Serpro não encontrado.

Tabela do objeto "certifaceID"

Objeto	Tipo	Descrição
aprovado	boolean	Indica se o usuário foi aprovado na análise biométrica.
codigo	number	Código interno de retorno da Certiface.
conhecido	boolean	Indica se o usuário é conhecido na base.
protocolo	number	Protocolo da execução.
scoreBiometrico	number	Percentual de similaridade facial.

Tabela do objeto "facecaptcha"

Objeto	Tipo	Descrição
causa	string	Origem da validação.
codID	number	Código identificador do processo.
protocolo	number	Protocolo da execução.
validado	boolean	Indica se a validação facial foi bem-sucedida.

Tabela do objeto "fotos"

Objeto	Tipo	Descrição
facecaptcha	object	Imagem frontal capturada para validação.
documento	array	Lista de imagens do documento analisado.

Subobjeto "fotos.documento"

Objeto	Tipo	Descrição
descricao	string	Tipo ou descrição do documento.
imagem	string	Imagem codificada em Base64.

Updated 16 days ago