io.github.paivapiovesan/next-finance

Cria um item de AGENDA (agendamento/lembrete com data, hora e responsável) em um registro da Central de Relacionamento (CRM). Localiza o registro pelo número. O responsável padrão é o do próprio registro — informe 'responsavel' para outro. Ex.: 'agendar ligação para o cliente amanhã às 11h para a Débora'.

Adiciona uma CLASSE DE CADASTRO (tag) a um contato JÁ EXISTENTE — sem duplicar o contato e sem apagar as classes atuais. Um contato pode ter VÁRIAS classes (ex.: 'Clientes e Empregadores' + 'UFMG 1986 Engenharia Civil'). Use isto (não criar_contato) quando o contato já existe e você só quer acrescentar mais uma classe. Localiza pelo nome, recupera o cadastro e grava a nova classe. Idempotente: se já tiver a classe, não faz nada.

Adiciona uma FILIAL (endereço com CNPJ) a um fornecedor JÁ cadastrado (mesma raiz de CNPJ) — independente de documento. Use quando uma NFC-e/NF-e chega de uma filial ainda não cadastrada e a matriz já existe: a filial precisa entrar no cadastro de endereços. Localiza a matriz pela raiz, verifica se a filial já existe (evita duplicar) e confirma que ela apareceu. Depois, selecione a filial em Matriz/Filial no documento (ou recadastre o documento). Passe o CNPJ COMPLETO da filial (14 dígitos).

Insere uma INTERAÇÃO (andamento/registro de contato) em um registro da Central de Relacionamento (CRM) já existente. Localiza o registro pelo número e anexa a interação (a interação fica registrada em nome do usuário logado). Use buscar_relacionamentos/detalhar_relacionamento para achar o número. Ex.: 'registrar que liguei para o cliente e ele pediu retorno amanhã'.

Responde dúvidas de USO do NEXT Finance/Business consultando o manual oficial do sistema (base de conhecimento embarcada). Use SEMPRE que o usuário perguntar 'como faço...', 'onde fica...', 'como funciona...', 'como cadastro/lanço/conecto/emito...' ou pedir o passo a passo de qualquer funcionalidade. Retorna o(s) artigo(s) do manual para você responder com o procedimento correto — não inventar. Sem argumento (ou 'índice'), lista todos os tópicos disponíveis. Não exige login.

Anexa um arquivo (boleto PDF, comprovante, nota, imagem, etc.) a um lançamento. Localiza o lançamento pelo trio (nome_conta + data + valor/descrição) e envia o arquivo. Informe 'caminho_arquivo' (arquivo local no computador) OU 'conteudo_base64' + 'nome_arquivo'. O nome precisa ter extensão (ex: boleto.pdf).

Marca as linhas pendentes de uma conciliação para que ela possa ser finalizada. Confirma as linhas com match automático e marca as sem match como novo lançamento. Necessário rodar ANTES de executar_conciliacao (senão a finalização é recusada com 'Existe algum lançamento para conciliar desmarcado').

Associa (mapeia) uma conta bancária vinda do Open Finance a uma conta do NEXT — associação CONTA A CONTA. Use o id da conta OF obtido em conectar_open_finance ou listar_contas_do_item_open_finance.

Atualiza os dados de um contato EXISTENTE (sem duplicar): e-mail, celular/telefone, REDES SOCIAIS (site, Instagram, Facebook, LinkedIn, TikTok), observações — e pode acrescentar classes. Só altera os campos informados; os demais são preservados. Localiza pelo nome. Também RENOMEIA (novo_nome, ex.: limpar '?' do nome) e aceita alvo por id (desambigua nomes duplicados). Para só adicionar classe, use adicionar_classe_contato.

Dispara uma sincronização Open Finance para a conta — puxa os lançamentos mais recentes do banco via Pluggy. Após sucesso, use 'buscar_lancamentos' para ver os novos dados. Pode levar alguns segundos (chamada assíncrona ao banco).

BAIXA (liquida) um título A PAGAR — marca o pagamento e debita o valor de uma conta corrente/caixa (conta_destino). Localiza o título pelo fornecedor (contraparte) + vencimento (+ valor para desambiguar). Suporta baixa PARCIAL. Use buscar_contas_a_pagar para encontrar o título antes. Confirme com o usuário antes de baixar.

BAIXA (liquida) um título A RECEBER — marca o recebimento e joga o valor numa conta corrente/caixa (conta_destino). Localiza o título pelo cliente (contraparte) + vencimento (+ valor para desambiguar). Suporta baixa PARCIAL (valor_parcial + previsao_restante). Use buscar_contas_a_receber para encontrar o título antes. Confirme com o usuário antes de baixar.

Busca compras de produtos agrupadas por produto e fornecedor. Use 'busca' para filtrar pelo nome do produto (ex: 'bombom garoto', 'arroz'). Use 'pessoa_id' para filtrar por fornecedor específico. Ideal para ver histórico de compras, comparar preços e rastrear aquisições.

Lista os TÍTULOS A PAGAR (contas a pagar) da carteira — agrega TODAS as contas do tipo 'Conta a Pagar'. Cada título traz: vencimento, valor, moeda, fornecedor (campo 'contraparte'), conta, se está vencido e os dias de atraso/para vencer. Retorna totais_por_moeda (nunca soma moedas diferentes) e agregação por fornecedor. Use moeda='BRL' para focar no real; apenas_vencidos=true para só o que está em atraso. Janela padrão: 1 ano atrás a 1 ano à frente.

Lista os TÍTULOS A RECEBER da carteira — agrega TODAS as contas do tipo 'Conta a Receber' e, por padrão, também as do tipo 'Contas em Cobrança' (cada título tem o flag em_cobranca). Cada título traz: vencimento, valor, moeda, cliente (campo 'contraparte'), conta, se está vencido e os dias de atraso/para vencer. Retorna totais_por_moeda (nunca soma moedas diferentes) e agregação por cliente. Use moeda='BRL' para focar no real; apenas_cobranca=true para SÓ os recebíveis em cobrança; apenas_vencidos=true para só os vencidos. Janela padrão: 1 ano atrás a 1 ano à frente.

Busca os DADOS CADASTRAIS de um contato (pessoa física/jurídica) pelo nome na Central de Relacionamento. A busca casa o termo em qualquer parte do nome (ex: 'Verdemar' acha 'ORGANIZAÇÃO VERDEMAR LTDA'). Com 1 resultado (ou nome exato) retorna a FICHA COMPLETA: para PF — CPF, RG, profissão, aniversário, e-mail, telefone, celular, endereço completo (logradouro, bairro, cidade/UF, CEP), chave PIX, redes sociais, observações; para PJ — CNPJ raiz, ramo/CNAE e cada estabelecimento com CNPJ, inscrição estadual (IE), inscrição municipal (IM) e endereço. Sempre inclui os registros CRM em aberto e os contratos vinculados. Com vários resultados, retorna lista enxuta (nome/tipo/cidade/e-mail) para refinar. Sem resultados, orienta os campos para cadastro. Use antes de criar_registro_relacionamento para localizar o contato e ver se já há tratativas abertas.

Lista documentos recebidos (NFCe, NF-e, etc.) do NEXT Business no período. Use 'nome_fornecedor' para filtrar por fornecedor. Use 'com_itens: true' para incluir os produtos/serviços de cada documento. Retorna totais de valor e valor líquido do período.

Lista as DESPESAS PERIÓDICAS (estimativas recorrentes) da carteira — a camada de PREVISÃO que o usuário cadastra na tela 'Despesas Periódicas' e que depois é programada em Contas a Pagar. Cada item traz: descrição, valor_estimado, moeda, dia do mês, periodicidade (Mensal/Anual…), plano de contas, centro de custo, variacao_tolerada_pct e previsoes_associadas. Retorna a estimativa_mensal_por_moeda (orçamento mensal). Use moeda='BRL' para focar no real. Distinta de buscar_contas_a_pagar (que traz os títulos já programados/reais).

Busca produtos e serviços dentro dos documentos recebidos (NFCe). Ideal para: 'onde comprei leite?', 'quanto paguei por café em cada fornecedor?'. Use 'busca' para filtrar pelo nome/descrição do produto. Use 'nome_fornecedor' para restringir a um fornecedor específico. Cada item retorna o documento de origem (data, número, fornecedor).

Busca lançamentos/transações da carteira. nome_conta é OPCIONAL — sem ele a tool agrega automaticamente todas as contas de movimento (corrente, cartão de crédito, caixa, poupança) numa única chamada, retornando o resultado consolidado. Prefira chamar UMA vez sem nome_conta a iterar por conta para um dashboard. Use plano_de_contas para filtrar por categoria (ex: 'Restaurante'). Transferências entre contas são excluídas por padrão. O retorno inclui totais (despesas/receitas/saldo) + agregações por plano_de_contas e centro_de_custo. Cada lançamento traz os campos de TÍTULO: 'vencimento' (DataVencimento), 'data_transacao' (data da baixa/liquidação), 'data_emissao', 'cliente', 'numero_documento', 'liquidado' e 'dias_atraso' (data_transacao − vencimento, para fator de atraso). Para uma consulta de TÍTULOS LIQUIDADOS, use apenas_liquidados=true.

Lista as RECEITAS PERIÓDICAS (estimativas recorrentes) da carteira — a camada de PREVISÃO da tela 'Receitas Periódicas', depois programada em Contas a Receber. Cada item traz: descrição, valor_estimado, moeda, dia do mês, periodicidade, plano de contas, centro de custo, variacao_tolerada_pct e previsoes_associadas. Retorna a estimativa_mensal_por_moeda. Use moeda='BRL' para focar no real. Distinta de buscar_contas_a_receber (títulos já programados/reais).

Central de Relacionamento (CRM) — lista as atividades (Leads, Oportunidades, Atendimentos, Cancelamentos) no período. Ideal para 'resumo das atividades da semana/mês'. Retorna agregações por tipo, situação (funil), responsável e origem, além da lista de atividades. Período default: últimos 30 dias. Filtros opcionais: tipo, situacao, responsavel, origem, busca.

Cadastra MANUALMENTE um documento fiscal recebido no NEXT Business (Compras & Despesas → Documentos Recebidos) a partir de dados lidos de um PDF/impressão/imagem — quando NÃO há XML nem link importável (ex.: NFC-e cuja consulta foi protegida por reCAPTCHA, ou NF3-e de energia). O ASSISTENTE lê o documento e passa os campos. Tipos: 'NFCe', 'NFe', 'NFSe', 'Energia Elétrica' (NF3-e), 'Recibo', 'Cupom Fiscal', etc. FORNECEDOR pela RAIZ do CNPJ (identidade única): se a filial (CNPJ completo) já existe, vincula a ela; se a empresa (raiz) existe mas a filial não, adiciona a filial (passe o endereço); se a raiz NÃO existe, CRIA o cadastro completo (passe o endereço + opcional classe_fornecedor). Se a filial existe mas o endereço mudou, passe atualizar_endereco=true com os campos endereco_* novos. ATENÇÃO a valores negativos (ex.: energia compensada na NF3-e reduz o total). PERGUNTE ao usuário a DATA DE EMISSÃO quando ela não estiver visível no documento, e a FORMA DE PAGAMENTO (e conta/cartão) — não invente. Passe sempre 'fornecedor_cnpj'. IMPORTANTE: este passo só CRIA o documento. Em seguida chame 'classificar_documento_recebido' para definir a CONTA/CARTÃO, o NÚMERO DE PARCELAS e vencimentos, o PLANO DE CONTAS e o CENTRO DE CUSTO — senão o lançamento fica sem classificação. Pergunte conta/parcelas/centro se o usuário não informou.

Calcula (SEM gravar) o reajuste de um contrato: usa o índice acumulado dos últimos 12 meses (padrão) do Banco Central — IPCA ou IGP-M — até o último mês fechado, e mostra valor atual → valor novo. O índice é lido do texto do contrato ('Informações sobre o contrato'); se não estiver lá, informe em 'indice'. Fonte: BCB SGS (público).

Classifica o pagamento de um documento recebido JÁ importado (Compras & Despesas): define a conta/cartão, parcelas e vencimentos, e o plano de contas + centro de custo — deixando-o lançado no Finance. Localiza o documento pelo 'numero' (+ 'fornecedor' se houver mais de um). Se o usuário não informou conta/parcelas/classificação, PERGUNTE antes.

Conecta uma conta ao banco via Open Finance (Pluggy) pela PRIMEIRA vez. Fluxo INTERATIVO: abre o widget Pluggy Connect no navegador local, o USUÁRIO escolhe o banco e autentica (senha/MFA no app do banco), e o MCP salva o vínculo e mapeia a conta. Se o banco trouxer VÁRIAS contas, retorna a lista para associar cada uma com associar_conta_open_finance. Para renovar MFA de conta já conectada, use iniciar_open_finance_qr.

CONFERÊNCIA previsto × realizado de um mês: cruza as 3 camadas — previsto (Despesa/Receita Periódica = estimativa), programado (título em Contas a Pagar/Receber no mês, após acerto) e realizado (efetivado nas contas de movimento). Retorna por_item (descrição: previsto/programado/realizado/diferença/status, respeitando a variação tolerada) e por_categoria (orçado × realizado por plano de contas), além de resumo_por_moeda. Status: ok / acima / abaixo / pendente (sem realizado) / sem_previsao. Use para validar se as estimativas batem com a realidade. Passe moeda='BRL' para não misturar moedas. Observação: por_item casa por descrição+plano (exato); a visão por_categoria é a mais robusta.

Rentabilidade OFICIAL dos investimentos (mesmo serviço da tela Rentabilidade do NEXT) — NÃO recalcula fórmula. Retorna, por ativo: % mensal, % acumulado composto, setor; os benchmarks do período (CDI/IPCA/IGP-M); o % do benchmark; e a CONTRIBUIÇÃO de cada ativo para o resultado (peso pelo saldo atual × acumulado) — para saber o IMPACTO real (um fundo pode cair muito mas pesar pouco). Marca 'ND' os meses sem cálculo (posição inexistente/sem cotação — não é 0%) e sinaliza meses atípicos para conferir possível evento societário (incorporação/amortização/mudança de ticker). Informe o período (YYYY-MM ou YYYY-MM-DD).

Consulta o saldo de UMA conta numa data específica (padrão: hoje). Use 'saldo_carteira' para o snapshot consolidado de todas as contas. Retorna o saldo acumulado do dia (ex: R$ -16.049,49 no Itaú em 06/06/2026).

GRAVA o CNPJ Raiz de Pessoas Jurídicas que estão sem — usando os 8 primeiros dígitos do CNPJ dos estabelecimentos, SÓ quando todos compartilham a mesma raiz (senão pula e reporta). Preserva endereços/IE/município (grava pelo mesmo endpoint da tela) e VERIFICA relendo o cadastro. Passe 'pessoa' para um contato, ou todos=true para o lote. Recomendado: rodar em UM contato primeiro (pessoa=...) e conferir antes do lote.

ONBOARDING (não exige login): cria o cadastro do usuário + uma CARTEIRA DE TESTE GRÁTIS (30 dias) para um prospect que ainda não usa o NEXT. Use quando alguém pede para 'criar minha conta/carteira', 'quero testar o NEXT', etc. REGRAS: (1) a SofIA NÃO pede senha pelo chat — ela gera uma senha temporária e o prospect define a dele depois via 'Esqueci minha senha'; (2) o prospect precisa ACEITAR os termos de uso (https://finance.net.br/termos-de-uso) explicitamente → só então passe aceitar_termos=true; (3) CONFIRME todos os dados (e o produto inferido) antes de gravar. Produtos: Finance Standard (padrão, gestão pessoal), Finance Professional, Finance Fortune, e as versões '+ Business' para PJ.

Cria um novo centro de custo na carteira. Informe o 'nome'; opcionalmente um 'pai' (centro de custo existente, para criar como sub-centro) e uma 'descricao'.

Cria uma CONTA de QUALQUER TIPO na carteira (Conta Corrente, Poupança, Conta Caixa, Cartão de Crédito, CDB, Tesouro Direto, Ações, Fundo, Empréstimo, Conta a Pagar/Receber, etc.). Obrigatórios: tipo_conta e nome. Use listar_tipos_conta para ver os tipos válidos. Nomes (tipo_conta, portfolio, banco, moeda, país) são resolvidos para IDs. Campos bancários (banco, agência, conta) valem para contas com banco. Padrões: moeda BRL, país Brasil, data inicial hoje, saldo inicial 0. Portfólio: se omitido, o sistema atribui um padrão.

Cria um CONTATO (pessoa física ou jurídica) no NEXT, seguindo as regras do sistema. OBRIGATÓRIOS: tipo (PF/PJ), nome (PF=nome completo; PJ=razão social) e classe_de_cadastro (use listar_classes_de_cadastro para ver as opções). Demais campos são opcionais mas recomendados (CPF/CNPJ, e-mail, telefone, endereço). Nomes (classe, ramo, país) são resolvidos para IDs internos.

Cria um NOVO contrato no NEXT Business (faturamento recorrente). Funciona em qualquer carteira: INFERE o produto pelos Serviços cadastrados no Business daquela carteira (case o mais provável a partir do 'produto' informado; se ambíguo/inexistente, a tool devolve as opções para você escolher — NÃO invente). SEGURANÇA: por padrão (confirmar=false) só devolve a PRÉVIA do plano (cliente, produto, valor, nº de parcelas, vencimentos) SEM gravar; confira com o usuário e só então chame de novo com confirmar=true para gravar. REGRAS: nº de parcelas segue a periodicidade dentro do prazo (mensal→12, trimestral→4, semestral→2, anual→1 no ano); reajuste padrão anual pelo IPCA (gravado nas Informações para o reajustar_contrato detectar depois); assinatura sempre pelo usuário logado + '(via SofIA MCP)'. O cliente deve já estar cadastrado (use buscar_contato/criar_contato). Ex.: compra 'Trimestral' de R$261,95 → contrato anual, 4 parcelas trimestrais. NÃO emite faturamento (isso é gerar_faturamento_contrato).

Cria um novo lançamento (despesa ou receita) numa conta. Valor negativo = despesa, positivo = receita. Nomes (conta, plano de contas, centro de custo) são resolvidos para IDs internos automaticamente; se a busca for ambígua a tool lista as opções.

Cria uma nova categoria no plano de contas. O 'pai' é OBRIGATÓRIO e define se o novo plano é de DESPESA ou RECEITA (o tipo é herdado do ramo do pai — ex.: pai 'Despesas Operacionais' cria uma despesa). Use 'listar_plano_de_contas' para achar o nome do pai.

Cria uma PROPOSTA comercial no NEXT Business (Atendimento). FLUXO: pergunte ao usuário (1) o CLIENTE, (2) o TIPO da proposta, (3) os SERVIÇOS a incluir, e (4) SE QUER USAR UM MODELO (chame listar_modelos_proposta para mostrar as opções) — o modelo preenche os blocos de texto (Introdução, Validade, Condição…). Os serviços são casados com os Serviços do Business (se ambíguo, a tool devolve as opções). SEGURANÇA: por padrão (confirmar=false) devolve a PRÉVIA (cliente, tipo, serviços, total) SEM gravar; confira com o usuário e só então chame com confirmar=true. NÃO envia/gera PDF (isso é ação à parte na tela).

Cria um registro de atividade na Central de Relacionamento (Lead, Oportunidade, Atendimento, etc). Localiza o contato pelo nome automaticamente. Se o contato já tiver registros EM ABERTO, retorna um aviso e NÃO cria (passe ignorar_abertos=true para criar mesmo assim). Campos com nome (tipo, origem, situação, prioridade, responsável) são resolvidos para IDs; se inválidos, a tool lista as opções válidas. Situação padrão: '0 - Entrar em Contato'. Prioridade padrão: 'Pendente de Classificação'. Data padrão: hoje. PJ: informe a PESSOA INTERNA em 'contato' (ex.: 'Marlene') — a tool resolve o ENDEREÇO e o celular do cadastro (a pessoa pode ou não ter endereço); se a pessoa não existir, lista os contatos da PJ. Sem pessoa, use 'endereco' para escolher o endereço (ou usa o principal).

Cria uma transferência entre duas contas — débito na conta de origem e crédito na conta de destino (o NEXT cria automaticamente os dois lados, vinculados). Use isto, NÃO criar_lancamento, quando o dinheiro sai de uma conta sua e entra em outra conta sua (ex: PIX entre contas próprias, aplicação/resgate, pagamento de fatura de cartão a partir da conta corrente). Requer permissão de edição na conta de origem. Valor sempre positivo.

Remove o vínculo Open Finance de uma conta (desvincula a conexão bancária). Use quando a associação ficou errada ou o vínculo travou — depois dá para reconectar com 'conectar_open_finance'.

Detalha os lançamentos pendentes de uma conciliação. Mostra cada transação do extrato, se é nova (não existe no NEXT) ou já existe, e se tem match automático com um lançamento existente.

Detalha um contrato pelo 'numero' (+ 'pessoa' para desambiguar): valor atual, datas, periodicidade de reajuste, situação e o texto de 'Informações sobre o contrato' (onde fica o índice de reajuste IPCA/IGPM).

Detalha UMA atividade da Central de Relacionamento pelo número, incluindo todas as interações registradas e itens de agenda. Use 'buscar_relacionamentos' primeiro para achar o número.

Raio-x da carteira para CONDUZIR o cliente: o que já está montado (contas por tipo, estrutura, Open Finance) × o que falta × pendências (conciliações), com uma lista de 'proximos_passos' sugeridos. Use ao INÍCIO de um atendimento/onboarding, ou quando o cliente perguntar 'e agora?' / 'por onde começo?' — e proponha ativamente o próximo passo em vez de esperar a pergunta.