Sobre esta API
Extrai os dados de CNH, RG, passaporte, cartão CNPJ e contrato social a partir da foto ou do PDF, prontos para preencher um cadastro.
Informe o tipo em document_type e envie o arquivo em file — imagem, HEIC ou PDF, até 20 MB. Os campos de analysis_result variam conforme o tipo, e is_valid indica se o arquivo é mesmo o documento informado.
Lê o que está impresso: não confere os dados em base oficial nem atesta a autenticidade do documento.
OCR com visão computacional · Atualização: tempo real
Requisição
POST /api/v1/oracle/document/readAutenticação HTTP Basic: public_key:secret_key em Base64. Guarde a chave secreta no servidor.
| Cabeçalho | Descrição |
|---|---|
AuthorizationObrigatório | Chave de API em Basic: public_key:secret_key em Base64. |
X-Project-IdOpcional | Projeto que recebe a chamada. Sem ele, vale o projeto padrão da conta. |
Idempotency-KeyOpcional | Repetir a mesma chave em até 24 horas devolve a resposta anterior, sem executar nem cobrar de novo. |
Parâmetros
| Campo | Tipo e local | Descrição |
|---|---|---|
fileObrigatório | filefile | Imagem, HEIC ou PDF do documento. |
document_typeObrigatório | stringquery | Tipo do documento enviado. Exemplo: |
curl --request POST 'https://api.apifordevs.com/api/v1/oracle/document/read?document_type=CNH' \
--user "afd_live_pk_...:$AFD_SECRET_KEY" \
--header "X-Project-Id: $AFD_PROJECT_ID" \
--form 'file=@./file.jpg'
import os
import requests
file = open("./file.jpg", "rb")
response = requests.request(
"POST",
"https://api.apifordevs.com/api/v1/oracle/document/read?document_type=CNH",
auth=("afd_live_pk_...", os.environ["AFD_SECRET_KEY"]),
headers={"X-Project-Id": os.environ["AFD_PROJECT_ID"]},
files={"file": file},
timeout=30,
)
response.raise_for_status()
print(response.json())
file.close()
import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("./file.jpg")]), "file.jpg");
const response = await fetch("https://api.apifordevs.com/api/v1/oracle/document/read?document_type=CNH", {
method: "POST",
headers: {
Authorization: "Basic " + Buffer.from(
"afd_live_pk_...:" + process.env.AFD_SECRET_KEY
).toString("base64"),
"X-Project-Id": process.env.AFD_PROJECT_ID,
},
body: form,
signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Campos de resposta
Campos e tipos publicados no catálogo desta API.
- Tipo de documento
document_typestring - Tipo de documento lido.
- Arquivo enviado
filenamestring - Nome do arquivo enviado.
- Campos extraídos
analysis_resultobject - Campos extraídos. As chaves variam por tipo de documento.
- Documento reconhecido
analysis_result.is_validboolean - Nome
analysis_result.nomestring - Em CNH, RG-FRONT, PASSAPORTE.
- Nº de registro
analysis_result.numero_registrostring - Em CNH.
- CPF
analysis_result.cpfstring - Em CNH, RG-FRONT, RG-BACK, PASSAPORTE.
- Nacionalidade
analysis_result.nacionalidadestring - Em CNH, PASSAPORTE.
- Documento de identidade
analysis_result.doc_identidadestring - Em CNH.
- Órgão emissor
analysis_result.org_emissorstring - Em CNH.
- Data de emissão
analysis_result.data_emissaostring - Em CNH.
- Validade
analysis_result.validadestring - Em CNH.
- Filiação 1
analysis_result.filiacao1string - Em CNH, RG-FRONT, RG-BACK, PASSAPORTE.
- Filiação 2
analysis_result.filiacao2string - Em CNH, RG-FRONT, RG-BACK.
- Data de nascimento
analysis_result.data_nascimentostring - Em RG-FRONT, RG-BACK, PASSAPORTE.
- Naturalidade (UF)
analysis_result.naturalidadestring - Em RG-FRONT.
- Órgão expedidor
analysis_result.orgao_expedidorstring - Em RG-FRONT, RG-BACK.
- Sexo
analysis_result.sexstring - Em RG-FRONT.
- RG
analysis_result.rgstring - Em RG-FRONT, RG-BACK.
- Data de expedição
analysis_result.data_expedicaostring - Em RG-BACK.
- Registro civil
analysis_result.registro_civilstring - Em RG-BACK.
- País emissor
analysis_result.pais_emissorstring - Em PASSAPORTE.
- Tipo de passaporte
analysis_result.tipo_passaportestring - Em PASSAPORTE.
- Zona de leitura (MRZ)
analysis_result.codigo_abaixostring - Em PASSAPORTE.
- Nº do passaporte
analysis_result.numero_passaportestring - Em PASSAPORTE.
- CNPJ
analysis_result.numero_cnpj_inscricaostring - Em CARTÃO_CNPJ.
- Data de abertura
analysis_result.data_aberturastring - Em CARTÃO_CNPJ.
- Razão social
analysis_result.nome_empresarialstring - Em CARTÃO_CNPJ.
- Nome fantasia
analysis_result.titulo_estabelecimento_fantasiastring - Em CARTÃO_CNPJ.
- CNAE principal
analysis_result.codigo_e_descricao_principalstring - Em CARTÃO_CNPJ.
- CNAEs secundários
analysis_result.codigos_e_descricoes_secundariasstring - Em CARTÃO_CNPJ.
- Natureza jurídica
analysis_result.codigo_e_descricao_natureza_juridicastring - Em CARTÃO_CNPJ.
- Logradouro
analysis_result.logradourostring - Em CARTÃO_CNPJ.
- Número
analysis_result.numerostring - Em CARTÃO_CNPJ.
- Complemento
analysis_result.complementostring - Em CARTÃO_CNPJ.
- CEP
analysis_result.cepstring - Em CARTÃO_CNPJ.
- Bairro
analysis_result.bairrostring - Em CARTÃO_CNPJ.
- Município
analysis_result.municipiostring - Em CARTÃO_CNPJ.
- UF
analysis_result.ufstring - Em CARTÃO_CNPJ.
- E-mail
analysis_result.emailstring - Em CARTÃO_CNPJ.
- Telefone
analysis_result.telefonestring - Em CARTÃO_CNPJ.
- Situação cadastral
analysis_result.situacao_cadastralstring - Em CARTÃO_CNPJ.
- Porte
analysis_result.portestring - Em CARTÃO_CNPJ.
- Capital social (MEI)
analysis_result.capital_socialstring - Em CARTÃO_CNPJ.
- Capital social (número)
analysis_result.capital_social_intinteger - Em CONTRATO_SOCIAL.
- Capital social (como escrito)
analysis_result.capital_social_strstring - Em CONTRATO_SOCIAL.
- Sócios
analysis_result.sociosobject - Em CONTRATO_SOCIAL.
Exemplo de resposta
{
"success": true,
"code": 200,
"code_message": "A requisição foi processada com sucesso.",
"errors": [],
"header": null,
"data_count": 1,
"data": [
{
"document_type": "CNH",
"filename": "cnh.jpg",
"analysis_result": {
"is_valid": true,
"nome": "FULANO DE TAL DA SILVA",
"numero_registro": "01234567890",
"cpf": "123.456.789-09",
"nacionalidade": "BRASILEIRO",
"doc_identidade": "12345678",
"org_emissor": "SSP SP",
"data_emissao": "14/03/2024",
"validade": "14/03/2034",
"filiacao1": "JOSE DE TAL DA SILVA",
"filiacao2": "MARIA DE TAL DA SILVA"
}
}
]
}
Respostas e cobrança
| HTTP | Descrição | Cobrança |
|---|---|---|
200 | Sucesso. | Sujeita à cobrança |
400
| Arquivo ou parâmetro que a rota não consegue processar, projeto inválido, ou dev_mode=true com chave de produção. | Sem cobrança |
401
| Credencial ausente, inválida ou revogada. | Sem cobrança |
402
| Saldo insuficiente ou limite de gasto diário atingido. | Sem cobrança |
403
| E-mail da conta não verificado, chave sem escopo para o serviço, IP fora da allowlist do projeto ou chave de teste sem dev_mode=true. | Sem cobrança |
409
| Requisição com a mesma Idempotency-Key ainda em andamento. | Sem cobrança |
413
| Arquivo acima de 20 MB. | Sem cobrança |
422
| Parâmetro obrigatório ausente ou fora do formato, ou Idempotency-Key repetida com outro conteúdo. | Sem cobrança |
429
| Limite de requisições por minuto da chave atingido. | Sem cobrança |
500
| Falha interna. | Sem cobrança |
503
| Serviço desativado ou temporariamente indisponível. | Sem cobrança |
Casos de uso
Onboarding sem digitação
O cliente fotografa a CNH e o formulário já vem preenchido: nome, CPF, filiação e validade, sem digitar nada.
Conferência de cadastro
Comparar o que o documento diz com o que o cliente declarou e levantar a divergência antes da aprovação.
Leitura de contrato social
Extrair capital social e sócios do contrato para instruir análise de crédito ou KYC de pessoa jurídica.
Notas de integração
- Cobrada por requisição e por token: documento de muitas páginas consome mais. O custo típico ao lado do preço é a média real dos últimos 30 dias.