Skip to main content
POST

Quando usar

Use este endpoint quando você já tem o balanço e a DRE em PDF e quer que a GYRA+ transforme as demonstrações em dados estruturados: balanço e DRE padronizados, indicadores calculados e parecer de IA, tudo dentro de um relatório de CNPJ já existente. É o mesmo processamento que roda quando um analista envia o balanço pela tela do Toolbox. Se o relatório já tem balanço, o envio soma ao que existe, não substitui. Veja o funcionamento completo em Análise Financeira.
A chamada é assíncrona. O 200 significa “arquivos aceitos e enfileirados”, não “dados prontos”. Os dados estruturados saem depois, em GET /report/{id}/section/BALANCE_SHEET (e nas demais seções financeiras).

Pré-requisitos

  1. Um relatório de CNPJ já criado (POST /v2/report), cujo id vai na URL.
  2. Token JWT válido (POST /auth/authenticate).
  3. Os PDFs, de preferência contendo apenas as páginas do Balanço Patrimonial e da DRE.

Autenticação

Bearer JWT no header Authorization. O relatório precisa ser da sua organização: a checagem acontece antes de qualquer arquivo ser gravado.

Parâmetros

O corpo é multipart/form-data. Não envie JSON.

Limites e validações

Enviar o PDF inteiro (capa, notas explicativas, parecer do auditor) funciona, mas custa mais e piora a precisão. Recorte o PDF nas páginas com números antes de enviar: Balanço Patrimonial (Ativo e Passivo) e DRE. Se cada exercício veio em um arquivo, mande todos na mesma chamada: eles são consolidados na mesma análise.

O que acontece depois

  1. Se o relatório ainda não tinha balanço, a chamada já cria as seções financeiras, vazias. É por isso que consultá-las logo depois do upload responde 200 com conteúdo vazio, e não 404.
  2. Cada arquivo vira um job de extração paralelo: leitura das tabelas (inclusive em documentos escaneados), padronização das linhas para o plano de contas único da GYRA+, validação da consistência contábil e cálculo dos indicadores.
  3. Ao final, as seções são preenchidas e a organização recebe um e-mail com a planilha consolidada.
Para consumir o resultado: O envio cria mais seis seções, derivadas das mesmas demonstrações: Todas as seções são organizadas por período ({"202401_202412": {...}}), o que permite comparar exercícios. A lista completa de tipos está em Consultar Seção por Tipo.
Para a maioria das integrações, BALANCE_SHEET, DRE e FINANCIAL_INDICATORS bastam. As seções de gráfico existem para a tela do Toolbox e não acrescentam informação.

Como saber que terminou

Não existe endpoint de status do lote. Duas formas de acompanhar:
Consulte GET /report/{id}/section/BALANCE_SHEET a cada alguns minutos. Como as seções passam a existir já no 200 do upload, a leitura é sempre 200: conteúdo vazio significa que a extração ainda está rodando, conteúdo preenchido significa que terminou.Um 404 aqui não quer dizer “ainda processando”, e sim que aquele relatório nunca recebeu balanço, nem por envio nem por descoberta automática.
Relatórios criados por POST /v2/report notificam por webhook. Com um webhook do tipo REPORT registrado, sua URL recebe um POST a cada atualização de seção do relatório, incluindo as financeiras.O payload traz o conteúdo da seção em data.content e o relatório em data.content.report.id, mas não identifica qual seção foi atualizada. Ou seja: use o webhook como gatilho para reconsultar a seção que te interessa, não como um evento “balanço pronto”.
Se a extração falhar ou ficar abaixo do nível de confiança exigido, as seções não são preenchidas com número errado: o erro fica registrado no campo errors da seção e o documento original continua disponível para conferência manual.
Arquivos grandes, perto do limite de 50 MB? Use o upload direto: o PDF vai do seu sistema direto ao armazenamento, em dois passos, com o mesmo resultado.
A resposta 200 é o relatório, com todas as seções e sem o conteúdo delas (sectionDetails). O exemplo abaixo está resumido.

Authorizations

Authorization
string
header
required

Enter JWT token

Path Parameters

id
string
required

ID do relatorio (CNPJ) que vai receber as demonstracoes.

Body

multipart/form-data
files
file[]
required

PDFs do balanco patrimonial e/ou da DRE. Repita o campo files para enviar mais de um arquivo. Ate 10 arquivos por chamada, 50MB cada, somente PDF.

Response

Relatorio atualizado, com as secoes financeiras marcadas como em processamento.