Documentos

Leitura de comprovante de endereço

Confere se é um comprovante de endereço dos últimos 3 meses e devolve titular e endereço.

OCRtempo real
POST/api/v1/oracle/document/address

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.

Tecnologia

OCR com visão computacional · Atualização: tempo real

Requisição

POST /api/v1/oracle/document/address

Autenticação HTTP Basic: public_key:secret_key em Base64. Guarde a chave secreta no servidor.

CabeçalhoDescrição
Authorization
Obrigatório
Chave de API em Basic: public_key:secret_key em Base64.
X-Project-Id
Opcional
Projeto que recebe a chamada. Sem ele, vale o projeto padrão da conta.
Idempotency-Key
Opcional
Repetir a mesma chave em até 24 horas devolve a resposta anterior, sem executar nem cobrar de novo.

Parâmetros

CampoTipo e localDescrição
file
Obrigatório
filefileImagem, 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'

Campos de resposta

Campos e tipos publicados no catálogo desta API.

Tipo de documentodocument_typestring
Arquivo enviadofilenamestring
Parecer e dados do comprovantevalidation_resultobject
Parecer da validação. Em faturamento, os meses vêm consolidados.
É comprovante de endereçovalidation_result.is_proof_of_addressboolean
Tipo de documentovalidation_result.tipo_documentostring
Emissorvalidation_result.emissorstring
Titularvalidation_result.titularstring
CPF/CNPJ do titularvalidation_result.cpf_cnpj_titularstring
Logradourovalidation_result.logradourostring
Númerovalidation_result.numerostring
Complementovalidation_result.complementostring
Bairrovalidation_result.bairrostring

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

HTTPDescriçãoCobrança
200Sucesso.Sujeita à cobrança
400

bad_request

live_key_cannot_use_dev_mode

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

unauthorized

Credencial ausente, inválida ou revogada.Sem cobrança
402

payment_required

Saldo insuficiente ou limite de gasto diário atingido.Sem cobrança
403

forbidden

ip_not_allowed

test_key_cannot_run_live

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

conflict

Requisição com a mesma Idempotency-Key ainda em andamento.Sem cobrança
413

payload_too_large

Arquivo acima de 20 MB.Sem cobrança
422

validation_error

Parâmetro obrigatório ausente ou fora do formato, ou Idempotency-Key repetida com outro conteúdo.Sem cobrança
429

rate_limit_exceeded

Limite de requisições por minuto da chave atingido.Sem cobrança
500

internal_error

Falha interna.Sem cobrança
503

service_unavailable

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.

SUA PRÓXIMA ENTREGA

Qual é a sua próxima integração?

Encontre a API que resolve o próximo passo do seu produto.