aggregate_transactions
ChatGPTAgrega lançamentos de forma DETERMINÍSTICA no banco: soma/conta/média/máximo/mínimo, agrupado por uma dimensão. USE ISTO para qualquer pergunta de "quanto/quantos/qual o maior/menor/média por X" — NUNCA some, conte ou ache o maior de cabeça a partir de query_transactions (você erra: reporta a página como se fosse o total, pega o maior só da página, etc.). Cobre: - "quanto gastei por categoria" → metric="sum", group_by="category", direction="outcome" - "qual conta tem mais lançamentos" → metric="count", group_by="account" - "meu maior lançamento" → metric="max", (sem group_by → um número) ou group_by pra ver por dimensão - "quantas transações de cada tipo" → metric="count", group_by="type" - "média de despesa por centro de custo" → metric="avg", group_by="cost_center", direction="outcome" - "quanto recebi por mês esse ano" → metric="sum", group_by="month", direction="income", from_date/to_date Resposta: { metric, group_by, items: [{ group_label, transactions_count, value_in_cent (+ value_brl formatado) }] // ordenado do maior pro menor (menor→crescente se metric=min) // para metric="count", cada item traz "count" (não value_in_cent) } Reporte group_label + value_brl (ou count) VERBATIM. O 1º item é o extremo. Valores monetários são em módulo (magnitude). CRÍTICO — NÃO adicione filtro por conta própria: só mande direction se o usuário disse receita/despesa/transferência; só mande status se ele disse pago/em aberto. "qual conta tem mais lançamentos", "meu maior lançamento", "quantas transações por tipo" = SEM direction e SEM status (senão você conta/soma só um pedaço e erra). Na dúvida, omita.
cancel_transaction
ChatGPTCancela 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_transactions_batch
ChatGPTCancela 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.
categorize_transaction
ChatGPTAtribui/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 }] }
conciliate_batch
ChatGPTConcilia 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_imported_transaction
ChatGPTVincula 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 }
create_account
ChatGPTCria 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_contact
ChatGPTCria 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_cost_center
ChatGPTCria 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_credit_card
ChatGPTCria 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_plan_account
ChatGPTCria 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_recurring_transaction
ChatGPTCria 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_tags
ChatGPTCria 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_transaction
ChatGPTCria 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_from_imported
ChatGPTPara 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_transfer
ChatGPTRegistra 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.
desconciliate_imported_transaction
ChatGPTDesfaz 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 }
disable_contacts
ChatGPTDesativa (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_cost_center
ChatGPTDesativa (soft-delete) um centro de custo. Não afeta transações antigas que o usavam — apenas remove das listas ativas.
disable_plan_accounts
ChatGPTDesativa (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_tags
ChatGPTDesativa (soft-delete) uma ou mais tags. Tags desativadas continuam vinculadas a transações antigas mas não aparecem como sugestão.
generate_cashflow
ChatGPTGera 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_custom_report
ChatGPTTOOL 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 (ating…
generate_dashboard
ChatGPTSnapshot 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_dre
ChatGPTGera 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"
get_account_balance
ChatGPTRetorna saldo atual de UMA conta específica. Use quando o usuário pergunta sobre o saldo de uma conta nominal ("quanto tenho no Itaú", "saldo da poupança"). Para saldo agregado de TODAS as contas → use get_consolidated_balance (mais barato). Para movimentações detalhadas em uma janela → use get_account_statement. Resposta: - { found: true, balance: { account_id, current_balance_in_cent, as_of } } se conta existe - { found: false } se account_id não pertencer à entidade ativa OU não houver entidade ativa Valor em CENTAVOS. as_of é a data ISO 8601 do último cálculo (geralmente hoje).
get_account_statement
ChatGPTExtrato 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_accounts_all_entities
ChatGPTLista 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_consolidated_balance
ChatGPTSaldo CONSOLIDADO (soma) de todas as contas ATIVAS da entidade, com detalhamento por conta. Use quando o usuário pergunta de forma agregada: - "qual meu saldo total / geral" - "quanto tenho no caixa hoje" - "soma dos saldos das minhas contas" Mais econômico que list_accounts + N×get_account_balance — esta tool já faz a agregação. NÃO use para: - Saldo de UMA conta específica → get_account_balance - Faturas de cartão de crédito → get_credit_card_invoices Resposta: { as_of, total_current_in_cent, by_account: [{account_id, name, current_in_cent}], count_accounts }. Valores em CENTAVOS. Saldo negativo é normal (significa dívida em uma conta específica).
get_contact_summary
ChatGPTRetorna RESUMO de UM contato específico: dados cadastrais (nome, CPF/CNPJ, e-mail, telefone, tipo, papel cliente/fornecedor) + contagens agregadas (transações, NFEs emitidas). Pré-requisito: você precisa do contact_id. Se o usuário falou só o nome, use query_contacts(filter="nome") primeiro para descobrir o ID. NÃO peça o ID ao usuário — descubra você mesmo. Use quando o usuário pergunta: - "qual o resumo / dados do cliente X" - "quem é o fornecedor Y" - "quantas vezes movimentei com o contato Z" - "tenho NFE emitida pra esse cliente?" Para listar as transações/parcelas detalhadas vinculadas, use query_transactions(contact_id=<id>) ou query_payments(contact_id=<id>) DEPOIS deste. Limitação conhecida: counts.proposals sempre retorna 0 (módulo de propostas ainda não integrado). counts.transactions inclui só lançamentos ativos (status=1). counts.nfe vem da tabela tax_receipts. NÃO inclui valores totais em R$ — apenas CONTAGENS. Para o total movimentado, chame query_transactions(contact_id=X) e some os totals do lado do consumidor. Resposta: - { found: true, summary: { contact: ContactDto, counts: { transactions, nfe, proposals } } } se encontrado - { found: false } se contact_id inválido OU não pertencer à entidade ativa
get_credit_card_invoices
ChatGPTLista 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_cards_all_entities
ChatGPTLista 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_tax_receipts
ChatGPTRetorna 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_transaction
ChatGPTRetorna 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_user_permissions
ChatGPTRetorna as permissões do usuário em uma entidade específica (ou na ativa). Use quando precisar saber se uma ação está autorizada antes de tentar uma tool de write: - "posso lançar uma despesa nessa empresa?" → checa "transaction.write" - "tenho permissão pra ver relatórios?" → checa "report.generate" - "qual é meu papel nessa empresa?" → retorna role Resposta: { entity_id, entity_name, role, permissions: string[], in_scope: boolean }. - in_scope=false significa que entity_id pedido não está na sessão (sem acesso). - role é uma das: "owner", "administrator", "operator", "supervisor", "custom". - permissions é a lista de strings tipo "transaction.read", "transaction.write", "account.read", "report.generate", etc. Não exige active entity (consulta meta sobre a sessão).
ignore_imported_transaction
ChatGPTMarca 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 }
import_statement
ChatGPTForç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.
list_accounts
ChatGPTLista 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_cost_centers
ChatGPTLista 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_credit_cards
ChatGPTLista 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_nfe
ChatGPTLista 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_pending_conciliations
ChatGPTLista 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_integrations
ChatGPTLista 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_plan_accounts
ChatGPTLista 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_tags
ChatGPTLista 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_users
ChatGPTLista as PESSOAS (usuários) que têm acesso à entidade/empresa ativa — quem faz parte da equipe no Controlle. NÃO confunda com query_contacts (clientes/fornecedores): "usuários"/"pessoas da minha empresa"/"quem tem acesso" = ESTA tool. Sem argumentos — sempre escopado na entidade ativa. Resposta: { items: [{ id, name, email, phone, role }], total } Use quando o usuário pergunta: - "quais usuários tem na minha empresa?" - "quem tem acesso à conta?" - "lista as pessoas cadastradas"
pay_credit_card_invoice
ChatGPTRegistra o pagamento de uma fatura de cartão. Use quando o usuário pede: - "paguei a fatura do Nubank com o Itaú" - "marca pagamento da fatura X de R$ 1.234 hoje" Fluxo: 1. get_credit_card_invoices → identifica a fatura (status="open") e pega invoice_id. 2. list_accounts → conta de pagamento (source_account_id). 3. pay_credit_card_invoice com invoice_id + value_in_cent + dt_payment + source_account_id. Suporta pagamento parcial (value_in_cent < value da fatura), e pagamento com outro cartão (source_credit_card_id em vez de source_account_id). Resposta: { invoice_id, payment_id, value_in_cent, dt_payment, source_account_id, source_credit_card_id }.
pay_transaction
ChatGPTRegistra o pagamento de UMA PARCELA (transaction_payment) de um lançamento. IMPORTANTE: a tool opera sobre PARCELAS individuais, não sobre a transação inteira. Use o id retornado por query_payments (items[].id) ou get_transaction (payments[].id). Fluxo recomendado: 1. query_payments(state="overdue") → lista parcelas em aberto 2. Identifica a parcela alvo (payment_id) e a conta de pagamento (account_id de list_accounts) 3. pay_transaction(payment_id, account_id, dt_billing, value_paid_in_cent?) Regras: - Apportionments (plano de contas + centro de custo) são PRESERVADOS automaticamente da parcela original. - Se value_paid_in_cent < value_in_cent original → status fica "paid_partial". - Se >= → status "paid". - Cobranças automáticas (billing) NÃO podem ser pagas manualmente. SEGURANÇA: o payment_id vem de query_payments/get_transaction — nunca invente. Passe expected_value_in_cent com o valor que o usuário disse; se não bater com a parcela real, a tool RECUSA e não paga nada. Ao confirmar, use description/paid_in_cent QUE VIERAM NA RESPOSTA — nunca invente. Resposta: { payment_id, transaction_id, status, paid_in_cent, dt_billing, account_id, description // descrição REAL do lançamento pago — reporte esta } Use quando o usuário pede: - "paga essa conta agora" - "marca essa parcela como paga, pelo Nubank, hoje" - "registra o pagamento de R$ 500 dessa fatura"
query_contacts
ChatGPTLista CONTATOS (clientes/fornecedores) da entidade ativa, com filtros opcionais. REGRA CRÍTICA DO filter: só passe filter quando o usuário DIGITOU um nome/termo específico de contato. É PROIBIDO INVENTAR um filter (ex.: passar filter="João" quando o usuário só pediu "meus contatos" ou "meus clientes") — isso zera a lista à toa. Para "meus contatos / meus clientes / meus fornecedores / listar contatos" → NÃO passe filter (use só role, ou nada). Só use filter com o texto EXATO que o usuário escreveu. Use quando o usuário pergunta: - "meus contatos" / "liste contatos" → SEM args (nenhum filter) - "meus clientes" / "lista de clientes" → role="client" (SEM filter) - "meus fornecedores" / "fornecedores" → role="supplier" (SEM filter) - "quem é o João Silva?" (usuário DIGITOU o nome) → filter="João Silva" - "fornecedores inativos" → role="supplier", active=false - "próxima página" → page=2 (mantenha demais filtros) Para detalhes financeiros de UM contato (totais movimentados, contagens), use get_contact_summary depois de encontrar o ID aqui. Resposta: { items: ContactDto[], page, page_size }. Paginação fixa em 30 itens. Se a entidade tiver muitos contatos, mostre os 30 e ofereça filtrar por nome/role na sequência — mas só após a primeira chamada. Campos importantes do ContactDto: - id: ID numérico do contato (use em outras tools como contact_id) - type: "physical" (PF) ou "legal" (PJ) - client/supplier: booleanos indicando papel - cpf_cnpj: documento (string) - active: derivado de situation === 1
query_credit_card_transactions
ChatGPTLista LANÇAMENTOS/COMPRAS de cartão de crédito (linhas de credit_card_transaction), com valor, descrição, competência, fatura e contato. Diferença das outras tools: - query_credit_card_transactions = compras individuais no cartão (esta). - get_credit_card_invoices = faturas mensais agregadas. - query_transactions / query_payments = lançamentos comuns (não cartão). Use quando o usuário pergunta: - "o que comprei no cartão X" - "lançamentos da fatura de maio" → invoice_id ou from_date/to_date - "compras no cartão entre datas" Resposta: { items: CreditCardTransactionDto[], total, page, page_size }. value_in_cent em CENTAVOS (soma dos rateios/apportionments). activity_type: "OUTCOME" (compra) ou "INCOME" (estorno). is_conciled indica se já foi conciliado com extrato.
query_payments
ChatGPTLista PARCELAS (linha da tabela transactions_payments) da entidade ativa. Uma parcela é uma cobrança/título individual derivada de um lançamento — um lançamento parcelado em 12x vira 12 parcelas, cada uma com seu próprio vencimento e situação. Use esta tool quando o usuário pergunta sobre: - "tenho contas a pagar em [período]? / o que tenho a pagar" → state="open" com from_date/to_date (traz TODAS em aberto). NÃO use "due_soon" (perde as que vencem depois de 7 dias) nem "all" (traz pagas/saldo inicial). - "contas vencidas / o que venceu / tenho vencidos?" → state="overdue" SEM direction — traz a PAGAR E a RECEBER vencidas (os dois sentidos). Separe na resposta pelo campo direction (a pagar x a receber); transferências (direction="transfer") NÃO são contas — mencione à parte ou ignore. Só passe direction="income"/"outcome" se o usuário pedir um lado só. - "vencimentos próximos / a vencer essa semana" → state="due_soon" - "parcelas pagas / contas quitadas" → state="paid" - "todas as parcelas de [período]" → state="all" com from_date/to_date NÃO use para: - Saldos consolidados → use get_consolidated_balance - Histórico de lançamentos (não parcelas) → use query_transactions - Pagamentos via PSP (Asaas, Pix) → outra tool Resposta: - items: PaymentDto[] — apenas a página corrente. - total: número TOTAL de parcelas que casam o filtro (não só na página). Compare items.length vs total pra saber se há mais. Pagine com page/limit. - page, page_size. Tipos: todos os _in_cent são number em CENTAVOS (divida por 100 pra reais). dt_due/dt_billing em YYYY-MM-DD (use pra mostrar o vencimento — NÃO deixe "—"). ds_transaction é a descrição do lançamento pai. Campo direction: "income" (a receber) / "outcome" (a pagar) / "transfer". activity_type: 0=saída, 1=entrada. CONTATO: cada item traz contact_name (cliente/fornecedor vinculado) e contact_id — use direto pra montar a coluna Cliente/Fornecedor; se contact_name for null, não há contato vinculado (escreva "—", não invente). NÃO use generate_custom_report só pra pegar o cliente das parcelas — já vem aqui. Ordenação: state='paid' → mais recente primeiro (dt_due DESC). Demais → mais ANTIGO primeiro* (overdue = a mais vencida em cima). NÃO chame o topo de "mais recentes" — em overdue é o MAIS vencido. "mais recentes" (por criação) é query_transactions, não aqui. CONTAGEM: total conta PARCELAS (inclui as 2 pernas de cada transferência). Se for reportar "N vencidos", desconte as transferências (direction="transfer") pra bater com o número de CONTAS do sistema.
query_recurrences
ChatGPTLista RECORRÊNCIAS (transactions_recurrences) da entidade ativa. Uma recorrência é a regra mãe que gera lançamentos repetidos (assinaturas, contratos fixos, aluguel mensal, parcelamentos, etc.) — distinta dos lançamentos individuais que ela cria. Use quando o usuário pergunta: - "quais minhas assinaturas / contratos fixos / despesas recorrentes" → active=true - "recorrências canceladas / encerradas" → active=false - "lista de tudo que é recorrente" NÃO confunda com: - query_payments → parcelas individuais (ex.: parcela 3/12 de "Internet") - query_transactions → lançamentos individuais (também ex.: o lançamento 3/12 de "Internet") A recorrência é o "molde"; a parcela/lançamento é a "instância". Resposta: - items: RecurrenceDto[] — página corrente. - total: número TOTAL de recorrências que casam o filtro (não só na página). Use page/limit pra paginar. - page, page_size. Campos: - "active": boolean derivado de status (1=ativa, 0=encerrada). - "rule" (int): periodicidade — 0=DIAS, 1=SEMANAS, 2=MESES, 3=ANOS, 4=QUINZENAS, 5=BIMESTRAL, 6=TRIMESTRAL, 7=SEMESTRAL. - "type" (int): 0=PARCELADO (installments), 1=FIXO, 2=À VISTA. - "qtd_difference_dates": intervalo entre repetições (ex.: rule=2 meses + qtd=1 → mensal). - "total_recurrence": número total de repetições da regra.
query_transactions
ChatGPTLista lançamentos financeiros (transactions) da entidade ativa. Use esta tool para perguntas amplas sobre histórico financeiro, despesas/receitas por período, ou busca por descrição/contato/conta. REGRA DE FILTROS: por padrão, chame SEM filtros (apenas limit) — traz TODOS os lançamentos, os MAIS RECÉM-CRIADOS primeiro (ordem = data de criação desc). TODOS os campos (status, from_date, to_date, type, text, contact_id, account_id) são OPCIONAIS; só envie um filtro quando o usuário PEDIR aquilo. Ex.: "minhas transações"/"últimos lançamentos" ⇒ NENHUM filtro. NUNCA adicione status por conta própria — nem "paid" (esconde os em aberto/recém-criados) nem "open" (esconde os já pagos). "despesas de julho"/"quanto gastei" traz TODAS (pagas E em aberto); só filtre status se o usuário disser a situação ("pagas", "em aberto"). from_date/to_date SÓ quando o usuário citar período; type SÓ se ele disser despesa/receita/transferência. LOCALIZAR UM LANÇAMENTO ESPECÍFICO (ex.: pra cancelar/pagar/editar "a despesa de gasolina", "o lançamento X"): filtre por text=<a descrição que o usuário citou> (busca ILIKE na descrição). NÃO traga a lista inteira e fique procurando na mão — use o text. Se vier vazio, diga que não achou e peça mais detalhe; NÃO chute um id de outro lançamento. Diferença vs. tools relacionadas: - query_payments — use quando o usuário pergunta sobre PARCELAS específicas (vencidas, a vencer, pagas). Um lançamento pode ter várias parcelas. - get_transaction — use quando o usuário já sabe o ID/UUID de um lançamento e quer o detalhe. Resposta: - items: TransactionDto[] — página corrente, enriquecida. Para montar listagem/detalhe use SEMPRE estes campos (não invente nem pegue de outro lugar): • CONTA usada = account.name (nome da conta bancária) ou credit_card.name se for cartão. NUNCA use o nome da categoria (que está em items[].plan_account_name) como conta — são coisas diferentes. • DATA = dt_competence (YYYY-MM-DD). Vencimento = dt_due (1ª parcela). Se null, diga "sem data", não invente. • STATUS = payment_status: "open"=em aberto, "paid"=pago, "partial"=parcial. Use ESTE — NUNCA assuma "pago". Não confunda com status (esse é ativo/inativo do registro). • CATEGORIA(S) = items[].plan_account_name. Se houver 2+ itens, é RATEIO entre categorias (rotule como "Rateio de categorias", não "detalhes dos itens"). • obs_transaction = observação (pode ser null). attachments_count = nº de anexos (se >0, HÁ anexos — não diga que não tem). is_recurring=true → lançamento fixo/recorrente. - total: número TOTAL de lançamentos que casam o filtro (não só na página). Compare items.length vs total pra saber se há mais; pagine com page/limit. - page, page_size. Tipos: total_amount_in_cent é number em CENTAVOS (divida por 100). dt_competence/dt_due são YYYY-MM-DD. activity_type: 0=saída, 1=entrada. type: 0=lançamento, 1=transferência. Exemplos: - "gastos de maio" → from_date="2026-05-01", to_date="2026-05-31", type="expense" - "receitas pagas este ano" → NÃO use status aqui; use query_payments(state="paid") (ou traga todas as receitas do ano com from_date/to_date/type="income" e veja a situação de cada uma no resultado) - "transferências da semana" → from_date e to_date da semana corrente, type="transfer"
rank_contacts
ChatGPTRanking de contatos pelo VALOR total movimentado, já agregado e ordenado do maior pro menor. Use SEMPRE que a pergunta for sobre o "maior/top" contato por valor — NÃO traga query_transactions e tente rankear de cabeça (você erra). Use quando o usuário pergunta: - "de quem eu mais recebo?" → direction="income" - "meu maior cliente / top 5 clientes (por valor)" → direction="income", role="client" - "pra quem eu mais pago / meu maior fornecedor" → direction="outcome" (role="supplier" se quiser só fornecedores) - "quem mais me pagou em 2025" → direction="income", from_date/to_date do ano Por padrão ranqueia pelo valor RECEBIDO/PAGO de fato (só parcelas baixadas) — é o que "top clientes"/"de quem mais recebo" quer dizer. Passe only_paid=false apenas se pedirem faturado/contratado. Resposta: { direction, metric, // "received" (pago/recebido) ou "invoiced" (faturado) items: [{ contact_id, contact_name, total_in_cent (+ total_brl já formatado), transactions_count }] // ordenado por total desc } Reporte contact_name e total_brl verbatim; o 1º item é o maior. Se metric="received", deixe claro que é o valor RECEBIDO/PAGO (não o faturado). Só considera lançamentos com contato vinculado (id_contacts) e exclui transferências.
suggest_conciliation_match
ChatGPTSugere candidatos de match para UMA imported_transaction pendente. Replica o algoritmo do banking-integration: busca em transactions reais (com payments) pela mesma conta, valor ±10 centavos, data ±1 dia e activity_type compatível (entrada/saída). Use depois de list_pending_conciliations, passando o id da pendente que você quer conciliar. Algoritmo: 1. Localiza a imported_transaction e extrai (valor, data, account, activity_type) 2. Busca transactions WHERE id_entity = active AND status=1 AND situation IN (PENDING, PAID) AND activity_type bate AND mesma conta AND valor±10c AND data±1d 3. Ordena por diff_in_days ASC, depois diff_in_cents ASC 4. Retorna top N (default 10) Resposta: { imported: ImportedTransactionDto | null, candidates: CandidateMatchDto[] } - imported=null se id inválido ou fora da entidade - candidates vazio se nenhum match dentro do threshold Cada candidato traz: transaction_id, ds_transaction, total_amount_in_cent, dt_competence, activity_type, diff_in_days (proximidade temporal), diff_in_cents (proximidade de valor), id_accounts_main. Apresente os top 3 ao usuário com diff destacado. Esta tool NÃO executa o match — só sugere. Para fazer a conciliação efetiva, será necessária uma write tool futura (não disponível ainda).
switch_entity
ChatGPTTroca a entidade ativa da sessão MCP. Use quando o usuário pede: - "muda pra empresa X" / "quero ver os dados da entidade Y" - após who_am_i quando o usuário escolhe entre as disponíveis Importante: - O entity_id DEVE existir em available_entities (use who_am_i pra confirmar). - A operação rotaciona o mcp-session-token: a resposta traz um novo token que deve substituir o atual. Para clientes que mantêm token na conexão (caso comum), basta passar a usar o token novo nas próximas chamadas; o servidor MCP aceita os dois durante a TTL do antigo. Resposta: { active_entity_id, token, expires_in }. expires_in em segundos (15min default).
unpay_transaction
ChatGPTDesfaz o pagamento (baixa) de UMA PARCELA — volta ela para EM ABERTO/pendente, zera a conta paga/valores/data e reverte o efeito no saldo. É o INVERSO de pay_transaction. Use SEMPRE que o usuário quiser "marcar como não pago", "desfazer o pagamento", "estornar a baixa", "reabrir a parcela", "marcar como em aberto". NÃO use cancel_transaction pra isso — cancelar EXCLUI o lançamento; aqui só se desfaz o pagamento, mantendo o lançamento. Identificação da parcela: passe payment_id (preferido, de query_payments/get_transaction) OU transaction_id (parcela única). Se o usuário se referir a "o item N" de uma lista, isso é a POSIÇÃO na lista — use o id REAL daquele item, NUNCA o número N como id. SEGURANÇA: passe expected_value_in_cent com o valor que o usuário disse; se não bater com a parcela real, a tool RECUSA e não altera nada. Cobranças automáticas (BILLING) não podem ser desfeitas. Ao confirmar, use description/value_in_cent QUE VIERAM NA RESPOSTA — nunca invente. Resposta: { payment_id, transaction_id, already_unpaid, status, description, value_in_cent } (already_unpaid=true → já estava em aberto, nada mudou.) Use quando o usuário pede: - "marca esse lançamento como não pago" - "desfaz o pagamento dessa parcela" - "estorna a baixa dessa conta"
update_contact
ChatGPTEdita um contato existente. Passe apenas os campos que quer alterar. Mantém o id original.
update_cost_center
ChatGPTEdita nome e/ou pai de um centro de custo existente.
update_plan_account
ChatGPTEdita uma categoria existente. Passe apenas os campos que quer alterar. Cuidado ao mudar movement — pode quebrar relatórios já calculados.
update_tag
ChatGPTRenomeia uma tag existente. Use list_tags para descobrir o tag_id.
update_transaction
ChatGPTAtualiza campos básicos de uma transação existente: descrição, data de competência, data de VENCIMENTO (dt_due, parcela única), observações, contato vinculado. LIMITAÇÕES desta versão (v1): - NÃO altera valor (use o app web). - Vencimento (dt_due): só para lançamento de PARCELA ÚNICA (parcelamento é recusado). - NÃO altera apportionments (plano de contas / centro de custo) — use categorize_transaction. - NÃO altera conta de origem/destino. Para categorizar (plano de contas, centro de custo), use categorize_transaction. Pelo menos um campo deve ser passado. Omitir = manter. null em obs_transaction/contact_id = limpar. Resposta: { id, ds_transaction, dt_competence, obs_transaction, id_contacts, dt_updated_at } Use quando o usuário pede: - "muda a descrição dessa transação pra X" - "essa transação é do mês passado, ajusta a data de competência" - "vincula o fornecedor X a essa transação"
who_am_i
ChatGPTRetorna identidade do usuário autenticado e contexto da sessão MCP corrente: user_id, canal (web/whatsapp/telegram/partners-api/internal), entidade ativa e lista de entidades acessíveis. Use no início de uma conversa para confirmar contexto ou quando o usuário pergunta: - "quem está logado / quem sou eu" - "em qual empresa estou" - "quais empresas tenho acesso" Sempre chame esta tool ANTES de qualquer ação que assume contexto se a sessão for nova ou se o usuário sinalizou ambiguidade. Resposta: { user_id, channel, external_user_id, active_entity_id, available_entities: [{ entity_id, name, role }] }. Não exige active entity (é a tool que descobre se há uma).
cancel_transaction
Claudecategorize_transaction
Claudeconciliate_imported_transaction
Claudecreate_account
Claudecreate_contact
Claudecreate_cost_center
Claudecreate_credit_card
Claudecreate_plan_account
Claudecreate_recurring_transaction
Claudecreate_tags
Claudecreate_transaction
Claudecreate_transfer
Claudedesconciliate_imported_transaction
Claudedisable_contacts
Claudedisable_cost_center
Claudedisable_plan_accounts
Claudedisable_tags
Claudeexport_report
Claudegenerate_cashflow
Claudegenerate_custom_report
Claudegenerate_dashboard
Claudegenerate_dre
Claudeget_account_balance
Claudeget_account_statement
Claudeget_accounts_all_entities
Claudeget_consolidated_balance
Claudeget_contact_summary
Claudeget_credit_card_invoices
Claudeget_credit_cards_all_entities
Claudeget_tax_receipts
Claudeget_transaction
Claudeget_user_permissions
Claudeignore_imported_transaction
Claudeimport_statement
Claudelist_accounts
Claudelist_cost_centers
Claudelist_credit_cards
Claudelist_nfe
Claudelist_pending_conciliations
Claudelist_pending_integrations
Claudelist_plan_accounts
Claudelist_tags
Claudepay_credit_card_invoice
Claudepay_transaction
Claudequery_contacts
Claudequery_credit_card_transactions
Claudequery_payments
Claudequery_recurrences
Claudequery_transactions
Claudesuggest_conciliation_match
Claudeswitch_entity
Claudeupdate_contact
Claudeupdate_cost_center
Claudeupdate_plan_account
Claudeupdate_tag
Claudeupdate_transaction
Claudewho_am_i
Claude
