finstatdocs
API Entrar

Início rápido

Da chave de API ao primeiro resultado. Você precisa de acesso ao portal do finstat como proprietário da empresa e de um PDF de balanço/DRE.

1. Crie uma chave de API

No portal, abra Chaves de API e clique em Nova chave. Marque os escopos documents:write (enviar) e documents:read (consultar). A chave começa com fst_ e aparece uma única vez: guarde-a no gerenciador de segredos do seu sistema.

bash
export FINSTAT_API_KEY=fst_...  # nunca no código, no Git ou em logs

2. Envie o PDF

Envie o arquivo bruto (sem multipart nem base64) com o CNPJ, a data de encerramento e a entidade. A Idempotency-Key identifica o envio: use um valor do seu sistema, como o id do lote.

curl
curl "https://finstat.com.br/v1/documents?cnpj=00000000000191&period_end=2025-12-31&entity=Individual" \
  -H "Authorization: Bearer $FINSTAT_API_KEY" \
  -H "Idempotency-Key: lote-2025-12-0042" \
  -H "Content-Type: application/pdf" \
  --data-binary @balanco.pdf
Node
import { readFile } from "node:fs/promises";
import { Finstat } from "finstat";

const finstat = new Finstat(process.env.FINSTAT_API_KEY!);

const document = await finstat.documents.submit({
  file: await readFile("balanco.pdf"),
  cnpj: "00000000000191",
  periodEnd: "2025-12-31",
});
console.log(document.id); // guarde o id
Python
import os
from pathlib import Path

import httpx

response = httpx.post(
    "https://finstat.com.br/v1/documents",
    params={"cnpj": "00000000000191", "period_end": "2025-12-31", "entity": "Individual"},
    headers={
        "Authorization": f"Bearer {os.environ['FINSTAT_API_KEY']}",
        "Idempotency-Key": "lote-2025-12-0042",
        "Content-Type": "application/pdf",
    },
    content=Path("balanco.pdf").read_bytes(),
    timeout=60,
)
response.raise_for_status()
print(response.json()["id"])

A resposta 202 traz o id e "status": "queued":

json
{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "queued",
  "reason": null,
  "pages": 0,
  "processing_seconds": 0,
  "engine_version": "",
  "model_version": ""
}

3. Acompanhe a situação

O documento passa por queued e processing até completed; quando o resultado precisa de conferência humana, passa antes por review. Em produção, receba a mudança pelo webhook; para testar, consulte:

curl
curl "https://finstat.com.br/v1/documents/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $FINSTAT_API_KEY"
Node
const current = await finstat.documents.retrieve("00000000-0000-4000-8000-000000000001");
console.log(current.status); // queued | processing | review | completed | rejected | error
Python
response = httpx.get(
    "https://finstat.com.br/v1/documents/00000000-0000-4000-8000-000000000001",
    headers={"Authorization": f"Bearer {os.environ['FINSTAT_API_KEY']}"},
)
print(response.json()["status"])

4. Busque o resultado

Com status completed, busque o resultado. Antes disso a rota responde 409 not_completed.

curl
curl "https://finstat.com.br/v1/documents/00000000-0000-4000-8000-000000000001/result" \
  -H "Authorization: Bearer $FINSTAT_API_KEY"
Node
const history = await finstat.documents.result("00000000-0000-4000-8000-000000000001");
for (const [period, entries] of Object.entries(history)) {
  for (const entry of entries) console.log(period, entry.termo_total, entry.valor);
}
Python
response = httpx.get(
    "https://finstat.com.br/v1/documents/00000000-0000-4000-8000-000000000001/result",
    headers={"Authorization": f"Bearer {os.environ['FINSTAT_API_KEY']}"},
)
for period, entries in response.json().items():
    for entry in entries:
        print(period, entry["termo_total"], entry["valor"])

O resultado é um objeto por entidade e data, com uma lista de linhas. Veja Resultado e histórico.

Próximos passos