OCR por Face Beta

🚧 Recurso em beta

Este endpoint está em beta. O contrato de resposta pode mudar sem troca de versão. Avise nosso time antes de colocá-lo em produção para que possamos acompanhar a sua integração.

A API OCR por Face é um serviço de verificação de identidade que permite aos clientes validar e recuperar documentos de identidade com base no CPF (Cadastro de Pessoas Físicas) e uma foto de selfie, tornando assim o processo de KYC mais fluido e eficiente.

Ele resolve o caminho inverso dos demais endpoints de documento: aqui o cliente não envia o documento. Envia o CPF e a selfie, e nós procuramos o documento correspondente. Se você já tem a imagem do documento em mãos, o endpoint certo é o Full OCR.

Request

POST /ocr-by-face/v1/tax-id/{CPF}

Parâmetros

Parâmetro	Descrição	Obrigatório	Forma de envio
CPF	CPF da pessoa, com ou sem máscara	Sim	Parâmetro de URL
document_types	Filtra os tipos de documento procurados. Sem ele, a busca cobre apenas RG e CNH.	Não	Parâmetro de query
selfie	Imagem da selfie da pessoa. O nome do campo é livre.	Sim	Arquivo no corpo

O CPF pode ser enviado com ou sem máscara (123.456.789-09 ou 12345678909), sempre com os 11 dígitos, incluindo os zeros à esquerda. Um CPF que não passa na validação do dígito verificador devolve 422 com a mensagem Invalid taxId (CPF), antes de qualquer processamento.

TIP

O document_types é uma lista repetida na query string. Pode ser passado da seguinte forma (ex.: RG, CNH e Passaporte): /ocr-by-face/v1/tax-id/12345678909?document_types[]=federal-id&document_types[]=drivers-license&document_types[]=passport.

Headers

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

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

Arquivos aceitos

Item	Valor
Formatos	image/png, image/jpeg
Quantidade por chamada	1 arquivo
Tamanho máximo (multipart)	15 MB

O nome do campo do formulário é livre. Se mais de um arquivo for enviado, a requisição é recusada com 422.

Além do multipart/form-data, a selfie pode ser enviada em JSON, no campo base64, como descrito em Envio de arquivos.

Exemplo Request

curl -i -X POST 'https://api-homolog.nxcd.app/ocr-by-face/v1/tax-id/12345678909' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'selfie=@./selfie.jpg'

Filtrando os tipos de documento procurados:

curl -i -X POST 'https://api-homolog.nxcd.app/ocr-by-face/v1/tax-id/12345678909?document_types[]=federal-id&document_types[]=passport' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'selfie=@./selfie.jpg'

Response

O envelope deste endpoint é reduzido: ele traz id e data, sem version e sem metadata.

Campo	Descrição	Tipo
id	ID da requisição	String
data	Objeto com o resultado da análise	Object
data.match	Indica se a selfie corresponde ao CPF	Boolean
data.similarity	Percentual de similaridade	Number
data.idCards	Lista com as identidades encontradas	Object[]
data.idCards[].base64	Base64 da identidade	String
data.ocr	Objeto com o texto extraído do documento	Object
data.ocr.taxId	CPF do proponente	String
data.ocr.name	Nome do proponente	String
data.ocr.birthdate	Data de nascimento do proponente	String
data.ocr.mothersName	Nome da mãe do proponente	String
data.ocr.fathersName	Nome do pai do proponente	String
data.ocr.issuedAt	Data de emissão do documento	String

🚧 idCards e ocr só existem quando a selfie bate

Quando match é false, data traz apenas match e similarity. Teste o match antes de ler data.ocr ou data.idCards.

Exemplos JSON

Veja alguns exemplos em JSON da resposta.

TIP

O CPF "12345678909" é um CPF de teste — ele passa na validação do dígito verificador, mas não corresponde a uma pessoa real. Em caso de dúvidas, entre em contato com o nosso suporte.

1. Exemplo quando um documento é encontrado a partir do CPF e selfie

Status Code: 200

{
  "id": "e83b9a9b-0547-4d52-84b4-68a156f6116a",
  "data": {
    "idCards": [
      {
        "base64": "iVBORw0KG...K5CYII="
      },
      {
        "base64": "iVBORw0K...SuQmCC"
      }
    ],
    "match": true,
    "ocr": {
      "birthdate": "1990-06-21",
      "fathersName": "Joe Doe",
      "issuedAt": "2010-10-01",
      "mothersName": "Jane Doe",
      "name": "John Doe",
      "taxId": "12345678909"
    },
    "similarity": 0.9982403814792633
  }
}

2. Exemplo quando a selfie não corresponde ao CPF

Status Code: 200

{
  "id": "943fb612-838e-46c3-92e7-4c92dc18b370",
  "data": {
    "match": false,
    "similarity": 0.5110294818878174
  }
}

3. Exemplo quando um documento não é encontrado

Status Code: 404

{
  "id": "7c86a49b-c392-4f6e-bd32-74f359d736bc",
  "error": {
    "statusCode": 404,
    "error": "Not Found",
    "message": "not found identity document for the provided person tax id and filters"
  }
}

4. Exemplo quando o payload é inválido (CPF ou imagem inválida)

Status Code: 422

{
  "id": "795ada3c-5b6f-42de-8878-c5e59f98133d",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid taxId (CPF)"
  }
}

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 a permissão nextid.ocrByFace.ocrByFace.
404 Not Found	Nenhum documento de identidade foi encontrado para o CPF informado e para os filtros aplicados.
406 Not Acceptable	O corpo foi enviado como JSON, mas sem o campo base64.
413 Payload Too Large	A selfie enviada 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	CPF que não passa na validação do dígito verificador (Invalid taxId (CPF)), formato de arquivo não aceito, ou mais de um arquivo.
500 Internal Server Error	Falha inesperada durante o processamento.

A mensagem do CPF inválido é diferente aqui

Este endpoint responde Invalid taxId (CPF). Os demais endpoints que validam CPF respondem Invalid Federal Revenue Number. Se o seu código compara a mensagem, trate as duas.

O 404 é a resposta esperada quando não existe documento para aquele CPF — não é uma falha da integração. A selfie que não corresponde ao CPF não gera erro: devolve 200 com match: false.

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

Versões

Este endpoint tem uma versão só, a v1, e ela é obrigatória no caminho: /ocr-by-face/v1/tax-id/{CPF}. Não existe a forma sem versão, e nenhuma outra versão está no ar.

Versão	Situação	O que muda
v1	Recomendada	Única versão. Envelope reduzido, com id e data apenas.

🚧 O contrato pode mudar sem troca de versão

Enquanto o endpoint estiver em beta, campos de data podem ser acrescentados, renomeados ou removidos sem que a v1 da URL mude. Leia os campos de forma defensiva e avise nosso time antes de subir para produção.

Segurança e Práticas Recomendadas

• Sempre validar o formato do CPF antes de enviar solicitações
• Garantir que as imagens de selfie estejam claras e bem iluminadas
• Implementar tratamento adequado de erros para todos os códigos de resposta
• Todas as solicitações devem ser feitas via HTTPS

Para suporte ou dúvidas, veja os canais de atendimento.