Full OCR + Datavalid

Este endpoint faz duas coisas em uma chamada:

Full OCR — classifica o documento enviado e extrai os campos dele, como o Full OCR e com as diferenças descritas abaixo, incluindo o cruzamento com a Receita Federal.
Datavalid — envia os dados extraídos ao serviço Datavalid da SERPRO e pergunta, campo a campo, se eles conferem com o registro oficial do governo.

A diferença para o Full OCR puro é a segunda etapa. O Full OCR responde "o que está escrito neste documento, e isso bate com a Receita Federal". Aqui você também recebe "e isso bate com o Datavalid" — nome, filiação, data de nascimento, situação da CNH, número do RG, e a biometria facial.

Este endpoint não faz liveness (use o Liveness) e não compara a face do documento com uma selfie que você envie. Se o seu caso é confrontar uma selfie com a biometria oficial, use o Face Match + Datavalid.

Request

POST /full-ocr-and-datavalid/v3

Headers

http

Authorization: ApiKey <sua-chave-de-api>

Este endpoint também aceita o token JWT, no formato Authorization: Bearer <accessToken>. Veja Token JWT.

Chaves da SERPRO

A consulta ao Datavalid pode ser feita com o nosso acesso à SERPRO ou com as suas próprias credenciais. Quem habilita o segundo modo é o escopo da sua chave de API:

Escopo da sua chave	Headers de credencial
`nextid.bureaus.fullOcrAndDatavalid`	Opcionais
`nextid.bureaus.fullOcrAndDatavalid.customerKeys`	Obrigatórios

Envie as credenciais em dois headers:

http

x-customer-key: <sua-chave-serpro>
x-customer-secret: <seu-secret-serpro>

🚧 Envie o valor puro, sem prefixo

Os dois headers são lidos exatamente como você os manda. Não coloque Key nem Secret antes do valor: o prefixo passaria a fazer parte da credencial enviada à SERPRO, e a consulta falharia com 401.

‼️ Faltando um dos dois headers, a requisição nem começa

Com o escopo customerKeys, os dois headers são obrigatórios. Se qualquer um deles estiver ausente ou vazio, a requisição é recusada de imediato com 401 e a mensagem Datavalid customer keys are required — antes de qualquer leitura de arquivo. Enviar só um dos dois é o mesmo que não enviar nenhum.

🚧 Se você mandar os headers, eles são usados

Os dois headers são lidos e encaminhados à SERPRO sempre que estão presentes, com qualquer um dos dois escopos. O escopo customerKeys determina que eles sejam exigidos, não que passem a ser usados.

Ou seja: uma chave de API com o escopo comum que envie x-customer-key e x-customer-secret passa a consultar com as suas credenciais. Se a intenção era usar o acesso da Nextcode, não envie os headers.

TIP

Este é o único endpoint que aceita chaves próprias da SERPRO. O Face Match + Datavalid usa sempre o acesso da Nextcode e ignora esses dois headers.

Parâmetros

Parâmetro	Descrição	Obrigatório
federalRevenueNumber	CPF conhecido da pessoa, para orientar a busca na Receita Federal. Aceita máscara. Pode ser repetido para mais de um CPF.	Não

🚧 Sem CPF resolvido, não há consulta ao Datavalid

A consulta ao Datavalid é feita pelo CPF. Esse CPF pode vir do próprio documento, lido pelo OCR, ou do parâmetro federalRevenueNumber — mas ele precisa existir.

Quando nenhum CPF é resolvido para o documento, a etapa do Datavalid é pulada em silêncio: a resposta é 200, com toda a extração normal e "datavalid": {}. Passar o federalRevenueNumber quando você já o conhece é a forma mais segura de garantir a consulta.

🚧 federalRevenueNumber é validado pelo dígito verificador

Um CPF que não passa na validação derruba a requisição inteira com 422, antes de qualquer processamento.

Arquivos aceitos

Item	Valor
Formatos	`application/pdf`, `image/png`, `image/jpeg`
Quantidade por chamada	até 7 arquivos
Tamanho máximo (multipart)	15 MB por arquivo

Os nomes dos campos do formulário são livres — eles voltam na resposta. Enviar mais de sete arquivos é recusado com 422.

Frente e verso do mesmo documento, enviados em arquivos ou páginas diferentes, são fundidos em uma única entrada de data. Isso vale nas duas versões deste endpoint.

Além do multipart/form-data, os arquivos podem ser enviados em JSON, no campo base64, como descrito em Envio de arquivos.

Exemplo Request

Com o acesso da Nextcode:

bash

curl -i -X POST 'https://api-homolog.nxcd.app/full-ocr-and-datavalid/v3?federalRevenueNumber=123.456.789-09' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'frente=@./cnh-frente.jpg' \
  --form 'verso=@./cnh-verso.jpg'

Com as suas próprias credenciais da SERPRO:

bash

curl -i -X POST 'https://api-homolog.nxcd.app/full-ocr-and-datavalid/v3?federalRevenueNumber=123.456.789-09' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --header 'x-customer-key: SUA_CHAVE_SERPRO' \
  --header 'x-customer-secret: SEU_SECRET_SERPRO' \
  --form 'documento=@./cnh.jpg'

Response

Esta seção descreve a v3, a versão recomendada. A v2 devolve um data com outro formato — veja Versões.

O envelope é o padrão da API:

Campo	Descrição	Tipo
id	Identificador único da requisição	`String`
version	Versão da API que atendeu a chamada	`String`
data	Lista com uma entrada por documento reconhecido. Vem vazia quando nenhum foi reconhecido.	`Object[]`
metadata	Metadados da requisição	`Object`

Cada item de data traz os blocos abaixo:

Bloco	O que é
`datavalid`	O que a SERPRO respondeu sobre os dados extraídos
`extraction`	Os campos lidos do documento
`federalRevenueData`	O cruzamento com a Receita Federal
`classification`	Que documento é, de que país, quais faces
`face`	A face encontrada no documento
`metadata`	Arquivos enviados e tempo de processamento. Fica na raiz, fora de `data[]`.

data[].datavalid

O resultado da validação na SERPRO. Cada campo com nome de dado é um booleano de conferência, não o valor do dado: name: true significa "o nome lido do documento confere com o registro oficial", e não devolve o nome oficial.

Campo	Descrição	Tipo
datavalid.federalRevenueNumberAvailability	Indica se o CPF existe na base oficial	`Boolean`
datavalid.federalRevenueNumberStatus	Indica se a situação cadastral do CPF na base oficial é regular	`Boolean`
datavalid.name	Indica se o nome lido confere com o da base oficial	`Boolean`
datavalid.nameSimilarity	Similaridade entre o nome lido e o da base oficial, de 0 a 1	`Number`
datavalid.mothersName	Indica se o nome da mãe confere	`Boolean`
datavalid.mothersNameSimilarity	Similaridade do nome da mãe, de 0 a 1	`Number`
datavalid.fathersName	Indica se o nome do pai confere	`Boolean`
datavalid.fathersNameSimilarity	Similaridade do nome do pai, de 0 a 1	`Number`
datavalid.birthdate	Indica se a data de nascimento confere	`Boolean`
datavalid.gender	Indica se o gênero confere	`Boolean`
datavalid.isBrazilian	Indica se a pessoa consta como brasileira na base oficial	`Boolean`
datavalid.croppedFaceBase64	Resultado da comparação da face do documento com a biometria oficial. Não contém base64.	`Object`
datavalid.croppedFaceBase64.availability	Indica se existe biometria facial registrada para aquele CPF	`Boolean`
datavalid.croppedFaceBase64.similarity	Similaridade entre a face do documento e a biometria oficial, de 0 a 1	`Number`
datavalid.croppedFaceBase64.probability	Faixa de probabilidade: `VeryHigh`, `High`, `Low` ou `VeryLow`	`String`
datavalid.document	Conferência do documento de identidade citado	`Object`
datavalid.document.type	Indica se o documento traz o RG	`Boolean`
datavalid.document.number	Indica se o número do RG confere com o da base oficial	`Boolean`
datavalid.document.numberConfidence	Similaridade do número do RG, de 0 a 1	`Number`
datavalid.driversLicense	Conferência dos dados da CNH	`Object`
datavalid.driversLicense.status	Indica se a CNH está confirmada na base da SERPRO	`Boolean`
datavalid.driversLicense.issuedAt	Indica se a data de emissão confere	`Boolean`
datavalid.driversLicense.expireAt	Indica se a data de validade confere	`Boolean`
datavalid.driversLicense.firstIssuedAt	Indica se a data de primeira habilitação confere	`Boolean`
datavalid.driversLicense.registerNumber	Indica se o número de registro confere	`Boolean`
datavalid.driversLicense.driversLicenseCategory	Indica se a categoria confere	`Boolean`

‼️ datavalid vem como {} quando a consulta não aconteceu

O objeto vazio não é falha do documento: é ausência de consulta. Acontece sempre que nenhum CPF foi resolvido para aquele documento.

Um código que lê data[0].datavalid.name recebe um erro nesse caso. Verifique que o objeto não está vazio antes de ler qualquer campo dele.

🚧 croppedFaceBase64 não traz recorte de face nenhum

Apesar do nome, datavalid.croppedFaceBase64 é o objeto do resultado da comparação biométrica — availability, similarity e probability. Nenhum dos três é base64, e a resposta do Datavalid não devolve imagem.

O nome vem da API do Datavalid e não muda. O recorte da face do documento, esse sim em base64, está em data[].face.croppedBase64.

Os blocos document e driversLicense dependem do documento enviado

driversLicense só tem conteúdo quando o documento analisado é uma CNH; document traz a conferência do RG. Para um documento que não alimenta esses campos, eles vêm com os valores ausentes.

json

{
  "datavalid": {
    "federalRevenueNumberAvailability": true,
    "federalRevenueNumberStatus": true,
    "name": true,
    "nameSimilarity": 1,
    "gender": true,
    "birthdate": true,
    "mothersName": true,
    "mothersNameSimilarity": 0.97,
    "fathersName": false,
    "fathersNameSimilarity": 0.62,
    "isBrazilian": true,
    "croppedFaceBase64": {
      "availability": true,
      "similarity": 0.96,
      "probability": "VeryHigh"
    },
    "document": {
      "type": true,
      "number": true,
      "numberConfidence": 1
    },
    "driversLicense": {
      "status": true,
      "issuedAt": true,
      "expireAt": true,
      "firstIssuedAt": true,
      "registerNumber": true,
      "driversLicenseCategory": true
    }
  }
}

data[].extraction

Os campos lidos do documento, em um objeto plano. O conjunto de chaves depende do tipo e do modelo do documento: uma CNH traz registerNumber, driversLicenseCategory, expireAt e companhia; um RG traz documentId, issuer, origin e naturalness. Os quatro campos de pessoa — name, federalRevenueNumber, mothersName e birthdate — aparecem na maioria dos modelos.

Este é o texto como saiu do OCR, sem tratamento. Este endpoint não tem o objeto enhanced com a versão limpa que a v4 do Full OCR oferece.

json

{
  "extraction": {
    "name": "JOAO DA SILVA SANTOS",
    "federalRevenueNumber": "12345678909",
    "mothersName": "MARIA DA SILVA SANTOS",
    "birthdate": "01/02/1990",
    "fathersName": "ANTONIO SANTOS",
    "registerNumber": "01234567890",
    "driversLicenseCategory": "AB",
    "firstIssuedAt": "15/04/2010",
    "issuedAt": "10/03/2019",
    "expireAt": "10/03/2029",
    "locale": "SAO PAULO",
    "originDocumentId": "12.345.678-9",
    "originDocumentIssuer": "SSP SP"
  }
}

data[].federalRevenueData

O cruzamento com a Receita Federal, feito antes e independentemente do Datavalid. Aqui, ao contrário do bloco datavalid, os campos trazem os valores que a Receita tem registrados.

Campo	Descrição	Tipo
federalRevenueData.name	Nome registrado na Receita Federal	`String`
federalRevenueData.federalRevenueNumber	CPF localizado na Receita Federal	`String`
federalRevenueData.mothersName	Nome da mãe registrado na Receita Federal	`String`
federalRevenueData.birthdate	Data de nascimento registrada na Receita Federal	`String`
federalRevenueData.matches.name.matched	`true` quando o nome lido corresponde ao da Receita Federal	`Boolean`
federalRevenueData.matches.federalRevenueNumber.matched	`true` quando o CPF corresponde	`Boolean`
federalRevenueData.matches.mothersName.matched	`true` quando o nome da mãe corresponde	`Boolean`
federalRevenueData.matches.birthdate.matched	`true` quando a data de nascimento corresponde	`Boolean`

Receita Federal e Datavalid são duas conferências diferentes

federalRevenueData compara o documento com a base da Receita Federal. datavalid compara com o registro do Datavalid da SERPRO. São fontes distintas e podem discordar — trate as duas como sinais independentes.

json

{
  "federalRevenueData": {
    "name": "JOAO DA SILVA SANTOS",
    "federalRevenueNumber": "12345678909",
    "mothersName": "MARIA DA SILVA SANTOS",
    "birthdate": "01/02/1990",
    "matches": {
      "name": { "matched": true },
      "federalRevenueNumber": { "matched": true },
      "mothersName": { "matched": true },
      "birthdate": { "matched": true }
    }
  }
}

data[].classification

Campo	Descrição	Tipo
classification.type	Tipo do documento: `DriversLicense`, `FederalID`…	`String`
classification.subtype	Modelo dentro do tipo: `Printed`, `Digital`, `Decree2018Paper`…	`String`
classification.country	País emissor, em três letras	`String`
classification.sides	Uma entrada por face reconhecida	`Object[]`
classification.sides[].side	`OnlyFront`, `OnlyBack` ou `FrontAndBack`	`String`
classification.sides[].page	Página em que a face foi reconhecida. Começa em 0.	`Number`
classification.sides[].fieldname	Nome do campo em que o arquivo foi enviado	`String`
classification.sides[].confidence	Confiança da classificação daquela face	`Number`

json

{
  "classification": {
    "type": "DriversLicense",
    "subtype": "Printed",
    "country": "BRA",
    "sides": [
      { "side": "OnlyFront", "page": 0, "fieldname": "frente", "confidence": 0.99 },
      { "side": "OnlyBack", "page": 0, "fieldname": "verso", "confidence": 0.97 }
    ]
  }
}

data[].face

A face encontrada no documento — a mesma que é enviada ao Datavalid para a comparação biométrica.

Campo	Descrição	Tipo
face.age	Idade aparente estimada	`Number`
face.gender.value	`Male` ou `Female`	`String`
face.boundingBox	Posição da face na imagem, em proporções entre 0 e 1 (`top`, `left`, `width`, `height`)	`Object`
face.croppedBase64	Recorte da face em base64	`String`

Quando nenhuma face é encontrada no documento, este bloco não aparece e a consulta ao Datavalid é feita sem a etapa biométrica. O datavalid.croppedFaceBase64 não some da resposta: a chave continua lá e vem vazia ({}), porque availability, similarity e probability só são preenchidos quando o Datavalid devolve o bloco biométrico. Os campos de nome, filiação e data continuam sendo conferidos.

metadata

Campo	Descrição	Tipo
metadata.filesInfo	Lista com uma entrada por arquivo enviado	`Object[]`
metadata.filesInfo[].fieldname	Nome do campo usado no envio	`String`
metadata.filesInfo[].name	Nome do arquivo enviado	`String`
metadata.filesInfo[].size	Tamanho do arquivo, em bytes	`Number`
metadata.filesInfo[].pages	Número de páginas do arquivo. Para imagens, `1`.	`Number`
metadata.filesInfo[].mimetype	Tipo do arquivo enviado	`String`
metadata.filesInfo[].encoding	Codificação do arquivo no envio	`String`
metadata.filesInfo[].sha256	Hash SHA-256 do arquivo enviado	`String`
metadata.timeSpent	Tempo de processamento da requisição, em milissegundos	`Number`

Exemplo completo

Status Code: 200

json

{
  "id": "12cfec3c-b456-7890-a4d1-5173e4c1418e",
  "version": "v3",
  "data": [
    {
      "datavalid": {
        "federalRevenueNumberAvailability": true,
        "federalRevenueNumberStatus": true,
        "name": true,
        "nameSimilarity": 1,
        "gender": true,
        "birthdate": true,
        "mothersName": true,
        "mothersNameSimilarity": 0.97,
        "fathersName": false,
        "fathersNameSimilarity": 0.62,
        "isBrazilian": true,
        "croppedFaceBase64": {
          "availability": true,
          "similarity": 0.96,
          "probability": "VeryHigh"
        },
        "document": {
          "type": true,
          "number": true,
          "numberConfidence": 1
        },
        "driversLicense": {
          "status": true,
          "issuedAt": true,
          "expireAt": true,
          "firstIssuedAt": true,
          "registerNumber": true,
          "driversLicenseCategory": true
        }
      },
      "extraction": {
        "name": "JOAO DA SILVA SANTOS",
        "federalRevenueNumber": "12345678909",
        "mothersName": "MARIA DA SILVA SANTOS",
        "birthdate": "01/02/1990",
        "fathersName": "ANTONIO SANTOS",
        "registerNumber": "01234567890",
        "driversLicenseCategory": "AB",
        "firstIssuedAt": "15/04/2010",
        "issuedAt": "10/03/2019",
        "expireAt": "10/03/2029",
        "locale": "SAO PAULO",
        "originDocumentId": "12.345.678-9",
        "originDocumentIssuer": "SSP SP"
      },
      "federalRevenueData": {
        "name": "JOAO DA SILVA SANTOS",
        "federalRevenueNumber": "12345678909",
        "mothersName": "MARIA DA SILVA SANTOS",
        "birthdate": "01/02/1990",
        "matches": {
          "name": { "matched": true },
          "federalRevenueNumber": { "matched": true },
          "mothersName": { "matched": true },
          "birthdate": { "matched": true }
        }
      },
      "classification": {
        "type": "DriversLicense",
        "subtype": "Printed",
        "country": "BRA",
        "sides": [
          { "side": "OnlyFront", "page": 0, "fieldname": "frente", "confidence": 0.99 },
          { "side": "OnlyBack", "page": 0, "fieldname": "verso", "confidence": 0.97 }
        ]
      },
      "face": {
        "age": 34,
        "gender": { "value": "Male" },
        "boundingBox": {
          "top": 0.2237228155136108,
          "left": 0.2856607735157013,
          "width": 0.1555942893028259,
          "height": 0.1687679588794708
        },
        "croppedBase64": "iVBORw0KGgoAAAANSUhEUgAAAlgAAAJYCAMAAA...K5CYII="
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "frente",
        "name": "cnh-frente.jpg",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      },
      {
        "fieldname": "verso",
        "name": "cnh-verso.jpg",
        "size": 512044,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
      }
    ],
    "timeSpent": 12480
  }
}

Documento lido, sem consulta ao Datavalid

Status Code: 200

Nenhum CPF foi resolvido para o documento — nem lido dele, nem informado em federalRevenueNumber. A extração acontece normalmente; a etapa do Datavalid é pulada.

json

{
  "id": "6a1d1e8c-4a7d-4a5e-9f2c-1b0f2a9c7e11",
  "version": "v3",
  "data": [
    {
      "datavalid": {},
      "extraction": {
        "name": "JOAO DA SILVA SANTOS",
        "birthdate": "01/02/1990",
        "documentId": "12.345.678-9",
        "issuer": "SSP SP"
      },
      "classification": {
        "type": "FederalID",
        "subtype": "MainModel",
        "country": "BRA",
        "sides": [
          { "side": "OnlyFront", "page": 0, "fieldname": "documento", "confidence": 0.98 }
        ]
      },
      "face": {
        "age": 34,
        "gender": { "value": "Male" },
        "boundingBox": { "top": 0.22, "left": 0.28, "width": 0.15, "height": 0.16 },
        "croppedBase64": "iVBORw0KGgoAAAANSUhEUgAAAlgAAAJYCAMAAA...K5CYII="
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "rg-frente.jpg",
        "size": 384210,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
      }
    ],
    "timeSpent": 7320
  }
}

Headers de resposta

Header	Quando aparece
`Nextid-ReqId`	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo `id` do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ou token JWT ausente, inválido, ou sem permissão para este endpoint. Também quando o escopo é o `customerKeys` e falta um dos headers de credencial, e quando a SERPRO recusa as suas credenciais.
404 Not Found	A versão informada na URL não existe. Só `v2` e `v3` são aceitas.
406 Not Acceptable	O corpo foi enviado como JSON, mas sem o campo `base64`.
413 Payload Too Large	Um dos arquivos enviados em `multipart/form-data` passa de 15 MB.
415 Unsupported Media Type	O header `Content-Type` está ausente ou não é suportado.
422 Unprocessable Entity	`federalRevenueNumber` que não passa na validação do dígito verificador, formato de arquivo não aceito, ou mais de sete arquivos. Também é o código devolvido quando o Datavalid recusa a face por baixa qualidade da imagem.
500 Internal Server Error	Falha inesperada durante o processamento, incluindo indisponibilidade do Datavalid.

Os dois `401` da configuração das chaves

São erros diferentes, com mensagens diferentes, e é por elas que você distingue um do outro.

Headers de credencial faltando. A requisição é recusada antes de qualquer processamento:

Status Code: 401

json

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "Datavalid customer keys are required"
  }
}

Credenciais recusadas pela SERPRO. Os headers vieram, mas a SERPRO respondeu 401 para eles. Aqui o arquivo já foi processado — o erro acontece na etapa da consulta e derruba a requisição inteira:

Status Code: 401

json

{
  "id": "6a1d1e8c-4a7d-4a5e-9f2c-1b0f2a9c7e11",
  "error": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "Invalid customer datavalid credentials"
  }
}

Este é o erro mais comum ao configurar as chaves próprias

Invalid customer datavalid credentials quer dizer que a chave e o secret chegaram à SERPRO e foram recusados. As causas de longe mais frequentes são o prefixo Key /Secret colado no valor do header e a troca dos dois valores entre si. Confira também se o seu contrato com a SERPRO cobre o serviço que está sendo consultado.

Esse erro não vem com resultado parcial: você não recebe a extração do documento junto. Se precisa da extração mesmo com o Datavalid indisponível, use o Full OCR.

Exemplo de resposta quando o Datavalid recusa a face por qualidade:

Status Code: 422

json

{
  "id": "a7f0c3d2-9e51-4b8a-8f31-2d4c6b9e0a77",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "The face is of poor quality to be processed in the datavalid"
  }
}

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

A versão recomendada é a v3, chamada em /full-ocr-and-datavalid/v3.

‼️ Omitir a versão entrega a chamada para a v2

POST /full-ocr-and-datavalid, sem versão no caminho, é atendido pela v2, que tem outro formato de resposta. Informe sempre a versão na URL.

Versão	Situação	O que muda
v3	Recomendada	`classification` no formato padrão da API, com `type`, `subtype`, `country` e `sides`.
v2	Legada	`classifications` no plural, com o vocabulário antigo de tipos, e `federalRevenueData` mais detalhado. É o que responde quando a versão é omitida na URL.

Não existe v4 aqui

O Full OCR tem uma v4, com extraction e enhanced separados. Este endpoint não tem: /full-ocr-and-datavalid/v4 responde 404.

O que muda na v2

O bloco datavalid é idêntico. As diferenças estão nos outros três:

classification vira classifications, no plural, e é uma lista com uma entrada por face reconhecida. Cada entrada tem page, fieldname e um classification com confidence, type no vocabulário antigo (CNH, RG, CPF, PROOF-OF-RESIDENCE, SELFIE, IMPRESSOS, CARTAOCREDITO ou OTHERS) e face (front, back ou front-back). Não há subtype nem country.
federalRevenueData é mais detalhado. Os matches ficam em federalRevenueData.matched — no singular, diferente da v3 — e cada campo traz matched, confidence (0 a 1) e strategy (char-to-char ou by-tokens).
face traz também a confiança do gênero, em face.gender.confidence.

Status Code: 200

json

{
  "id": "12cfec3c-b456-7890-a4d1-5173e4c1418e",
  "version": "v2",
  "data": [
    {
      "datavalid": {
        "federalRevenueNumberAvailability": true,
        "federalRevenueNumberStatus": true,
        "name": true,
        "nameSimilarity": 1,
        "gender": true,
        "birthdate": true,
        "mothersName": true,
        "mothersNameSimilarity": 0.97,
        "fathersName": false,
        "fathersNameSimilarity": 0.62,
        "isBrazilian": true,
        "croppedFaceBase64": {
          "availability": true,
          "similarity": 0.96,
          "probability": "VeryHigh"
        },
        "document": { "type": true, "number": true, "numberConfidence": 1 },
        "driversLicense": {
          "status": true,
          "issuedAt": true,
          "expireAt": true,
          "firstIssuedAt": true,
          "registerNumber": true,
          "driversLicenseCategory": true
        }
      },
      "extraction": {
        "name": "JOAO DA SILVA SANTOS",
        "federalRevenueNumber": "12345678909",
        "mothersName": "MARIA DA SILVA SANTOS",
        "birthdate": "01/02/1990",
        "registerNumber": "01234567890",
        "driversLicenseCategory": "AB"
      },
      "federalRevenueData": {
        "name": "JOAO DA SILVA SANTOS",
        "federalRevenueNumber": "12345678909",
        "mothersName": "MARIA DA SILVA SANTOS",
        "birthdate": "01/02/1990",
        "matched": {
          "name": { "matched": true, "confidence": 1, "strategy": "char-to-char" },
          "federalRevenueNumber": { "matched": true, "confidence": 1, "strategy": "char-to-char" },
          "mothersName": { "matched": true, "confidence": 0.97, "strategy": "by-tokens" },
          "birthdate": { "matched": true, "confidence": 1, "strategy": "char-to-char" }
        }
      },
      "classifications": [
        {
          "page": 0,
          "fieldname": "frente",
          "classification": { "confidence": 0.99, "type": "CNH", "face": "front" }
        },
        {
          "page": 0,
          "fieldname": "verso",
          "classification": { "confidence": 0.97, "type": "CNH", "face": "back" }
        }
      ],
      "face": {
        "age": 34,
        "gender": { "value": "Male", "confidence": 99.72 },
        "boundingBox": { "top": 0.22, "left": 0.28, "width": 0.15, "height": 0.16 },
        "croppedBase64": "iVBORw0KGgoAAAANSUhEUgAAAlgAAAJYCAMAAA...K5CYII="
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "frente",
        "name": "cnh-frente.jpg",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      }
    ],
    "timeSpent": 11940
  }
}

‼️ Trocar de versão quebra quem lê a resposta

O resultado da conferência do nome contra a Receita Federal está em data[].federalRevenueData.matched.name.matched na v2 e em data[].federalRevenueData.matches.name.matched na v3. E a classificação sai de data[].classifications[] para data[].classification.

O bloco datavalid é o único que atravessa as duas versões sem mudança.

Classificador

Full OCR + Datavalid ​

Request ​

Headers ​

Chaves da SERPRO ​

Parâmetros ​

Arquivos aceitos ​

Exemplo Request ​

Response ​

data[].datavalid ​

data[].extraction ​

data[].federalRevenueData ​

data[].classification ​

data[].face ​

metadata ​

Exemplo completo ​

Documento lido, sem consulta ao Datavalid ​

Headers de resposta ​

Erros ​

Os dois 401 da configuração das chaves ​

Versões ​

O que muda na v2 ​

Full OCR + Datavalid

Request

Headers

Chaves da SERPRO

Parâmetros

Arquivos aceitos

Exemplo Request

Response

data[].datavalid

data[].extraction

data[].federalRevenueData

data[].classification

data[].face

metadata

Exemplo completo

Documento lido, sem consulta ao Datavalid

Headers de resposta

Erros

Os dois `401` da configuração das chaves

Versões

O que muda na v2