Levar o fluxo de caixa para o BI

O painel da diretoria, o Power BI ou a planilha do controller querem os números do caixa sem ninguém exportar à mão. Três leituras cobrem quase tudo: o fluxo de caixa (dia a dia, realizado e projetado), o resumo (em aberto e vencido) e a lista de contas para quem monta o próprio modelo.

Quando usar	Atualizar um painel de caixa, uma previsão de pagamentos ou um relatório de inadimplência
Porta	REST (leitura) · Agente (MCP)
Você vai precisar	Módulo FINANCEIRO; permissão FINANCEIRO (leitura basta); token JWT de um usuário de integração só com essa permissão

Como funciona

job do BI (diário) ── GET /financeiro/fluxo-caixa?empresaId=&inicio=&fim= ──▶ TAI
                   ── GET /financeiro/titulo/resumo?empresaId= ──────────────▶ TAI
                   ── GET /financeiro/titulo/page?empresaId=&page=&size= ────▶ TAI
                   └─ grava nas tabelas do BI, com a data da carga

Passo a passo

1. Liste as empresas. Cada leitura é por estabelecimento.

   GET /empresa
   Authorization: Bearer $TAI_TOKEN

2. Leia o fluxo de caixa da janela.

   GET /financeiro/fluxo-caixa?empresaId=3&inicio=2026-10-01&fim=2026-12-31

   inicio e fim em yyyy-MM-dd, até 400 dias. Sem eles, a janela é o mês corrente mais os dois seguintes. A resposta traz:

   Bloco	O que é
   dias[]	Um item por dia: realizadoEntrada, realizadoSaida, projetadoEntrada, projetadoSaida, variacaoDia, variacaoAcumulada
   linhas[]	Cada movimento: data, natureza (REALIZADO ou PROJETADO), fonte (TITULO, FOLHA ou FISCAL), direcao, descricao, contraparte, valor, vencida, tituloId, parcelaId
   totais	Realizado e projetado, entradas e saídas, e variacaoLiquida da janela
   vencidasAntes	O que está em aberto com vencimento anterior à janela — quantidade e valor, de entrada e de saída
   posicaoContas[]	Por conta bancária: saldoDeclarado e dataSaldo do último extrato importado
   fontes[]	A declaração de cada fonte, com quantas linhas projetou e avisos (por exemplo, guias da folha sem data, que ficaram de fora)

3. Leia o resumo. Quatro números e as parcelas vencidas:

   GET /financeiro/titulo/resumo?empresaId=3

   apagarAberto, apagarVencido, areceberAberto, areceberVencido, parcelasVencidasPagar e parcelasVencidasReceber.

4. Carregue as contas (opcional). Para montar o próprio modelo — por categoria, contraparte ou competência —, pagine a lista de títulos:

   GET /financeiro/titulo/page?empresaId=3&competencia=2026-10&page=0&size=100

   Filtros: direcao, status (ABERTO, PARCIAL, LIQUIDADO, CANCELADO), competencia (AAAA-MM), contraparteId, categoriaId e search. Cada título traz valorTotal, valorPago, valorAberto, categoriaNome, contraparteNome e proximoVencimento; o detalhe das parcelas sai em GET /financeiro/titulo/{id}.

Como ler os números

• Realizado são as baixas da janela, na data em que aconteceram (regime de caixa). Projetado são as parcelas em aberto pelo saldo restante, mais as obrigações da folha ainda pendentes (FGTS, INSS, IRRF).
• variacaoAcumulada é variação, não saldo: começa em zero no primeiro dia da janela. Se o painel precisa de saldo, some a posição das contas por sua conta e risco — e lembre que ela é o que o banco declarou no último extrato, na dataSaldo, não o saldo de hoje. Conta sem extrato importado vem com saldo nulo.
• Vencidas antes da janela não aparecem em dias[]: vão atravessar o caixa em data desconhecida e por isso vêm separadas. Não descarte esse bloco.
• Uma conta cancelada vale zero nos totais.

Demonstrativos contábeis

Se a empresa contabiliza a folha e o financeiro pela TAI (módulo Folha de Pagamento), a DRE, o balancete, o razão e o diário do período saem numa chamada:

GET /contabil/peca?empresaId=3&competencia=2026-10&pecas=DRE,BALANCETE

A DRE traz totalReceitas, totalDespesas, resultado e avisos. Exige a permissão FOLHA e só reflete o que já virou lote contábil — veja Trabalhar com o escritório contábil.

Atualizar na hora

A carga diária basta para a maioria dos painéis. Se o painel precisa mudar assim que o caixa muda, um webhook assinando os eventos do Financeiro avisa o seu job: PARCELA_BAIXADA e PARCELA_ESTORNADA mexem no realizado, TITULO_CRIADO e TITULO_CANCELADO no projetado, e EXTRATO_IMPORTADO (com contaBancariaId) na posição da conta. Ao receber, releia só o que mudou — o título pelo tituloId, ou a janela do fluxo de caixa.

Pelo seu agente de IA

“Quanto a empresa tem a pagar nos próximos 30 dias, por categoria? E quanto já está vencido?”

O agente lê o fluxo e o resumo e responde em conversa; com exportar_para_excel ele entrega a planilha por link temporário. Só leitura — veja Ferramentas.

Cuidados

• Uma janela por chamada, até 400 dias. Para históricos longos, divida em janelas.
• Datas dos parâmetros em yyyy-MM-dd; competência em AAAA-MM. Veja Datas e formatos.
• Pagine com size entre 50 e 200 e agende a carga fora do horário de pico — veja Limites.
• O fluxo é leitura pura: chamá-lo não altera nada e pode ser repetido à vontade.