Controlle

Cancela uma transação inteira (soft-delete: status=0 em transactions, transactions_itens e transactions_payments). Operação IDEMPOTENTE: se já estiver cancelada, retorna { already_cancelled: true } sem erro. NÃO confunda com pay_transaction: - cancel_transaction = remove a transação (não vai mais aparecer em queries / dashboard) - pay_transaction = registra que a parcela foi paga A transação não pode ser recuperada via esta tool (não há "uncancel"). Recuperação requer SQL admin. SEGURANÇA (leia): o id vem de query_transactions/get_transaction — nunca invente. Passe expected_value_in_cent com o valor que o usuário disse; se não bater com o lançamento real, a tool RECUSA e não cancela nada. Ao confirmar ao usuário, use a description e o value_in_cent QUE VIERAM NA RESPOSTA da tool — NUNCA invente valor/descrição. Resposta: { transaction_id, already_cancelled, items_cancelled, payments_cancelled, description, value_in_cent // o que REALMENTE foi cancelado — reporte estes } Use quando o usuário pede: - "cancela essa transação" - "exclui esse lançamento" - "esse boleto foi cancelado, tira dos meus registros"

cancel_transaction

Cancela VÁRIOS lançamentos numa ÚNICA chamada (soft-delete real de cada um). USE ISTO quando o usuário pede pra cancelar/excluir mais de um lançamento — NÃO chame cancel_transaction várias vezes e, acima de tudo, NUNCA diga que cancelou sem chamar esta tool. Fluxo: query_transactions para achar os ids (pela descrição/data/período que o usuário citou) → monte items[] com os transaction_id (e expected_value_in_cent quando souber o valor) → cancel_transactions_batch. Cada item é cancelado de fato; a resposta traz a contagem REAL — reporte esses números, nunca invente: { requested, cancelled_count, already_cancelled_count, failed_count, cancelled: [{ transaction_id, description, value_in_cent, already_cancelled }], failed: [{ transaction_id, reason }] } Se algum falhar (failed_count > 0), diga honestamente quantos foram e quantos não.

cancel_transactions_batch

Lista cartões de crédito de TODAS as empresas que o usuário tem acesso, agrupados por entidade — sem precisar trocar de entidade ativa (não usa switch_entity). Use quando o usuário pergunta de forma ampla: - "todos os meus cartões" - "cartões de todas as minhas empresas" - "qual empresa tem mais limite de cartão" Formato otimizado pra LLM: agrupado por entidade com contagem e limite total, depois os cartões. Só cartões ACTIVE. Resposta: { total_entities, total_cards, by_entity: [{ entity_id, entity_name, cards_count, total_limit_in_cent, cards: [{ id, name, banner, limit_in_cent, available_limit_in_cent }] }] }. Valores em CENTAVOS.

get_credit_cards_all_entities

Atribui/altera a CATEGORIA (plano de contas) e/ou o CENTRO DE CUSTO de uma transação existente — inclusive ADICIONAR centro de custo a um lançamento que você acabou de criar. Use quando o usuário pede, sobre um lançamento existente: - "adiciona o centro de custo Administrativo a essa despesa" - "categoriza essa transação como Aluguel" - classificar uma transação importada / realocar centro de custo MODO SIMPLES (padrão — use este para lançamento comum): passe transaction_id + cost_center_id e/ou plan_account_id pelo NOME ("Administrativo") no TOPO, e NÃO envie items. O sistema aplica a TODOS os itens da transação e resolve os item_id sozinho — você NÃO precisa chamar get_transaction nem lidar com id de item. Nome inexistente é RECUSADO (não inventa nem cria). MODO POR ITEM (só para RATEIO com categorias/centros diferentes por item): use items[] com item_id de get_transaction. Não é update_transaction (que muda descrição/data/contato). Passar null num campo REMOVE aquela classificação. Resposta: { transaction_id, items_updated, items: [{ item_id, plan_account_id, cost_center_id }] }

categorize_transaction

Concilia um LOTE de transações importadas 1:1 numa única chamada — cada par (imported_transaction_id → transaction_id) é conciliado de forma independente. Use quando o usuário quer conciliar VÁRIAS de uma vez ("concilia todas essas", "concilia as que têm candidato"). Assim você NÃO precisa chamar conciliate_imported_transaction item a item nem pedir confirmação a cada uma. Fluxo: 1. list_pending_conciliations → pendentes 2. suggest_conciliation_match em cada uma → escolha o candidato certo (valor/data que batem) 3. monte os pares e chame conciliate_batch UMA vez Cada par é independente: se um falhar (ex.: já conciliado), os outros seguem. Máx 50 por chamada — para mais, pagine em lotes de 50. Resposta: { total, conciled, failed, results: [{ imported_id, transaction_id, ok, error? }] } Reporte ao usuário quantas conciliou e quais falharam (com o motivo REAL) — não invente.

conciliate_batch

Vincula UMA transação importada do banco a UMA transação existente do Controlle. É a operação de "conciliação 1:1" — caso mais comum. Fluxo recomendado: 1. list_pending_conciliations(account_id) → imported_transactions pendentes 2. suggest_conciliation_match(imported_transaction_id) → candidatos transactions 3. conciliate_imported_transaction(imported_id, transaction_id) → liga as duas A imported_transaction sai do "pendente". A transaction recebe is_conciled=true. Esta tool cobre conciliação 1:1 (e, sem candidato, use create_transaction_from_imported). Casos 1:N / N:1 / N:N NÃO são suportados aqui — e NÃO afirme que o app web tem essa função (não temos certeza disso); apenas diga que por aqui você faz 1:1. Resposta: { imported_id, transaction_id, conciled: true }

conciliate_imported_transaction

Lista TRANSAÇÕES IMPORTADAS PENDENTES de conciliação — extratos bancários ou faturas de cartão importados (via Open Finance, OFX, etc.) que ainda não foram casados com lançamentos reais do Controlle. Critério de "pendente": imported_transactions.status=1 AND id_candidate IS NULL AND ignored=false. Vem de account_statements filtrado por id_entity da sessão. Use quando o usuário pergunta: - "o que tenho pra conciliar" - "extratos pendentes" - "movimentações importadas não classificadas" Para cada pendente, use suggest_conciliation_match(imported_transaction_id) para descobrir candidatos no Controlle. Campos retornados: - id: ID da imported_transaction (use em suggest_conciliation_match) - ds_transaction: descrição vinda do extrato bancário - vl_in_cents: valor em centavos (negativo = saída, positivo = entrada) - dt_transaction: data da movimentação no extrato (YYYY-MM-DD) - account_type, id_account_statement, source_type (OFX/Open Finance/etc.) - ignored: false (filtrado já) Ordenado por dt_transaction DESC (mais recente primeiro).

list_pending_conciliations

TOOL ABERTA: monta e executa uma query READ-ONLY via DSL JSON estruturado. Você (LLM) descreve a query como objeto JSON; o backend valida tudo contra allowlist e injeta filtro de entidade automaticamente. Apenas LEITURA — sem UPDATE/DELETE/INSERT. QUANDO USAR: prefira as tools especializadas (query_transactions, generate_dre, generate_cashflow, generate_dashboard) para o que elas cobrem. MAS quando o pedido precisa de algo que NENHUMA especializada faz — cruzar tabelas (join, ex.: contatos que têm NFe emitida), agregar por uma dimensão arbitrária (soma/contagem/média por contato, centro de custo, tag, conta), ou combinar filtros incomuns — USE ESTA TOOL. NÃO desista, NÃO diga "não consigo", e NÃO fique insistindo numa tool especializada que não faz aquilo. Esta é sua ferramenta de composição: quase toda pergunta de "quanto/quantos/quais por X" que não tem tool pronta se resolve aqui. Se precisar do NOME de uma dimensão (contato, categoria, centro de custo), faça o join da tabela correspondente e selecione o nome — não agrupe só pelo id. DSL: { from: <tabela base>, select: [{ col: "id" } | { agg: "sum", col: "value_in_cent", as: "total" }], filters: [{ col: "dt_competence", op: ">=", value: "2026-01-01" }, { col: "x", op: "in", value: [1,2,3] }, { col: "y", op: "between", value: 100, value_to: 200 }], joins: [{ table: "transactions_itens", on: { left_col: "id", right_col: "id_transactions" }, type: "left" }], group_by: ["plan_account_id"], order_by: [{ col: "total", direction: "desc" }], limit: 100 // máx 1000 } Tabelas permitidas: transactions, transactions_payments, transactions_itens, contacts, plan_accounts_entities, cost_centers, tags, accounts, tax_receipts. Ops permitidos: =, !=, <, <=, >, >=, in, like, between, is_null, is_not_null. Aggs permitidas: sum, count, avg, min, max. VALORES DE ENUM (colunas numéricas das tabelas raw — use estes NÚMEROS nos filtros e traduza na resposta; NÃO invente): - transactions.type: 0=lançamento normal · 1=transferência · 2=saldo inicial · 3=pagamento de fatura de cartão. Para receita/despesa "de verdade", filtre type=0 (exclui transferência, saldo inicial e pagamento de fatura). - transactions.activity_type: 1=entrada/receita · 0=saída/despesa. - transactions.status: 1=ativo · 0=inativo (use status=1). - transactions_payments.situation: 0=em aberto/pendente · 1=pago/recebido · 2=pago parcial. ("a pagar/a receber em aberto" = situation=0; "recebido/pago" = situation=1). - transactions_payments.status: 1=ativo (use status=1). - transactions_payments.value_in_cent: valor da parcela — DESPESA vem NEGATIVA (use ABS pra comparar módulo). payment_in_cent = valor efetivamente pago/baixado. - accounts.type: 0=corrente · 1=poupança · 2=investimento · 3=outros · 4=carteira digital. accounts.status: 1=ativa · 0=inativa · 2=excluída (exclua deletadas com status<>2). - plan_accounts_entities.movement: 1=entrada/receita · 0=saída/despesa · 2=outros. plan_accounts_entities.status: 1=ativo. plan_accounts_entities.others=true → categoria genérica "Outros". - Datas: dt_competence=competência (regime de competência) · dt_due=vencimento · dt_billing=data da baixa/pagamento (regime de caixa). REGRAS de segurança (server-side): - Filtro id_entity é INJETADO automaticamente em toda tabela com essa coluna. Não passe id_entity nos seus filtros — backend força. - Joins só funcionam entre pares pré-aprovados (ex.: transactions↔transactions_itens via id/id_transactions). Outros viram erro. - Colunas fora da allowlist de cada tabela viram erro. - statement_timeout 5s no DB. - Hard LIMIT 1000. - Tudo audit-logado. REJEITADO automaticamente: raw SQL strings, subqueries, CTEs, UNION, window functions, funções não-listadas, INFORMATION_SCHEMA, pg_*, regex, mutações. Use quando o usuário pede algo tipo: - "quanto cada cliente movimentou nos últimos 90 dias" (precisa custom: agrega por contact) - "lista distinct dos meus fornecedores com NFe emitida" (join contacts + tax_receipts, distinct) - "top 10 categorias por gasto este ano" (agg por plan_account) Resposta: { rows: [...], row_count, truncated: true/false (atingiu o LIMIT), sql_executed: "SELECT ... FROM ... LIMIT 100" (transparência), duration_ms }

generate_custom_report

Lista quantas transações importadas (vindas do banco via integração Pluggy ou upload OFX) estão PENDENTES de conciliação, agrupado por conta/cartão. Use no início de um fluxo de conciliação pra saber onde o usuário precisa agir: 1. list_pending_integrations → ver onde tem pendências 2. import_statement (opcional) → forçar nova importação se a conta tá há tempo sem update 3. list_pending_conciliations(account_id) → ver as imported_transactions específicas 4. suggest_conciliation_match(imported_transaction_id) → buscar candidatos 5. conciliate_imported_transaction → finalizar 1:1 Resposta: { total_pending: <int>, by_account: [{ account_id?, credit_card_id?, pending_count }] }

list_pending_integrations

Lista as contas bancárias/carteiras de TODAS as empresas que o usuário tem acesso, agrupadas por entidade — sem precisar trocar de entidade ativa (não usa switch_entity). Use quando o usuário pergunta de forma ampla, cobrindo várias empresas: - "saldo de todas as minhas empresas" - "quanto tenho no total considerando tudo" - "quais contas eu tenho em cada empresa" Formato otimizado pra LLM: agrupado por entidade (com contagem e saldo total da entidade), mais um grand_total geral. Evita N chamadas de list_accounts + switch_entity. Resposta: { total_entities, total_accounts, grand_total_balance_in_cent, by_entity: [{ entity_id, entity_name, accounts_count, total_balance_in_cent, accounts: [{ id, name, type, current_balance_in_cent, active }] }] }. Valores em CENTAVOS.

get_accounts_all_entities

Cria um novo cartão de crédito na entidade ativa. Campos obrigatórios: name, banner_id (bandeira), closing_day (fechamento), due_day (vencimento), limit_in_cent (limite em centavos). Opcionais: limit_alert, payment_account_id (conta de pagamento). Bandeiras (banner_id): 1=Alelo 2=Amex 3=Aura 4=Digio 5=Diners 6=Elo 7=Hipercard 8=Mastercard 9=Trigg 10=Visa 11=Outros. Use quando o usuário pede "cadastra/cria um cartão X com limite Y, fecha dia A vence dia B". Resposta: { id, name, banner_id, limit_in_cent }.

create_credit_card

Cria um novo centro de custo (cost center). Centros de custo classificam transações por área/departamento/projeto (ex.: "Marketing", "TI", "Filial SP"). Hierarquia simples: opcionalmente um centro pode ter um PAI (sub-centro). Max 1 nível. Use quando o usuário pede: - "cria centro de custo 'Marketing Digital'" - "preciso de um sub-centro 'Anúncios' dentro de Marketing" Resposta: { id, ds_cost_center, id_cost_center_parent }

create_cost_center

Cria uma nova conta bancária ou carteira digital na entidade. Pelo menos um de institution_financial_id ou digital_wallet_id deve estar presente — exceto pra carteiras locais simples (type="other") que aceitam ambos nulos. Use quando o usuário pede: - "cria conta corrente Banco do Brasil ag 1234 conta 56789" - "preciso de uma caixinha pra dinheiro físico" - "adiciona uma carteira pra Mercado Pago" Resposta: { id, ds_account, type, uuid }

create_account

Cria um novo contato (cliente, fornecedor ou ambos) na entidade ativa. OBRIGATÓRIO: NOME + papel (cliente/fornecedor) + (E-MAIL OU CPF/CNPJ — qualquer um dos dois; o sistema de produção exige isso; telefone sozinho NÃO basta). Se o usuário deu e-mail ou CPF/CNPJ, use. Se NÃO deu nenhum, PEÇA um dos dois de forma leve ("me passa um e-mail ou o CPF/CNPJ dele?") — NÃO invente valor e NÃO fique pedindo vários dados. Telefone é opcional (guardado, mas não substitui e-mail/CPF). NUNCA invente e-mail/telefone/CPF "placeholder" pra tentar contornar erro (ex.: teste@exemplo.com, none@none.com, 00000000) — se o usuário não deu, OMITA o campo. Não repita a tool trocando os args no chute. Se o sistema recusar por JÁ EXISTIR um contato com esse mesmo nome: diga em linguagem simples que já há um contato com esse nome e pergunte se é pra usar o existente ou cadastrar assim mesmo — NUNCA peça CPF/e-mail/telefone por causa disso. Checagem de duplicidade: você PODE fazer query_contacts pelo nome antes de criar, mas é SILENCIOSO — se não achar um contato existente, apenas crie. NUNCA diga ao usuário "não foi encontrado"/"não existe" (é óbvio: ele está CADASTRANDO um novo). Só avise se JÁ existir um parecido (possível duplicata). Se for pessoa física use type="person"; jurídica type="company" (+ company_name se tiver). Sem documento informado, crie mesmo assim. Pelo menos um de client/supplier deve ser true (se o usuário disser "fornecedor X", supplier=true; se "cliente", client=true). Resposta: { id, uuid, name, type, cpf_cnpj, email, phone, client, supplier, company_name } Use quando o usuário pede: - "cadastra esse fornecedor: ACME LTDA, CNPJ 12.345..." - "cria um novo cliente João da Silva, CPF X"

create_contact

Cria um novo lançamento financeiro com PARCELA ÚNICA (BILL_UNIQUE). MÍNIMO NECESSÁRIO: description + activity_type + total_in_cent. Todo o resto é opcional — se omitido, a tool aplica os MESMOS defaults do app web: - account_id → conta PADRÃO da entidade ("Conta Inicial") - plan_account_id → categoria "Outros" - dt_competence/dt_due → HOJE NÃO fique perguntando conta/categoria/data quando o usuário não informar: lance com os defaults e, DEPOIS, informe o que foi usado e ofereça ajustar. A resposta traz `defaults_applied` (['account'|'category'|'date']) e os nomes resolvidos — use isso pra dizer p.ex. "Lancei na Conta Inicial, categoria Outros, hoje. Quer trocar a conta, a categoria ou a data?". Só pergunte antes se o usuário pediu algo específico que você não conseguiu resolver. LIMITAÇÕES desta versão (v1): - Apenas BILL_UNIQUE (uma parcela). Para parcelado/recorrente, use o app web. - Sem cartão de crédito (id_credit_cards_main = null). - Sem rateio (apportionment) entre múltiplas categorias — um único plan_account. - Sem múltiplos centros de custo. - Sem tags / anexos. Se o usuário DER conta/categoria específicas: list_accounts / list_plan_accounts (folha, pode_lancar=true; movement="credit" p/ receita, "debit" p/ despesa — nunca categoria-pai) para obter os ids e passe-os. Resposta: { transaction_id, uuid, account_id, account_name, plan_account_id, plan_account_name, dt_competence, dt_due, defaults_applied } Para casos mais complexos (parcelado, cartão, rateio, recorrência), oriente o usuário a usar o app. Use quando o usuário pede: - "lança 50 de almoço" → cria despesa R$50 com os defaults, depois oferece ajuste - "lança uma despesa de R$ 1000 com aluguel, vence dia 15" - "registra uma receita de R$ 500 de venda de produto X"

create_transaction

Para uma transação importada do banco que NÃO tem candidato pra conciliar: CRIA um lançamento novo a partir dela E concilia, em UMA operação. Valor, data, conta e direção (entrada/saída) vêm da PRÓPRIA importada — você só escolhe a CATEGORIA (pela descrição) e, se quiser, contato/centro de custo. Quando usar: item de list_pending_conciliations SEM match (suggest_conciliation_match não trouxe candidato bom). NÃO use quando há candidato — aí é conciliate_imported_transaction (1:1). Fluxo: list_pending_conciliations → (sem candidato) → escolha a categoria via list_plan_accounts pela descrição da importada (o movement bate com a direção) → create_transaction_from_imported. Cria E concilia numa chamada só; NÃO chame conciliar depois. Pra vários itens, chame um por item (confirme uma vez e execute o lote). Resposta: { imported_id, created: true }

create_transaction_from_imported

Cria um lançamento PARCELADO ou RECORRENTE — múltiplas parcelas geradas pelo MS conforme regra. Use para: - **Parcelado** (compra em N vezes, com fim): recurrence_type="installments", recurrence_total = N (ex.: 12). NÃO use para despesa fixa. - **Despesa/receita FIXA contínua** (aluguel, salário, assinatura "todo mês", "fixo mês a mês"): recurrence_type="fixed", recurrence_rule="months", e NÃO envie recurrence_total (repete indefinidamente). NUNCA invente um número grande de meses. Diferenças vs create_transaction: - create_transaction: BILL_UNIQUE (1 parcela única). - create_recurring_transaction: INSTALLMENTS (N parcelas). Fluxo: 1. list_accounts → account_id 2. list_plan_accounts (movement="credit" pra income, "debit" pra outcome) → plan_account_id 3. query_contacts ou create_contact (opcional) 4. create_recurring_transaction Use quando o usuário pede: - "aluguel de R$ 3.000 fixo todo mês" / "salário recorrente" → fixed (SEM recurrence_total) - "aluguel pelos próximos 12 meses" → installments, recurrence_total=12 - "parcela essa compra em 6x de R$ 500" → installments, recurrence_total=6 NÃO duplique: se o usuário pede pra tornar recorrente um lançamento que JÁ EXISTE, não basta criar aqui — o lançamento único original continua e vira duplicata. Cancele o original antes (ou avise que vai substituí-lo). Resposta: { installments_created, first_transaction_id, first_dt_due }.

create_recurring_transaction

Cria uma nova categoria no plano de contas. Categorias classificam transações como receita/despesa por tipo (ex.: "Aluguel", "Vendas online", "Folha"). Movement DEVE bater com o tipo da transação que vai usá-la: - transação com activity_type="income" → categoria com movement="income" - transação com activity_type="outcome" → categoria com movement="outcome" Quase sempre uma categoria nova é FILHA de uma categoria pai (level 1, vinda do plano padrão). Use list_plan_accounts pra descobrir os pais possíveis. SEMPRE informe dre_group_id — sem ele a categoria não entra no DRE (o relatório de resultado). Escolha o grupo do DRE coerente com a natureza da categoria (ver lista no campo dre_group_id). Use quando o usuário pede: - "cria categoria 'Aluguel comercial' como despesa, filha de Despesas Operacionais" - "preciso de uma categoria pra receitas de consultoria" Resposta: { id, ds_category, movement, id_plan_accounts_parent, level }

create_plan_account

Cria uma ou mais tags na entidade ativa. Tags são usadas pra marcar transações (junto com plano de contas e centro de custo). Aceita ARRAY pra criar em lote — o MS valida duplicatas case-insensitive dentro da request E contra tags já existentes na entity. Use quando o usuário pede: - "cria uma tag chamada 'Projeto X'" - "preciso de tags pra Marketing, Operações e Financeiro" → crie 3 numa só chamada Resposta: { created: [{ id, ds_tag }, ...] }

create_tags

Registra uma TRANSFERÊNCIA entre duas contas da MESMA entidade. Cria 2 lançamentos espelhados (saída na origem, entrada no destino) vinculados por transaction_related_uuid. Não impacta saldo total da entity, só move entre contas. Diferente de create_transaction (que cria receita/despesa), aqui não há categoria obrigatória nem fornecedor. Use quando o usuário pede: - "transferi R$ 5.000 do Itaú pro Nubank" - "moveu R$ 1k da conta principal pra conta de poupança" - "registra transferência de A pra B" NÃO use para pagamento de fornecedor (esse é create_transaction outcome) nem pagamento de fatura de cartão (esse é pay_credit_card_invoice). Resposta: { related_uuid, source_account_id, destination_account_id, value_in_cent, dt_competence, status: "done" (transferência efetivada hoje/passado) | "scheduled" (agendada, competência futura) }. NÃO existe "pendente por saldo": o sistema efetiva a transferência mesmo deixando a conta negativa — reporte o status REAL retornado, sem especular.

create_transfer

Gera o DRE do período no MESMO cálculo do relatório oficial do Controlle (report/reportDre): soma as parcelas (transactions_payments) classificadas pela estrutura contábil de dre_groups e monta a cascata. Valores em CENTAVOS. Regime "competence" (default) ou "cash". IMPORTANTE (sinais): despesas/deduções vêm NEGATIVAS; receitas positivas. Cada nível da cascata é a SOMA do anterior com o próximo grupo (não subtraia de novo — o sinal já faz isso). Resposta: { from_date, to_date, regime, groups: [ { group (1..6), label, subtotal_in_cent, lines: [{ id_dre, ds_dre, type: "income"|"expense", value_in_cent }] } ], totals: { receita_operacional_in_cent, // grupo 1 deducoes_in_cent, // grupo 2 (negativo) receita_liquida_in_cent, // = receita_operacional + deducoes custos_in_cent, // grupo 3 (negativo) resultado_bruto_in_cent, // = receita_liquida + custos despesas_operacionais_in_cent, // grupo 4 (negativo) resultado_operacional_in_cent, // = resultado_bruto + despesas_operacionais financeiro_nao_operacional_in_cent, // grupo 5 resultado_antes_ir_in_cent, // = resultado_operacional + financeiro ir_csll_distribuicoes_in_cent, // grupo 6 (negativo) resultado_liquido_in_cent // = resultado_antes_ir + ir_csll (RESULTADO FINAL) } } Apresente a cascata na ordem acima (Receita líquida → Resultado bruto → Resultado operacional → Resultado antes do IR → Resultado líquido). Reporte os valores de "totals" verbatim (já em reais após /100). Grupos sem lançamento simplesmente não aparecem em "groups" (conte como 0 na cascata). Use quando o usuário pede: - "DRE de janeiro a março", "demonstrativo de resultado do ano" - "resultado do período", "lucro/prejuízo por competência ou caixa"

generate_dre

Snapshot financeiro instantâneo da entidade ativa: saldo total consolidado + parcelas vencidas + a vencer próximos 7 dias + receitas/despesas do mês corrente. Não aceita parâmetros (intencionalmente "agora mesmo"). Para outros períodos, use generate_dre ou generate_cashflow. Resposta (valores em CENTAVOS, datas YYYY-MM-DD): { as_of: data de hoje, current_balance_in_cent: saldo consolidado de todas contas ativas, accounts_count, overdue: { count, total_in_cent }, due_soon_7d: { count, total_in_cent }, month: { label "YYYY-MM", income_realized_in_cent, // entradas JÁ recebidas no mês income_forecast_in_cent, // total de entradas PREVISTAS no mês (recebido + a receber) expense_realized_in_cent, // saídas JÁ pagas no mês expense_forecast_in_cent, // total de saídas PREVISTAS no mês (pago + a pagar) net_realized_in_cent, net_forecast_in_cent } } Ao falar de entradas/saídas do mês, deixe claro o que é REALIZADO (já entrou/saiu) e o que é PREVISTO (total do mês); "a receber/a pagar ainda" = previsto − realizado. NÃO some o valor cheio de vendas parceladas como se fosse tudo do mês. Use quando o usuário pede: - "panorama atual" - "resumo financeiro de hoje" - "como está a minha empresa agora" - "dashboard"

generate_dashboard

Desativa (soft-delete) uma ou mais categorias do plano de contas (1-50 por chamada). RESILIENTE: se alguma categoria não puder ser desativada (é PAI com subcategorias, está EM USO em lançamentos, ou é padrão do sistema), as OUTRAS ainda são desativadas — nada de falhar tudo. Processa folhas antes dos pais (assim um pai que ficou sem filhos já sai na mesma chamada). Resposta: { requested, disabled_count, failed: [{ plan_account_id, reason }] }. REPORTE ao usuário quantas foram desativadas e, se failed não estiver vazio, diga QUAIS não deram e o MOTIVO (ex.: "tem subcategorias", "está em uso em lançamentos") — em linguagem simples, sem jargão. Para "zerar tudo": desative primeiro as que puder; as que têm lançamentos/subcategorias, avise o usuário (pode precisar mover os lançamentos antes).

disable_plan_accounts

Desativa (soft-delete) um centro de custo. Não afeta transações antigas que o usavam — apenas remove das listas ativas.

disable_cost_center

Desativa (soft-delete) um ou mais contatos. Mantém vínculos históricos com transações antigas; remove dos pickers/sugestões ativos. Algumas validações server-side: - Contato com CPF/CNPJ especial (ex.: Controlle Tecnologia LTDA) não pode ser excluído. - Operação em lote (até 50). Resposta: { disabled_count }

disable_contacts

Desativa (soft-delete) uma ou mais tags. Tags desativadas continuam vinculadas a transações antigas mas não aparecem como sugestão.

disable_tags

Desfaz uma conciliação prévia. A transação importada volta a aparecer como PENDENTE de conciliação; a transaction do Controlle perde is_conciled=true. Use quando o usuário pede: - "essa conciliação tá errada, desfaz" - "liguei a transação errada, preciso refazer" Resposta: { imported_id, desconciled: true }

desconciliate_imported_transaction

Retorna detalhe completo de UMA Nota Fiscal (tax_receipt) específica: todos os campos cadastrais + valor + datas + dados do prestador e consumidor. Pré-requisito: você precisa do id da NFe. Se o usuário não passou, use list_nfe com filtros (contact_id, datas) para localizar. Use quando o usuário pergunta: - "detalhes da nota X" - "dados completos da NFe Y" - "qual o CNPJ do prestador da nota Z" Diferente de list_nfe: traz TODOS os campos (incluindo external_id do provedor, gateway_id). Resposta: - { found: true, tax_receipt: TaxReceiptDto } se encontrada - { found: false } se id inválido OU NFe não pertence à entidade ativa

get_tax_receipts

Retorna o detalhe completo de UM lançamento específico, incluindo todas as suas parcelas (transactions_payments), contato, conta, categoria. Use somente quando o usuário já tem em mãos o ID ou UUID do lançamento — tipicamente após uma query_transactions ou query_payments que listou candidatos. NÃO use para buscar por descrição/data/contato — use query_transactions com filtros. Resposta: - { found: true, transaction: TransactionDto } se encontrado - { found: false } se id não existir OU pertencer a outra entidade (escopo respeitado) Valores em CENTAVOS no campo total_amount_in_cent.

get_transaction

Extrato DIÁRIO consolidado de UMA conta em uma janela de datas. Retorna saldo de abertura/fechamento + agregados diários (saldo, entradas, saídas). Importante: este endpoint retorna **agregados por dia**, não cada lançamento individual. Para listar movimentações lançamento-a-lançamento de uma conta, use query_transactions com account_id. Use quando o usuário pede: - "extrato do Itaú em maio" - "como foi o saldo da poupança nos últimos 30 dias" - "entradas e saídas da conta X esta semana" Resposta: - { found: true, statement: { opening_balance_in_cent, closing_balance_in_cent, items: [{date, daily_balance_in_cent, daily_income_in_cent, daily_outcome_in_cent, running_balance_in_cent}] } } se conta existir - { found: false } se account_id inválido na entidade ativa OU se não houver entidade ativa Valores em CENTAVOS. Datas em ISO 8601 (YYYY-MM-DD). Janela máxima: 365 dias.

get_account_statement

Lista FATURAS de cartão de crédito da entidade ativa, ordenadas por competência (mais recente primeiro). Quando credit_card_id é omitido, busca em todos os cartões da entidade (chamadas paralelas, 5 simultâneas). Use quando o usuário pergunta: - "minhas faturas em aberto" → status="open" - "faturas pagas em 2026" → status="paid", year=2026 - "fatura atual do Itaú" → credit_card_id=X (descubra via list_credit_cards futuramente) - "faturas dos últimos 3 meses" → from_date/to_date Diferença vs query_payments: - query_payments cobre parcelas de lançamentos comuns. NÃO inclui faturas de cartão (essas são entidades próprias). - get_credit_card_invoices cobre as faturas mensais agregadas dos cartões. Resposta: { items: CreditCardInvoiceDto[], total }. Campo value_in_cent em CENTAVOS. status derivado de situation: 1→"paid", 0→"open", outros→"unknown".

get_credit_card_invoices

Gera FLUXO DE CAIXA (cashflow) do período por bucket temporal: entradas + saídas + líquido + saldo acumulado. Difere de generate_dre: - DRE considera dt_competence (regime de competência) e categoriza por plano de contas. - Cashflow considera dt_billing (caixa efetivo, parcelas liquidadas) e agrupa só temporalmente. Filtra apenas parcelas LIQUIDADAS (situation IN [PAID, PAID_PARTIAL]) — fluxo real de dinheiro, não previsto. Resposta: { from_date, to_date, granularity, opening_balance_in_cent (0 — base relativa), closing_balance_in_cent, buckets: [{ bucket, income_in_cent, expense_in_cent, net_in_cent, running_balance_in_cent }] } Use quando o usuário pede: - "fluxo de caixa diário desse mês" - "movimentações de caixa de janeiro" - "evolução do caixa semana a semana" - "quanto entrou e saiu mês a mês"

generate_cashflow

Força uma importação de transações da conta/cartão via a integração bancária (Pluggy/Belvo). Cria um STATEMENT (registro de execução) e popula imported_transactions com o que vier da API do banco. Useful quando: - A última sincronização foi há muitas horas - O usuário acabou de fazer um pagamento e quer ver na hora - Conta nova foi conectada Exatamente UM de account_id OU credit_card_id deve ser informado. Sem datas → MS usa default (últimos 3 dias). Resposta: { statement_id?, new_transactions?, ok, message? } Após importar, use list_pending_conciliations(account_id) para ver as transações que precisam de conciliação manual.

import_statement

Marca uma transação importada como IGNORADA (não vai conciliar). Útil quando: - A transação importada é lixo/duplicada da integração - O usuário não quer registrar isso no Controlle (ex.: transferência entre contas próprias) Pra desfazer (re-incluir como pendente), use desconciliate_imported_transaction. Resposta: { imported_id, ignored: true }

ignore_imported_transaction

Lista NOTAS FISCAIS (NFe-S, tax receipts) da entidade ativa. Tabela tax_receipts. TODOS os parâmetros são opcionais — chame sem args para listar últimas 50 emitidas. Use quando o usuário pergunta: - "minhas notas fiscais" → sem args - "NFe do iFood" → primeiro query_contacts(filter="iFood") → depois list_nfe(contact_id=X) - "NFe canceladas este ano" → situation="cancelled", from_date inicio do ano - "NFe de maio" → from_date/to_date Para detalhes completos de UMA NFe específica, use get_tax_receipts(id). Campos retornados (lista resumida): - id: ID da NFe (use em get_tax_receipts) - id_contact: ID do cliente - number: número da NF (string, pode ser null) - dt_emitted_at: data de emissão (YYYY-MM-DD ou null) - vl_amount_in_cents: valor em centavos - situation: status numérico da NFe - ds_service: descrição do serviço prestado - provider_company_name, consumer_fiscal_name: nomes formais - dt_cancelled_at: null se ativa, data se cancelada Ordenado por dt_emitted_at DESC.

list_nfe

Lista os CARTÕES DE CRÉDITO da entidade ativa (não as faturas — pra faturas use get_credit_card_invoices). Retorna por cartão: nome, bandeira (Visa/Master/Elo/...), limite, limite disponível, dia de fechamento, dia de vencimento, conta de pagamento vinculada e status. Use quando o usuário pergunta: - "quais cartões eu tenho" - "qual o limite do meu cartão X" - "quando fecha/vence a fatura do cartão Y" (closing_day/due_day) Resposta: { items: CreditCardDetailDto[], total }. Valores em CENTAVOS. status: active/inactive/deleted (DELETED já filtrado).

list_credit_cards

Lista os CENTROS DE CUSTO da entidade ativa. Tabela cost_centers — hierarquia opcional para classificar transações por departamento/projeto/filial. TODOS os parâmetros são opcionais — chame sem args para listar todos os centros ativos. NÃO peça refinamento. Use quando o usuário pergunta: - "meus centros de custo" → sem args - "centros inativos" → active=false Diferença vs. plano de contas: - plan_accounts = QUAL natureza do lançamento (Aluguel, Folha, Vendas). - cost_centers = QUAL projeto/departamento gerou (Filial SP, Marketing, Obra-X). Campos: - id, ds_cost_center (nome), id_parent (hierarquia), active.

list_cost_centers

Lista as CONTAS BANCÁRIAS da entidade ativa (corrente, poupança, investimento, outras). Cada item traz id, nome, tipo, banco, status e saldo atual em centavos. Use ANTES de chamar outras tools que pedem account_id quando o usuário só mencionou o nome ("Itaú PJ", "Nubank PJ"). Descubra o ID aqui e use nas próximas chamadas. Também responde perguntas como: - "quais contas tenho cadastradas" - "minhas contas correntes" (com type="checking") - "contas inativas" (com active=false) NÃO use para: - Saldo consolidado total → get_consolidated_balance (mais barato) - Saldo de UMA conta específica → get_account_balance - Extrato/movimentações → get_account_statement - Faturas de cartão de crédito → get_credit_card_invoices Resposta: { items: AccountDto[], total }. Saldos em CENTAVOS no campo current_balance_in_cent. Pode vir null se o cálculo falhar — nesse caso explicite ao usuário.

list_accounts

Lista o PLANO DE CONTAS (categorias DRE) da entidade ativa. Tabela plan_accounts_entities — hierarquia de categorias usadas para classificar lançamentos. TODOS os parâmetros são opcionais — chame sem args para listar todas as categorias ativas. NÃO peça refinamento ao usuário antes de chamar. Use quando o usuário pergunta: - "quais minhas categorias / plano de contas" → sem args - "categorias de despesa" → movement="debit" - "categorias de receita" → movement="credit" - "categorias inativas" → active=false Campos retornados: - id: ID numérico (use para outras tools que filtram por categoria) - key_category: código curto da categoria (ex.: "3.1.01") - ds_category: nome legível (ex.: "Aluguel") - id_parent: id da categoria pai (null = raiz) - level: profundidade hierárquica (0 = raiz) - is_father: true se tem filhas (categoria-pai/grupo) - pode_lancar: true = categoria FOLHA, lançável em create_transaction. false = categoria-pai/grupo, NÃO aceita lançamento (o sistema rejeita). - movement: 0=débito (despesa), 1=crédito (receita) - active: status === 1 CRÍTICO ao escolher plan_account_id p/ create_transaction: use SEMPRE um item com pode_lancar=true (folha). Categoria-pai (pode_lancar=false, ex.: um grupo "Combustíveis" que tem subcategorias) é REJEITADA pelo sistema. Se o nome que o usuário citou for uma categoria-pai, desça e escolha a subcategoria folha mais adequada; se houver várias, mostre as opções ao usuário. NUNCA crie uma categoria nova pra contornar isso.

list_plan_accounts

Lista as TAGS (etiquetas) da entidade ativa. Tabela tags. Tags são marcadores livres para classificar lançamentos transversalmente (ex.: "viagem-cliente-X", "marketing-Q1", "reembolsar"). Vinculação: cada transaction pode ter N tags via tabela transactions_tags (M:N). Diferente de plano de contas (categoria DRE) e cost center (departamento), tag é etiqueta flexível, sem hierarquia obrigatória, definida pelo usuário. TODOS os parâmetros são opcionais — chame sem args para listar todas. Use quando: - "minhas tags / etiquetas" → sem args - "tags ativas" → active=true Campos: - id: ID numérico (use em outras tools quando filtrar por tag) - ds_tag: nome da tag - active: status === 1 Resposta cacheada por 5 minutos no Redis (tags mudam pouco).

list_tags