Sobre esta API

Lê o demonstrativo de faturamento enviado pela empresa e extrai razão social, CNPJ, período e o valor de cada mês.

Envie o PDF ou a imagem em file. Em PDF, até 12 páginas são lidas e os meses voltam numa lista só, em número decimal e sem símbolo de moeda.

É leitura do documento enviado: não consulta a Receita nem confere os valores com outra fonte.

Tecnologia

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

Requisição

POST /api/v1/oracle/document/revenue

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

Cabeçalho	Descriçã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

Campo	Tipo e local	Descrição
`file` Obrigatório	filefile	PDF ou imagem do demonstrativo de faturamento.

1curl --request POST 'https://api.apifordevs.com/api/v1/oracle/document/revenue' \
2  --user "afd_live_pk_...:$AFD_SECRET_KEY" \
3  --header "X-Project-Id: $AFD_PROJECT_ID" \
4  --form 'file=@./file.jpg'

1import os
2import requests
3
4file = open("./file.jpg", "rb")
5response = requests.request(
6    "POST",
7    "https://api.apifordevs.com/api/v1/oracle/document/revenue",
8    auth=("afd_live_pk_...", os.environ["AFD_SECRET_KEY"]),
9    headers={"X-Project-Id": os.environ["AFD_PROJECT_ID"]},
10    files={"file": file},
11    timeout=30,
12)
13response.raise_for_status()
14print(response.json())
15file.close()

1import { readFile } from "node:fs/promises";
2const form = new FormData();
3form.append("file", new Blob([await readFile("./file.jpg")]), "file.jpg");
4
5const response = await fetch("https://api.apifordevs.com/api/v1/oracle/document/revenue", {
6  method: "POST",
7  headers: {
8    Authorization: "Basic " + Buffer.from(
9      "afd_live_pk_...:" + process.env.AFD_SECRET_KEY
10    ).toString("base64"),
11    "X-Project-Id": process.env.AFD_PROJECT_ID,
12  },
13  body: form,
14  signal: AbortSignal.timeout(30000),
15});
16if (!response.ok) throw new Error(`HTTP ${response.status}`);
17console.log(await response.json());

Campos de resposta

Campos e tipos publicados no catálogo desta API.

Tipo de documentodocument_typestring
Arquivo enviadofilenamestring
Faturamento consolidadovalidation_resultobject: Parecer da validação. Em faturamento, os meses vêm consolidados.
Documento reconhecidovalidation_result.is_validboolean
Tipo de documentovalidation_result.document_kindstring
Razão socialvalidation_result.company_namestring
CNPJvalidation_result.cnpjstring
Períodovalidation_result.periodobject
Faturamento mensalvalidation_result.monthlyarray
Mêsvalidation_result.monthly[].monthstring
Valorvalidation_result.monthly[].amountnumber
Parecervalidation_result.descricaostring

Exemplo de resposta

1{
2  "success": true,
3  "code": 200,
4  "code_message": "A requisição foi processada com sucesso.",
5  "errors": [],
6  "header": null,
7  "data_count": 1,
8  "data": [
9    {
10      "document_type": "FATURAMENTO_EMPRESA",
11      "filename": "faturamento-2026.pdf",
12      "validation_result": {
13        "is_valid": true,
14        "document_kind": "faturamento",
15        "company_name": "COIN NODES LTDA",
16        "cnpj": "49.670.293/0001-03",
17        "period": {
18          "start": "01/2026",
19          "end": "03/2026"
20        },
21        "monthly": [
22          {
23            "month": "01/2026",
24            "amount": 128400
25          },
26          {
27            "month": "02/2026",
28            "amount": 141250
29          },
30          {
31            "month": "03/2026",
32            "amount": 136900.5
33          }
34        ],
35        "descricao": "Documento de faturamento com 3 meses identificados",
36        "pages_analyzed": 2
37      }
38    }
39  ]
40}

Respostas e cobrança

HTTP	Descrição	Cobrança
`200`	Sucesso.	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

Análise de crédito PJ

Transformar o demonstrativo enviado pelo cliente em série mensal para alimentar o modelo de limite.

Enquadramento de porte

Conferir a receita declarada contra o porte informado no cadastro.

Leitura de faturamento da empresa