Classificar documento automaticamente

Envia a imagem de um documento sem declarar o template. A OCR identifica o tipo e o lado do documento, confere se ele está na lista allowed_templates e, em seguida, aplica as mesmas validações e a mesma extração do envio com template.

Use quando o usuário pode enviar mais de um tipo de documento — por exemplo, CNH ou RG — e você não quer pedir que ele escolha antes da captura.

Endpoint

ENDPOINT

/image

MÉTODO

POST

STATUS

200

É o mesmo endpoint do envio com template. O que muda o comportamento é o corpo: envie allowed_templates no lugar de template. Os dois campos são mutuamente exclusivos — enviar ambos, ou nenhum, retorna 400.

Autenticação

Envie a chave de API no header Authorization. Ver Autenticação.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição	Tamanho
document_b64	string	Sim	Arquivo do documento em base64. JPEG ou PDF de uma única página.	3 MB (JPEG), 30 MB (PDF)
allowed_templates	string[]	Sim	Tipos de documento que você aceita receber. Valores na tabela Templates permitidos.	—

{
  "document_b64": "YOUR_BASE64_DOCUMENT",
  "allowed_templates": ["cnh", "rg"]
}

import requests

response = requests.post(
    "https://api.caas.qitech.app/ocr/image",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "document_b64": "YOUR_BASE64_DOCUMENT",
        "allowed_templates": ["cnh", "rg"],
    },
)
print(response.status_code, response.json())

Templates permitidos

Informe o documento inteiro (cnh) para aceitar qualquer um dos lados, ou um lado específico (cnh_front) para aceitar só aquele lado.

Valor	Aceita
cnh	CNH física, frente (cnh_front) ou verso (cnh_back).
cnh_front, cnh_back	Só o lado indicado da CNH física.
cnh_digital	PDF da CNH digital.
rg	RG ou CIN física, frente (rg_front) ou verso (rg_back).
rg_front, rg_back	Só o lado indicado do RG ou da CIN física.
cin_digital	PDF da CIN digital.
rg_digital	PDF do RG digital.
national_migration_registry	CRNM, frente ou verso.
national_migration_registry_front, national_migration_registry_back	Só o lado indicado da CRNM.
national_registry_of_foreigners	RNE, frente ou verso.
national_registry_of_foreigners_front, national_registry_of_foreigners_back	Só o lado indicado do RNE.

Resposta

Campo	Tipo	Descrição
ocr_key	uuid	Chave da imagem. Use-a para referenciar o documento nos demais produtos QI Tech.
template	string	Template identificado, sempre com o lado quando o documento tem dois: cnh_front, rg_back, cnh_digital...
is_inferred_template	boolean	true quando o template foi identificado pela classificação automática.
allowed_templates	string[]	A lista enviada na requisição.
created_at	string	Data e hora do processamento, em ISO 8601 (UTC).

{
  "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
  "template": "cnh_front",
  "is_inferred_template": true,
  "allowed_templates": ["cnh", "rg"],
  "created_at": "2026-10-16T13:45:12Z"
}

Recupere a imagem depois pelo ocr_key, como descrito em Enviando um documento.

Aviso importante

Não use dados reais de pessoas físicas ou jurídicas no ambiente de sandbox.

Erros

Documento reprovado

Quando a imagem é processada mas reprovada, a resposta é 400 e traz o ocr_key da tentativa. title indica a categoria e reason, o motivo:

{
  "title": "invalid",
  "description": "The uploaded image cannot be successfully processed.",
  "reason": "document_not_allowed",
  "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9"
}

Status	title	reason	Quando acontece
400	invalid	template_not_classified	A OCR não reconheceu o documento.
400	invalid	document_not_allowed	O documento foi reconhecido, mas não está em allowed_templates.
400	invalid	multiple_documents_found	Há mais de um documento na imagem.
400	invalid	invalid_document	A imagem não foi aceita como um documento válido do tipo identificado.
400	invalid	missing_document_section	Parte do documento está fora da imagem ou encoberta.
400	invalid	missing_data	Campos obrigatórios do documento não puderam ser lidos.
400	invalid	qr_code_not_found	PDF digital (CNH, RG ou CIN) sem QR code.
400	invalid	not_digitally_signed	PDF digital (CNH, RG ou CIN) sem a assinatura digital do emissor.
400	bad_quality	blurred_document	Imagem desfocada ou de baixa qualidade. Só para JPEG.
400	bad_quality	document_position_invalid	O documento encosta na borda da imagem. Só para JPEG.
400	bad_quality	glare_on_document	Reflexo que encobre ou distorce informações do documento.
400	bad_quality	color_irregularity	Distribuição de cor irregular no documento.
400	bad_quality	face_not_found	Nenhum rosto detectado na foto do documento.
400	bad_quality	face_out_of_bounds	O rosto está parcialmente fora da imagem.
400	bad_quality	face_brightness_problem	O rosto está escuro demais.
400	bad_quality	face_too_close	O rosto ocupa uma área grande demais da imagem.
400	bad_quality	face_too_distant	O rosto ocupa uma área pequena demais da imagem.

A validação de rosto (face_*) só é aplicada aos lados com foto: frente da CNH, frente do RG ou da CIN, frente da CRNM e verso do RNE.

Requisição recusada

Estes erros acontecem antes do processamento e não geram ocr_key:

Status	title	reason	Quando acontece
400	Invalid JSON	—	O corpo da requisição não é um JSON válido.
400	Request data failed validation	—	Corpo fora do contrato: campo obrigatório ausente, campo desconhecido, valor fora da lista, ou template enviado junto com allowed_templates.
400	Invalid base64	invalid_base64	document_b64 não é base64 válido, ou o arquivo não é JPEG nem PDF.
400	File is too big	max_file_size_exceeded	JPEG acima de 3 MB ou PDF acima de 30 MB.
400	Document is too big	max_pages_exceeded	PDF com mais de uma página.
401	Authorization header not found	—	Header Authorization ausente.
401	Deactivated ApiKey	—	Chave de API desativada.
403	Invalid ApiKey	—	Chave de API inexistente.
500	Internal Server Error	—	Falha interna. Tente novamente mais tarde.

Os status HTTP genéricos estão em Status HTTP.