Enviar documento

POST /v1/documents recebe o PDF bruto e responde 202 com o id do documento. Escopo documents:write.

Parâmetros

Parâmetro	Onde	Descrição
`cnpj`	consulta	14 caracteres sem pontuação: dígitos ou letras maiúsculas (aceita o CNPJ alfanumérico).
`period_end`	consulta	Data de encerramento do período, `AAAA-MM-DD`.
`entity`	consulta	`Individual` (padrão), `Controladora`, `Consolidado` ou `Combinado`.
`Idempotency-Key`	cabeçalho	Obrigatório. 1 a 128 caracteres, único na sua empresa.
`Content-Type`	cabeçalho	`application/pdf`.

O corpo é o PDF, sem multipart nem base64. A conferência confirma que o CNPJ e a data do documento batem com os informados; divergências viram recusa.

curl

curl --retry 5 --retry-max-time 120 \
  "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

const document = await finstat.documents.submit(
  {
    file: await readFile("balanco.pdf"),
    cnpj: "00000000000191",
    periodEnd: "2025-12-31",
    entity: "Individual",
  },
  { idempotencyKey: "lote-2025-12-0042" },
);

Limites do arquivo

Até 25 MiB. Acima disso, 413 pdf_too_large.
Até 100 páginas, cada uma até o formato A2. O envio não conta páginas: um PDF maior recebe 202, mas não é processado e termina em error com reason processing_failed. O mesmo vale para páginas acima de A2 (A1, por exemplo). Confira o PDF antes de enviar.
O corpo precisa começar com %PDF-; senão, 422 invalid_pdf.

Idempotência

A Idempotency-Key é obrigatória e vale dentro da sua empresa.

Mesma chave e mesma entrada (PDF, cnpj, period_end e entity) devolvem 202 com o mesmo id, sem criar outro documento nem nova cobrança.
Mesma chave com entrada diferente devolve 409 version_conflict.
Derive a chave do seu registro (por exemplo, o id do lote). Nunca gere uma nova a cada tentativa: depois de timeout ou falha de rede, repita com a mesma chave.

Respostas

HTTP	Significado
`202`	Aceito. Corpo com `id` e `status` (`queued`).
`401`	Chave inválida ou sem `documents:write`.
`409`	`version_conflict`: chave já usada com outra entrada.
`413`	`pdf_too_large` ou `body_too_large`.
`422`	`pdf_and_idempotency_key_required`, `invalid_pdf` ou `invalid_request`.
`429`	`too_many_requests`: sua chave já tem dois envios em andamento.
`500`	`internal_error`: repita com a mesma chave.
`503`	`capacity_busy`: espere o `Retry-After` e repita.

Detalhes em Erros e Limites e novas tentativas.

Nova conferência

A empresa pode pedir pelo portal uma nova conferência de um documento liberado ou recusado. Ele volta a review (ou a queued, se foi recusado antes de qualquer extração) com reason client_request. Não é preciso reenviar o PDF.