Granatum Financeiro

View saved version →

---
name: granatum-financeiro
description: >
  Use quando a conversa envolver Granatum ou dados financeiros da empresa: DRE,
  fluxo de caixa, resumo financeiro, pendências, extrato, lançamentos, contas a
  pagar/receber, criar ou corrigir lançamento. Não use para finanças pessoais
  genéricas, sistemas que não sejam Granatum, aconselhamento tributário/jurídico
  ou operações bancárias fora das ferramentas Granatum.
metadata:
  version: "0.1.0"
---

# Granatum Financeiro

Regras que valem para toda interação com o Granatum. Aplicar mesmo quando o
usuário não invocar nenhum comando específico.

## Resolver a empresa antes de qualquer coisa

Toda ferramenta do Granatum exige `wgi_conta_id`. Nunca inventar esse valor.

1. Chamar `listar_empresas` na primeira operação da sessão.
2. Se houver uma única empresa, adotá-la e seguir sem perguntar.
3. Se houver mais de uma, perguntar em qual trabalhar e manter essa escolha pelo
   resto da conversa.
4. Ao trocar de empresa no meio da conversa, avisar explicitamente e descartar
   IDs de conta, categoria e centro de custo obtidos para a empresa anterior -
   eles não são válidos entre empresas.

## Quando ler referências

- Para configurar ou testar a conexão, leia [references/config.md](references/config.md).
- Para criar lançamento, leia [references/novo-lancamento.md](references/novo-lancamento.md).
- Para DRE, leia [references/dre.md](references/dre.md).
- Para fluxo de caixa, leia [references/fluxo-caixa.md](references/fluxo-caixa.md).
- Para extrato, busca ou correção de lançamentos, leia [references/extrato.md](references/extrato.md).
- Para contas a pagar/receber e vencimentos, leia [references/pendencias.md](references/pendencias.md).
- Para visão geral do mês ou desempenho financeiro sem relatório específico, leia [references/resumo-mes.md](references/resumo-mes.md).
- Para montar escrita, interpretar erro da API, diagnosticar relatório inesperado ou lidar com campos, leia [references/regras-de-campo.md](references/regras-de-campo.md).

## Regime contábil: nunca deixar implícito

O regime determina qual data conta. Errar aqui produz um relatório que parece
certo e está errado.

| Situação | Regime |
| --- | --- |
| DRE (`obter_dre`) | `competencia`, sempre |
| Fluxo de caixa (`obter_fluxo_caixa`) | `caixa`, sempre |
| Drill-down após um relatório | o **mesmo** regime do relatório de origem |
| Listagem livre de lançamentos | `caixa` por padrão; declarar qual foi usado |

Ao apresentar qualquer número, dizer qual regime foi usado e o período coberto.
Se o usuário pedir algo ambíguo ("quanto faturei em julho"), assumir o padrão da
tabela, entregar o resultado e mencionar em uma linha que existe a outra leitura.

## Relatório zerado é diagnóstico, não resposta

Um DRE ou fluxo de caixa que volta com tudo em zero quase nunca significa
"não houve movimento". Antes de reportar ausência de dados ao usuário, verificar:

1. **Regime trocado** - competência vs caixa invertidos.
2. **Categorias não mapeadas** - conferir os alertas de mapeamento na resposta
   do relatório; categorias fora da árvore da DRE não aparecem no resultado.
3. **Período de referência** - confirmar o formato (`mensal`=YYYY-MM,
   `trimestral`=YYYY-Tn, `semestral`=YYYY-Sn, `anual`=YYYY) e se o período já
   fechou.
4. **Filtros herdados** - `conta_ids`, `categoria_ids` ou
   `centro_custo_lucro_ids` restritivos vindos de uma pergunta anterior.

Cruzar com `obter_lancamentos` no mesmo período para checar se há movimento
bruto. Só afirmar "não houve movimentação" depois disso.

## Guardrails de escrita

Escritas atingem os livros reais do cliente. Não existe modo de simulação.

**Antes de `criar_lancamento`:**

- Reunir os dados, montar um resumo legível (tipo, valor, vencimento, categoria,
  conta, pessoa, descrição) e **esperar confirmação explícita do usuário**.
  Nunca criar direto a partir do primeiro pedido, mesmo que todos os campos
  tenham sido informados de uma vez.
- Validar a categoria: só usar item com `aceita_lancamento=true`. Categoria-pai é
  recusada pela API. Se o usuário nomear uma categoria-pai, mostrar as folhas
  disponíveis abaixo dela e pedir para escolher.
- Validar a conta: usar `listar_contas` com `apenas_para_lancamento=true`.

**Duplicatas:**

Se a resposta vier com status `confirmacao_necessaria`, apresentar os
`lancamentos_existentes` ao usuário e perguntar se deve criar mesmo assim. Só
reenviar com `confirmar_duplicata: true` após um "sim" humano explícito.
**Nunca definir `confirmar_duplicata: true` por conta própria**, em nenhuma
circunstância, nem para "resolver" um erro, nem em retry automático.

**Exclusão:**

Só chamar `excluir_lancamento` quando o usuário pedir exclusão de forma direta e
inequívoca, identificando o lançamento. Confirmar antes. Nunca excluir como
efeito colateral de uma correção - para corrigir, usar `atualizar_lancamento`.

**Escopo de escrita ausente:**

As ferramentas de escrita exigem o escopo OAuth `lancamentos:write`, concedido
separadamente do escopo de leitura. Se uma ferramenta de escrita retornar erro
JSON-RPC `-32602` com `data.codigo = "escopo_insuficiente"`, `escopo_necessario`,
`escopos_concedidos` e `hint_for_llm`, a conexão do usuário foi autorizada apenas
para leitura.

Não é erro nos dados e não adianta ajustar os campos e tentar de novo. Dizer ao
usuário que a conexão atual só tem permissão de leitura e que, para criar,
alterar ou excluir lançamentos, precisa reconectar o Granatum aceitando a
permissão de alterar lançamentos. Depois disso, parar. **Não** repetir a chamada,
não tentar outra ferramenta de escrita, não sugerir contorno. Consultas continuam
funcionando normalmente - seguir ajudando com relatórios e leitura.

**Atualização preserva o que não é enviado:**

Em `atualizar_lancamento`, omitir um campo preserva o valor atual; passar `0` nos
campos de vínculo (`pessoa_id`, `centro_custo_lucro_id`, `forma_pagamento_id`)
é que remove. Isso é o **oposto** de `criar_lancamento`, onde omitir e passar
zero dão no mesmo. Para limpar um vínculo, enviar `0` explicitamente - omitir
retorna sucesso sem alterar nada. Enviar somente o delta confirmado com o
usuário, nunca o objeto inteiro.

## Regras de campo que causam erro silencioso

- `valor` é sempre positivo. O sinal vem de `tipo_lancamento`, nunca do número.
- `data_pagamento` é o único indicador de pago. Presente = pago, ausente =
  previsto. Não pode ser data futura.
- `data_competencia` omitida faz o Granatum resolver sozinho. Não inventar valor.
- `identificador_externo` é obrigatório e é o que protege contra duplicidade.
  Regras completas em [references/regras-de-campo.md](references/regras-de-campo.md).
- `atualizar_lancamento` só opera em lançamento simples. Séries, lançamentos
  compostos e transferências precisam ser editados na interface do Granatum -
  informar isso ao usuário em vez de tentar.

## Como apresentar números

- Formatar em reais (R$ 1.234,56).
- Sempre indicar período e regime.
- Em variações, dar o valor absoluto e o percentual.
- Não arredondar valores de lançamentos individuais.
- Não afirmar causa para uma variação sem ter feito drill-down. Dizer o que
  mudou, e oferecer investigar o porquê.

Referenced files: 9