io.github.paivapiovesan/next-finance

CORRIGE os ITENS de um documento recebido JÁ cadastrado — troca a lista de produtos (DespesaServProd) preservando total, fornecedor, classificação, pagamento e parcelas. Use para DETALHAR uma NFC-e que entrou como resumo (ex.: '65 itens conforme a nota') com os itens produto a produto. O total NÃO muda (a soma dos itens tem que bater com o total do documento — não afeta o saldo). Localiza pelo 'numero' (+ 'fornecedor').

Edita um lançamento existente. Localiza pelo nome_conta + data + valor/descrição (varre TODAS as contas homônimas, inclusive em moedas diferentes — ex: as várias 'Conta a Pagar') e aplica as alterações. Se mais de um lançamento bater, a tool lista as opções para você refinar (use 'moeda' para desambiguar).

Edita VÁRIOS lançamentos DE UMA VEZ — resolve o caso de N lançamentos IDÊNTICOS (mesma data/valor/descrição) que a edição individual recusa por não conseguir distinguir. Localiza TODOS os que batem os critérios (conta + data ou período + valor/descrição/cliente) e aplica a MESMA mudança a cada um (descrição, contato, plano, centro, observações, nº doc). Caso típico: transferir todos os lançamentos de uma descrição errada para a correta, vinculando ao cadastro certo (ex.: 'Lara Assis' → 'Lara Ribeiro'). Fluxo em 2 passos: confirmar=false devolve a CONTAGEM e uma amostra; após o 'ok', confirmar=true aplica a todos. Ignora transferências. Só age em contas com permissão de edição.

Envia o E-MAIL DE COBRANÇA de um título que está em 'Contas em Cobrança' (reproduz o botão 'Enviar Email de Cobrança' da tela). Usa o padrão 'Email de Cobrança' + AWS SES configurados na carteira e envia para o e-mail do cliente cadastrado. O título precisa ESTAR em cobrança — mova antes com enviar_para_cobranca. Localiza o título pelo cliente (contraparte) + vencimento (+ valor). Confirme com o usuário antes de disparar.

Move um título A RECEBER não recebido para 'Contas em Cobrança' (reclassificação, sem emitir boleto). Localiza o título pelo cliente (contraparte) + vencimento (+ valor). Se houver mais de uma conta de cobrança, informe conta_cobranca.

EXCLUI um contato DEFINITIVAMENTE (irreversível). É a ferramenta de DEDUPLICAÇÃO: com manter_um=true, quando o nome tem cadastros repetidos, MANTÉM 1 e exclui os demais. Por nome só age em alvo único; para um duplicado específico, informe o id. SEMPRE roda em 2 passos: primeiro sem confirmar (mostra quantos serão excluídos) e, após o 'ok' do usuário, com confirmar=true. Obs.: o NEXT recusa nomes DUPLICADOS ao atualizar — se um contato der erro 'já existe pessoa com mesmo nome', é sinal de duplicata: deduplique aqui antes de renomear/normalizar.

Exclui um lançamento existente. Localiza pelo trio (nome_conta + data + valor/descrição). Se mais de um lançamento bater os critérios, a tool lista as opções para você refinar. AÇÃO IRREVERSÍVEL.

Finaliza (executa) a conciliação de uma conta via Concluir — aplica os lançamentos do extrato na conta. AÇÃO IRREVERSÍVEL. Requer permissão de edição. Rode 'associar_conciliacao' antes. Pode levar mais de 1 minuto. Os lançamentos novos podem ficar SEM classificação — use editar_lancamento depois.

Gera o FATURAMENTO do contrato (emite os documentos das parcelas) — NEXT `GerarFaturamento`. Ação SEPARADA do reajuste e do 'Criar Parcelas'. Use só quando o usuário pedir para faturar/emitir.

Importa contatos EM LOTE de um arquivo .VCF (vCard) OU .CSV (Google Contacts) — auto-detecta o formato. Rápido (uma chamada por lote via FisicaLote), preservando nome, e-mail, telefone/celular e endereço. PULA DUPLICADOS pelo nome (contra os já cadastrados), então dá para RETOMAR de onde parou (é só rodar de novo). Fluxo: confirmar=false para a PRÉVIA (quantos novos vs já cadastrados) e, após o 'ok', confirmar=true para gravar. Informe a 'classe' a aplicar a todos. Use 'limite' para importar em partes.

Importa documento(s) fiscal(is) recebido(s) por XML no NEXT Business (Compras & Despesas → Documentos Recebidos): NF-e, NFC-e ou NFS-e. O NEXT parseia o XML e cria o documento. Informe 'caminho_arquivo' (um XML local), 'diretorio' (importa TODOS os .xml da pasta, em lote), ou 'conteudo_base64' + 'nome_arquivo'. CLASSIFICAÇÃO (só para UM arquivo): para o documento já sair lançado no Finance, informe 'conta_pagamento' (conta/cartão), e se for o caso 'parcelas' + 'primeiro_vencimento', além de 'plano_de_contas' e 'centro_de_custo'. Se o usuário NÃO disse onde/como pagar nem a classificação, PERGUNTE antes (conta/cartão, à vista ou parcelado + 1º vencimento, plano de contas, centro de custo) — não invente.

Puxa o extrato de uma conta pela CONEXÃO DIRETA do banco (o 'Conexão Banco API' da tela Conciliar Extrato) — distinto do Open Finance. Bancos suportados: Inter (PJ), BTG, Banco Original. Traz as transações do período para a conciliação pendente e as LISTA, mas NÃO concilia nada — a conciliação é feita depois na tela do NEXT ou com detalhar_conciliacao/associar_conciliacao/executar_conciliacao. Período padrão: últimos 30 dias.

Abre uma janela local no navegador com o widget Pluggy Connect para autenticar uma conta Open Finance que exige MFA (ex: Inter, que pede leitura de QR Code no Super App). Após o usuário concluir a autenticação, a janela fecha sozinha e a conta fica pronta para 'obter_extrato_open_finance'.

Retorna UM insight/dica curto e personalizado sobre a carteira (vencimento/pendência/oportunidade/observação), para a SofIA ABRIR a conversa proativamente. Chame na PRIMEIRA interação de uma conversa, antes de esperar a pergunta do cliente, e apresente o insight de forma curta e acolhedora.

Lista os arquivos anexados a um lançamento (nome, extensão, tamanho, URL). Localiza pelo trio (nome_conta + data + valor/descrição).

Lista todas as carteiras disponíveis para o usuário logado.

Lista os centros de custo da carteira. Use para descobrir nomes exatos antes de filtrar lançamentos por centro de custo.

Lista as Classes de Cadastro (Tags) disponíveis para classificar um contato — ex: 'Clientes e Empregadores', 'Fornecedores', 'Correntista'. A classe é OBRIGATÓRIA ao criar um contato (criar_contato). Use antes de criar_contato para escolher a classe correta.

Lista os CLIENTES da carteira (quem tem títulos a receber), ordenados pelo valor a receber. Cada cliente traz: nome, tipo (PF/PJ), quantidade de títulos, valor a receber e valor vencido. Retorna também o total_a_receber da carteira. Use busca para filtrar por nome. Para a ficha cadastral completa de um cliente (CPF/CNPJ, endereço, etc.) use buscar_contato; para registrar uma tratativa/cobrança use criar_registro_relacionamento.

Lista as conciliações bancárias em andamento na carteira (criadas por extrato Open Finance ou importação de arquivo). Mostra conta, banco, número de transações e período. Use antes de executar/detalhar uma conciliação.

Lista as contas ativas da carteira selecionada. As contas seguem hierarquia de 4 níveis: Moeda → Portfolio → Tipo de Conta → Conta. Portfolios: Liquidez, Previdência, Renda Fixa, Renda Variável, Tesouraria. Use os filtros para navegar nessa hierarquia.

RÁPIDO e DIRETO: lista SÓ as contas correntes da carteira, com campos mínimos (nome, banco, agência, conta, permissão e saldo de hoje). Use esta tool quando o usuário pedir 'minhas contas correntes' / 'saldo das contas' — NÃO use listar_contas (que traz a árvore inteira de centenas de contas) nem nada de Open Finance/extrato/conciliação para isso. Uma única consulta ao cadastro interno + uma consulta de saldo em lote. Passe incluir_saldo=false para a resposta mais rápida possível (sem o saldo do dia).

Lista as contas bancárias trazidas por uma conexão Open Finance de uma conta (para associar). Retorna cada conta OF com id e descrição — use o id em associar_conta_open_finance.

Lista as contas da carteira que possuem vínculo Open Finance ativo (integração via Pluggy/OF). Retorna nome da conta, banco, tipo e se exige MFA. Não chama a API REST — usa os dados de cadastro da conta diretamente.

Lista contatos com CELULAR e E-MAIL — para agenda, exportação e relatórios em massa. Diferente de buscar_contato (que resolve UM contato para a ficha completa), esta tool retorna uma lista paginada: nome, tipo, cidade/UF, celular, e-mail e telefone. IMPORTANTE (PJ): numa pessoa jurídica os telefones/celulares das pessoas ficam nas PESSOAS DE CONTATO dentro do cadastro (ex.: na Jaymar — Adriana, Marlene…). Por padrão (incluir_pessoas=true) cada PJ é expandida: além da linha da empresa, vem uma linha por pessoa de contato (tipo 'Contato', com 'empresa' = razão social e 'cargo'). Use incluir_pessoas=false para só as linhas da empresa. Filtros: filtro_nome (casa nome OU empresa), filtro_email, filtro_celular (casam por trecho), tem_celular / tem_email (só quem tem), tipo ('PF'/'PJ'). Paginação: pagina (1-based) e limite (padrão 30, máx 100) — o limite conta as pessoas/empresas da BASE; com expansão, o total de linhas retornadas pode ser maior. Filtros são aplicados após buscar o detalhe, então uma página pode vir com menos itens — pagine até tem_mais=false. Para 'todos os contatos da empresa X' também funciona buscar_contato('X') (a ficha da PJ traz o array 'contatos').

Lista os contratos (NEXT Business → Receitas & Operações → Contratos) da carteira. Use 'pessoa' para filtrar por cliente. Traz número, cliente, valor, situação, período de reajuste e o índice detectado no texto do contrato.

Lista os DOCUMENTOS EMITIDOS (faturamento / vendas — NEXT Business → Receitas & Operações → Documentos Emitidos): cada documento com data, cliente, tipo (ex.: 'NFSe Nacional'), valor e situação. Já vem com AGREGADOS: total, por mês, por tipo, por situação, top clientes, e POR ITEM da nota (VendaServico: descrição/código do serviço, qtd, valor) — dado CRU (a categorização de produtos é específica de cada carteira, fica a cargo de quem consome). EXCLUI os CANCELADOS por padrão. Período padrão: do 1º de janeiro do ano até hoje. Use resumo_apenas=true para trazer só os agregados (sem a lista).

Lista os DOCUMENTOS RECEBIDOS (NF-e da SEFAZ, bandeja a importar) e SINALIZA os RECORRENTES — casa o emitente com uma despesa periódica cadastrada. Cada documento traz: fornecedor, data, valor, nsu, importada e o flag 'recorrente' (com a referência da despesa periódica e o ALERTA de diferença de valor: 'a previsão era R$X e o documento chegou R$Y'). Use para priorizar/avisar as contas recorrentes que chegaram. apenas_nao_importadas=true mostra só as pendentes; apenas_recorrentes=true só as recorrentes.

Lista os CLIENTES INADIMPLENTES — contas a receber VENCIDAS agregadas por cliente (inclui as já em 'Contas em Cobrança'). Cada cliente traz: total_vencido, nº de títulos, vencimento_mais_antigo, dias_atraso_max, faixa de aging (1-30/31-60/61-90/90+), quanto já está em cobrança e o CONTATO para cobrar (celular/e-mail; em PJ, os contatos internos). Ordenado pelo maior valor em atraso. Retorna totais_por_moeda (nunca soma moedas diferentes). Use para saber quem cobrar e como falar — e depois enviar_para_cobranca / enviar_email_cobranca.

Lista os MODELOS de proposta cadastrados (Business → Propostas). Use ANTES de criar_proposta para perguntar ao usuário se ele quer usar um modelo (o modelo preenche os textos de Introdução, Validade, Condição, etc.).

Lista as moedas disponíveis no NEXT Finance (ex: BRL, USD, EUR). Use 'busca' para filtrar por nome, sigla ou símbolo.

AUDITORIA: lista as Pessoas Jurídicas com o campo CNPJ Raiz VAZIO e sugere a raiz correta a partir dos estabelecimentos — só sugere quando TODOS os estabelecimentos compartilham a mesma raiz (regra segura). Separa em 'corrigíveis automaticamente' e 'não automáticos' (raízes diferentes ou sem CNPJ). Somente leitura. Depois use corrigir_cnpj_raiz para preencher.

Lista o plano de contas da carteira — categorias de DESPESA E RECEITA (cada item traz o 'tipo'). Retorna por_tipo com a contagem de despesa/receita. Use tipo='despesa' ou 'receita' para focar num lado. Use para descobrir os nomes exatos das categorias antes de classificar/buscar lançamentos por plano de contas.

Lista os tipos de conta disponíveis (corrente, poupança, cartão, investimento etc.).

Abre uma janela no browser para login seguro no NEXT Finance. As credenciais não passam pelo chat. Se já houver sessão salva, restaura automaticamente sem abrir o browser.

Encerra a sessão e remove os dados de sessão salvos.

Varre a carteira INTEIRA e normaliza os CELULARES fora do padrão BR (+55, 0 do DDD, prefixo espúrio → últimos 11 díg.). Fluxo: confirmar=false para a PRÉVIA (quantos a corrigir, casos ambíguos e amostra de/para) e, após o 'ok', confirmar=true para corrigir. A API do NEXT não tem batch de telefone, então corrige em SEQUÊNCIA (lenta, ~6-20s por contato) — use 'limite' para ir em partes; é RETOMÁVEL (roda de novo e pula os já normalizados) e renova o token no meio. Devolve alterados, ignorados (ambíguos) e falhas com nomes. incluir_telefone=true também normaliza o campo Telefone.

Solicita ao banco (via Open Finance) o extrato de uma conta no período. Diferente de 'atualizar_open_finance' (que só pega o mais recente), permite especificar um intervalo de datas. Default: últimos 30 dias. Após sucesso, a conciliação fica pendente no NEXT — finalize no app para os lançamentos aparecerem em 'buscar_lancamentos'.

Verifica a permissão do usuário logado sobre uma conta. Retorna 'Negar' (oculta), 'Ver' (somente leitura) ou 'Editar' (acesso total). O MCP respeita essas permissões automaticamente: contas 'Negar' não aparecem em listagens, e tentativas de criar/editar/excluir lançamento em conta 'Ver' são rejeitadas.

APLICA o reajuste do contrato E cria o novo ciclo de parcelas (grava tudo via API). Faz o procedimento completo da tela: (1) atualiza o VALOR e os valores dos serviços pelo índice acumulado (IPCA/IGPM, BCB, 12 meses até o último mês fechado); (2) MANTÉM todas as parcelas existentes nos valores originais; (3) CRIA as 12 novas parcelas no valor reajustado, do mês seguinte à última; (4) avança a Validade (+12) e a Data Fim (+12 meses); (5) acrescenta a nota padrão. Ao final avisa quantas parcelas foram criadas e no valor novo. Confirme o valor novo com o usuário antes de chamar. O índice vem do texto do contrato (ou de 'indice').

Reinicia uma conciliação em andamento (descarta o progresso e re-busca os lançamentos do extrato). Útil quando algo deu errado na conciliação atual.

Remove um ou mais anexos de um lançamento. Localiza pelo trio (nome_conta + data + valor/descrição) e remove os arquivos por nome COM extensão (ex: 'boleto.pdf'). Use 'listar_anexos_lancamento' para ver os nomes exatos.

Resumo de gastos/receitas numa categoria do plano de contas — responde 'quanto gastei com Restaurantes em maio?'. Retorna total de despesas/receitas/saldo do período, breakdown por mês, por conta, por centro de custo e top 15 descrições. Período default: últimos 30 dias.

Resumo de gastos/receitas num centro de custo — responde 'despesas e receitas do CC Pedro Tobias?'. Retorna total de despesas/receitas/saldo, breakdown por mês, por plano de contas, por conta e top 15 descrições. Período default: últimos 30 dias.

Snapshot completo de saldos da carteira numa data (default: hoje), agrupado em árvore Moeda → Portfolio → Tipo de Conta → Conta. Equivale à tela 'Outras Contas' do NEXT Finance. Mostra patrimônio total por moeda (BRL, USD, EUR, etc.) e breakdown por categoria (Renda Fixa, Renda Variável, Tesouraria, Liquidez, Previdência).

Seleciona uma carteira pelo nome (necessário antes de listar contas e lançamentos). Use listar_carteiras para ver os nomes disponíveis.

Use SOMENTE para BOLETO SEM NOTA de uma despesa recorrente. ATUALIZA a PREVISÃO existente em Contas a Pagar (vira título real com a linha digitável, valor e vencimento do boleto) em vez de criar um lançamento novo — evita DUPLICAR o valor. SEMPRE avisa a diferença de valor (previsão estimada vs boleto real). Localiza a previsão pelo fornecedor + competência (mês do vencimento do boleto). Fluxo: confirmar=false para a PRÉVIA (com o alerta de valor) → após o 'ok', confirmar=true para gravar. IMPORTANTE: se a conta VEIO COM NOTA FISCAL (energia, água, telefonia, NF-e), NÃO use este tool — use cadastrar_documento_recebido (o documento no Business gera a transação vinculada) e avise a diferença de valor. Se não achar a previsão, avisa.

Histórico de preços de um produto — responde 'qual o último preço que paguei pelo produto X?'. Por padrão retorna 1 linha por fornecedor com a compra mais recente, ordenado por data desc. Use 'agrupar_por_fornecedor=false' para listar TODAS as compras. Período default: últimos 12 meses. Fonte: NEXT Business (NFCe/NF-e + cadastro de produtos).

Verifica se uma conta específica tem vínculo Open Finance configurado e se exige MFA. Usa dados de cadastro (offline).

Retorna a versão da SofIA (NEXT Finance MCP) e informações do servidor. Use quando o usuário perguntar qual a versão da SofIA/MCP — funciona em qualquer cliente (Claude, ChatGPT, Codex).