SDKs

Node.js

O pacote npm finstat é o SDK oficial para Node.js 20+, sem dependências, com tipos TypeScript gerados do servidor.

bash

npm install finstat

typescript

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",
});

Método	Rota
`documents.submit(params, { idempotencyKey? })`	`POST /v1/documents`
`documents.retrieve(id)`	`GET /v1/documents/{id}`
`documents.result(id)`	`GET /v1/documents/{id}/result`
`documents.waitForResult(id, { intervalMs?, timeoutMs? })`	Consulta até `completed`, `rejected` ou `error`.
`history.retrieve(cnpj)`	`GET /v1/history/{cnpj}`
`webhooks.constructEvent(rawBody, signature, secret)`	Verifica a assinatura e devolve o evento.

Configuração

Opção	Padrão	Descrição
`baseUrl`	`https://finstat.com.br`	Origem da API.
`maxNetworkRetries`	`2`	Novas tentativas em `429`, `503`, `5xx` e falha de rede, com a mesma `Idempotency-Key`.
`timeoutMs`	`60000`	Tempo máximo por tentativa.

Idempotência

Sem idempotencyKey, o SDK deriva a chave do conteúdo (SHA-256 do PDF + CNPJ + período + entidade): reenviar o mesmo arquivo devolve o mesmo documento, sem nova cobrança. Com { idempotencyKey: "lote-7" }, a deduplicação segue a sua chave; a mesma chave com outro conteúdo lança FinstatIdempotencyError.

Esperar o resultado sem webhook

typescript

const { document, history } = await finstat.documents.waitForResult(id); // consulta a cada 60 s
if (history === null) console.log("terminou sem resultado:", document.status, document.reason);

Tipos

O histórico é Record<string, HistoryEntry[]>. termo_total tem o tipo TermoTotal, um dos termos exportados em TERMS. Também são exportados DOCUMENT_STATUSES, ENTITIES e REJECT_CATEGORIES. Os erros estão em Erros.

Python

Em breve. Até lá, use httpx ou requests: todos os exemplos desta documentação têm a versão Python, e a referência traz cada rota.