Sobre OCR Service API

Use esta página para integrar services de OCR pelo POST /api/service-api. Ela mostra qual service usar, como montar o payload, como deve ser o retorno e o que conferir antes de abrir chamado ou mexer na implementação.

Requisito básico: o token precisa ser do produto correto e o produto precisa ter o service ativo com API habilitada. Se a configuração do produto estiver incompleta, a chamada pode autenticar e ainda assim retornar falta de acesso.

Documentos de identificação

Use SERVICE_OCR quando o documento for RG, CNH, OAB, RNE ou PASSAPORTE e o payload tiver documentType.

Cartão CNPJ

Use SERVICE_OCR_CNPJ_CARD para extrair CNPJ e texto OCR do cartão CNPJ.

Comprovante de endereço

Use SERVICE_OCR_PROOF_OF_ADDRESS para contas, faturas e comprovantes aceitos.

Documento de emancipação

Use SERVICE_OCR_EMANCIPATION para documentos variáveis, sem layout fixo.

Teste mais rápido

Se você só precisa validar a chamada em HML, comece pelos exemplos prontos:

CNH

Curl pronto com SERVICE_OCR, documentType: CNH e image1.

RG frente e verso

Curl pronto com SERVICE_OCR, documentType: RG, image1 e image2.

Cartão CNPJ

Curl pronto para SERVICE_OCR_CNPJ_CARD com imagem do cartão CNPJ.

Comprovante de endereço

Curl pronto para SERVICE_OCR_PROOF_OF_ADDRESS com comprovante em base64.

Para teste manual no Postman, use a seção Copiar e testar. Ela monta o JSON completo no clipboard.

Jornada visual do OCR

1. Escolha o documento

Defina se o teste é CNH, RG, cartão CNPJ, comprovante de endereço ou documento de emancipação antes de montar o payload.

2. Use imagem real

Envie imagem nítida, sem corte e em base64 puro. OCR ruim quase sempre começa com imagem ruim ou documento errado.

3. Leia o result

O retorno útil fica em result. Use status, onboardingStatus e externalId para rastrear o processamento.

Blocos de decisão

Tenho RG ou CNH

Use SERVICE_OCR com documentType. Para RG, envie frente e verso quando o documento exigir os dois lados.

Tenho cartão CNPJ

Use SERVICE_OCR_CNPJ_CARD. O mínimo esperado é CNPJ válido, docType coerente e genericOcr preenchido.

Tenho comprovante

Use SERVICE_OCR_PROOF_OF_ADDRESS. O documento precisa ter endereço visível e texto suficiente para leitura.

Tenho documento variável

Use SERVICE_OCR_EMANCIPATION. Não trate CPF, RG ou código como obrigatórios, porque o layout pode variar.

Caminho recomendado

Se você precisa testar agora, siga esta ordem:

Confirme o service no produto do cliente.
Gere o token do mesmo produto.
Converta uma imagem real para base64 puro.
Envie o payload do OCR correto.
Valide status, onboardingStatus, externalId e os campos dentro de result.

Esse caminho evita misturar problema de permissão, imagem ruim e payload errado.

O que esta página resolve

Público	Como usar
Desenvolvimento	Copiar payload, entender campos obrigatórios e validar o retorno esperado.
Produto	Conferir se o service certo está configurado para o documento certo.
Suporte	Separar problema de configuração, imagem ruim, payload errado e falha técnica.
CS/Operação	Explicar para o cliente o que enviar e o que esperar da resposta.

O objetivo é evitar tentativa e erro. Antes de abrir chamado, a pessoa deve conseguir responder: qual service foi chamado, qual imagem foi enviada, qual produto autorizou a chamada e qual externalId voltou.

Escolha rápida

Preciso ler	Service	Enviar	Retorno principal
CNH	`SERVICE_OCR`	`documentType: CNH` + `image1`	CPF, nome, nascimento, dados da CNH
RG	`SERVICE_OCR`	`documentType: RG` + `image1` + `image2`	CPF, nome, filiação, nascimento, dados do RG
Cartão CNPJ	`SERVICE_OCR_CNPJ_CARD`	`image1`	CNPJ, tipo do documento, texto OCR
Documento de emancipação	`SERVICE_OCR_EMANCIPATION`	`image1`	Texto OCR, campos extraídos e análise estruturada
Comprovante de endereço	`SERVICE_OCR_PROOF_OF_ADDRESS`	`image1`	Nome, endereço, tipo do documento, datas e valores

O campo image1 deve receber base64 puro da imagem. Não envie prefixo como data:image/jpeg;base64,.

Qual imagem usar

Service	Imagem certa	Não usar
`SERVICE_OCR` com CNH	Foto ou imagem nítida da CNH inteira	Selfie, print cortado, documento de outro tipo
`SERVICE_OCR` com RG	Frente em `image1` e verso em `image2`	Só frente quando o verso for obrigatório
`SERVICE_OCR_CNPJ_CARD`	Cartão CNPJ completo e legível	Contrato social, nota fiscal ou comprovante
`SERVICE_OCR_PROOF_OF_ADDRESS`	Conta, fatura ou comprovante aceito com endereço visível	Documento pessoal ou selfie
`SERVICE_OCR_EMANCIPATION`	Documento de cartório, declaração, escritura ou certidão legível	Documento sem relação com emancipação

Critério de sucesso por service

Service	Sucesso mínimo esperado	Quando recusar
`SERVICE_OCR` com CNH	Documento lido e campos principais da CNH retornados.	Imagem ausente, documento não lido ou tipo documental inconsistente.
`SERVICE_OCR` com RG	Frente e verso enviados, documento lido e dados principais retornados.	Verso ausente, imagem ilegível ou dados centrais não extraídos.
`SERVICE_OCR_CNPJ_CARD`	CNPJ válido extraído e `docType` coerente com cartão CNPJ.	CNPJ não encontrado ou CNPJ inválido.
`SERVICE_OCR_EMANCIPATION`	OCR retornou texto e a API retornou os campos encontrados, sem exigir layout fixo.	OCR vazio ou imagem que não permite leitura.
`SERVICE_OCR_PROOF_OF_ADDRESS`	OCR retornou texto útil e dados possíveis do comprovante.	Imagem não lida ou documento fora do esperado para comprovante.

Nem todo service tem os mesmos campos obrigatórios. Em documentos variáveis, como emancipação e comprovante de endereço, o retorno deve trazer o que foi extraído sem inventar dado.

Fluxo completo

Gere o token em /api/token-generate.
Confirme se o produto tem o service ativo e habilitado para API.
Escolha o service correto na tabela acima.
Converta a imagem para base64 puro.
Envie o payload para POST /api/service-api.
Valide status.code, onboardingStatus, externalId e os campos dentro de result.

Gerar base64 no PowerShell

Para copiar apenas o base64 da imagem:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\documento.jpg")) | Set-Clipboard

O valor copiado deve ser base64 puro. Não envie prefixo como data:image/jpeg;base64,.

Copiar e testar

Use estes blocos quando quiser montar o JSON completo no clipboard e colar direto no body raw JSON do Postman. Troque apenas o caminho do arquivo e mantenha o service conforme o OCR que será testado.

CNH

$b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\cnh.jpg"))
@{
  service = "SERVICE_OCR"
  documentType = "CNH"
  image1 = $b64
} | ConvertTo-Json -Compress | Set-Clipboard

RG com frente e verso

$front = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\rg-frente.jpg"))
$back = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\rg-verso.jpg"))
@{
  service = "SERVICE_OCR"
  documentType = "RG"
  image1 = $front
  image2 = $back
} | ConvertTo-Json -Compress | Set-Clipboard

Cartão CNPJ

$b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\cartao-cnpj.jpg"))
@{
  service = "SERVICE_OCR_CNPJ_CARD"
  image1 = $b64
} | ConvertTo-Json -Compress | Set-Clipboard

Comprovante de endereço

$b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\comprovante-endereco.jpg"))
@{
  service = "SERVICE_OCR_PROOF_OF_ADDRESS"
  image1 = $b64
} | ConvertTo-Json -Compress | Set-Clipboard

Depois de executar o comando, cole o conteúdo do clipboard no Postman em Body > raw > JSON.

Testar no Postman

Gere token em POST /api/token-generate.
Copie o access_token.
Abra POST https://backoffice-hml.idcerberus.com/api/service-api.
Adicione o header Authorization: Bearer {access_token}.
Adicione Content-Type: application/json.
Cole o JSON gerado pelo PowerShell no body raw.
Execute e confira status, onboardingStatus, externalId e result.

Exemplo de headers:

Authorization: Bearer {access_token}
Content-Type: application/json

Conferência antes de chamar suporte

Ponto	O que conferir
Produto	O token usado pertence ao produto em que o service está ativo.
Payload	O campo `service` usa o alias liberado no produto.
Imagem	A imagem abre normalmente e o texto está legível para uma pessoa.
Base64	O valor enviado não tem prefixo `data:image/...;base64,`.
Retorno	Guarde `externalId`, `status.message` e o horário do teste.

Se esses pontos estiverem corretos e o OCR ainda falhar, o chamado já chega com informação suficiente para investigar sem repetir teste básico.

Diagnóstico rápido

Sintoma	Conferir primeiro	Próxima ação
Não tem acesso ao service	Token, produto, service ativo e API habilitada.	Corrigir a configuração do produto antes de mexer na imagem.
Deu imagem ausente	`image1`, `image2`, `image1Url`, `image2Url` ou `key`, conforme o OCR.	Gerar novamente o JSON e confirmar se o campo esperado chegou no body.
Retornou `{}`	Se a imagem é do tipo certo e está legível.	Testar com imagem mais nítida e validar se o service escolhido bate com o documento.
Veio `ERROR`	`externalId`, horário, ambiente e mensagem técnica segura.	Repetir uma vez; se persistir, acionar suporte técnico com o `externalId`.
Veio sem campo esperado	Se o campo existe visualmente no documento e se o OCR desse service retorna esse campo.	Comparar com o padrão de retorno abaixo e não tratar campo ausente como contrato obrigatório.

Qualidade da imagem

Para reduzir recusa por leitura ruim:

Item	Recomendação
Enquadramento	Documento inteiro visível, sem cortar bordas.
Nitidez	Texto legível ao abrir a imagem manualmente.
Iluminação	Evitar reflexo, sombra forte e blur.
Orientação	Preferir documento reto, sem rotação exagerada.
Arquivo	Usar imagem real em JPG/PNG convertida para base64.

Foto de documento não serve para service de face. Selfie não serve para OCR de documento.

Configuração do produto

Antes de testar em HML ou PROD, confira:

Configuração	O que verificar
Token	`client` e `secret` pertencem ao produto que será testado.
Service	O service está cadastrado e ativo no produto.
API	O service está liberado para chamada via API.
Alias	O valor enviado em `service` é o alias de chamada do produto.
Campos	O service tem os campos de entrada e saída esperados.

Se o retorno for "Don't have access to the service", o primeiro ponto a olhar e configuração do produto, não a imagem.

Padrão de retorno

O retorno público deve ficar limpo, com os dados úteis dentro de result. Exemplo de sucesso:

{
  "result": {
    "cpf": "00000000000",
    "docType": "CNH",
    "name": "NOME EXTRAÍDO"
  },
  "status": {
    "code": 200,
    "message": "OCR realizado com sucesso"
  },
  "onboardingStatus": "APPROVED",
  "externalId": "..."
}

O cliente não deve depender de campos internos como:

fieldsOutput
required
enabled
valid
callService
nextStep
fields
visible

A regra prática e simples: o integrador olha para result. Se o campo não está em result, ele não deve ser usado como contrato público da API.

Não use assim

Evite	Motivo
Enviar `data:image/jpeg;base64,...`	A API espera base64 puro.
Usar foto de RG/CNH em service de face	Face e OCR usam fluxos diferentes.
Usar selfie em OCR de documento	OCR precisa da imagem do documento.
Testar RG enviando só a frente	O verso pode conter campos importantes.
Testar cartão CNPJ no service de comprovante	Cada OCR tem parser e critério próprio.
Colocar CPF, CNPJ ou nomes reais na documentação	Exemplos públicos devem usar dados fictícios.
Assumir que campo ausente sempre é bug	O campo pode não existir no documento ou não ter sido lido.

Limites conhecidos

Ponto	Como tratar
OCR não garante leitura perfeita em imagem ruim	Valide nitidez, enquadramento e documento completo antes de acionar suporte.
Alguns campos podem não existir no documento	A API deve retornar apenas o que foi extraído com segurança.
Produto sem API habilitada parece erro de acesso	Corrija configuração do produto antes de mexer no payload.
RG pode variar por estado/modelo	Sempre enviar frente e verso quando o service exigir RG.
Emancipação não tem layout único	O sucesso depende de texto OCR, não de todos os campos opcionais.
Comprovantes variam muito	`fullAddress`, valores, datas e código de barras dependem do tipo de documento enviado.

Documentos de identificação

Cartão CNPJ

Comprovante de endereço

Documento de emancipação

​Teste mais rápido

CNH

RG frente e verso

Cartão CNPJ

Comprovante de endereço

​Jornada visual do OCR

1. Escolha o documento

2. Use imagem real

3. Leia o result

​Blocos de decisão

Tenho RG ou CNH

Tenho cartão CNPJ

Tenho comprovante

Tenho documento variável

​Caminho recomendado

​O que esta página resolve

​Escolha rápida

​Qual imagem usar

​Critério de sucesso por service

​Fluxo completo

​Gerar base64 no PowerShell

​Copiar e testar

​CNH

​RG com frente e verso

​Cartão CNPJ

​Comprovante de endereço

​Testar no Postman

​Conferência antes de chamar suporte

​Diagnóstico rápido

​Qualidade da imagem

​Configuração do produto

​Padrão de retorno

​Não use assim

​Limites conhecidos

Teste mais rápido

Jornada visual do OCR

Blocos de decisão

Caminho recomendado

O que esta página resolve

Escolha rápida

Qual imagem usar

Critério de sucesso por service

Fluxo completo

Gerar base64 no PowerShell

Copiar e testar

CNH

RG com frente e verso

Cartão CNPJ

Comprovante de endereço

Testar no Postman

Conferência antes de chamar suporte

Diagnóstico rápido

Qualidade da imagem

Configuração do produto

Padrão de retorno

Não use assim

Limites conhecidos