Sobre esta API
Confere se o arquivo é um comprovante de endereço (conta de luz, água, gás, telefone ou internet, fatura de cartão, correspondência de banco ou de órgão público, IPTU) e se ele é dos últimos 3 meses, e devolve titular, CPF/CNPJ, endereço completo e as datas.
Envie a imagem ou o PDF em file. O prazo conta da data de emissão; sem ela, do vencimento; sem os dois, do fim do mês de referência. is_valid só é true quando é comprovante e está no prazo, e descricao diz o motivo quando não está.
É leitura do documento enviado: não confirma o endereço em outra fonte.
OCR com visão computacional · Atualização: tempo real
Requisição
POST /api/v1/oracle/document/addressAutenticaçã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 comprovante de endereço. |
curl --request POST 'https://api.apifordevs.com/api/v1/oracle/document/address' \
--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/address",
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/address", {
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 - Arquivo enviado
filenamestring - Parecer e dados do comprovante
validation_resultobject - Parecer da validação. Em faturamento, os meses vêm consolidados.
- É comprovante de endereço
validation_result.is_proof_of_addressboolean - Tipo de documento
validation_result.tipo_documentostring - Emissor
validation_result.emissorstring - Titular
validation_result.titularstring - CPF/CNPJ do titular
validation_result.cpf_cnpj_titularstring - Logradouro
validation_result.logradourostring - Número
validation_result.numerostring - Complemento
validation_result.complementostring - Bairro
validation_result.bairrostring
- Município
validation_result.municipiostring - UF
validation_result.ufstring - CEP
validation_result.cepstring - Data de emissão
validation_result.data_emissaostring - Vencimento
validation_result.data_vencimentostring - Mês de referência
validation_result.mes_referenciastring - Documento reconhecido
validation_result.is_validboolean - Data considerada
validation_result.data_consideradastring - Origem da data
validation_result.base_da_datastring - Dias desde a data
validation_result.dias_desde_a_datainteger - Dentro de 3 meses
validation_result.dentro_do_prazoboolean - Data da conferência
validation_result.data_atualstring - Parecer
validation_result.descricaostring
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": "COMPROVANTE_ENDERECO",
"filename": "conta-de-luz.pdf",
"validation_result": {
"is_proof_of_address": true,
"tipo_documento": "Conta de energia elétrica",
"emissor": "Companhia de Energia",
"titular": "FULANO DE TAL DA SILVA",
"cpf_cnpj_titular": "529.982.247-25",
"logradouro": "RUA EXEMPLO",
"numero": "100",
"complemento": "APTO 12",
"bairro": "CENTRO",
"municipio": "SAO PAULO",
"uf": "SP",
"cep": "01001-000",
"data_emissao": "02/10/2026",
"data_vencimento": "20/10/2026",
"mes_referencia": "09/2026",
"is_valid": true,
"data_considerada": "02/10/2026",
"base_da_data": "data_emissao",
"dias_desde_a_data": 16,
"dentro_do_prazo": true,
"data_atual": "18/10/2026",
"descricao": "Comprovante de endereço válido: emitido em 02/10/2026."
}
}
]
}
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 e KYC
Aceitar só comprovante recente e preencher o endereço do cadastro a partir dele.
Conferência de titularidade
Comparar o titular do comprovante com o cliente, e decidir se pede declaração de residência quando não é o mesmo.