OCR por Face/Selfie (Non-Doc)

A API OCR por Face (Non-Doc) é 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 fluído e eficiente.

Request

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

Parâmetros da Solicitação Arquivos

Como parâmetros esse endpoint espera o CPF e selfie do proponente.

Parâmetro	Tipo	Obrigatório	Descrição	Forma de Envio
cpf	String	Sim	Número do CPF (11 dígitos)	Parâmetro de URL
selfie	File	Sim	Arquivo de imagem da selfie (JPEG/JPG)	Arquivo no Body
document_types	String[]	Não	Filtro por tipos de documentos ("federal-id", "passport", "driver_license")	Parâmetro de URL

TIP

O document_types, por padrão filtra somente RGs e CNHs. E pode ser passado da seguinte forma (ex.: RG, CNH e Passaporte): /ocr-by-face/v1/tax-id/266.136.040-97?document_types[]=drivers-license&document_types[]=federal-id&document_types[]=passport.

Response

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

Exemplos JSON

Veja alguns exemplos em JSON da resposta.

TIP

O CPF "266.136.040-97" é inválido e pode ser utilizados para o teste. O mesmo está registrado com a face do Mr. Bean, e pode ser recuperado utilizando uma selfie de boa resolução dele. 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": "2025-06-21",
      "fathersName": "Joe Doe",
      "issuedAt": "2010-10-01",
      "mothersName": "Jane Doe",
      "name": "John Doe",
      "taxId": "11122233345"
    },
    "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álida (CPF ou imagem inválida)

Status Code: 422

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

Códigos de Erro

Código de Status	Significado
200	Requisição bem-sucedida
404	Identidade não encontrada para o CPF
422	Requisição inviável - Input inválido
500	Erro Interno do Servidor

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
• Cacheiar respostas bem-sucedidas quando apropriado
• Tratar limitação de taxa adequadamente
• Todas as solicitações devem ser feitas via HTTPS

Suporte

Para suporte ou dúvidas, por favor, contate suporte@nxcd.com.br