io.github.paivapiovesan/next-finance

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.

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).

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.

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. O fornecedor precisa estar cadastrado (senão use criar_contato). 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 'fornecedor_cnpj' para vincular a filial certa; se for filial nova da mesma empresa, inclua também o endereço para cadastrá-la.

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.

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).

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 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 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.

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 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.

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).

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.

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.

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 as moedas disponíveis no NEXT Finance (ex: BRL, USD, EUR). Use 'busca' para filtrar por nome, sigla ou símbolo.

Lista o plano de contas da carteira (categorias de receita e despesa). Use para descobrir nomes exatos de categorias antes de buscar lançamentos por plano de contas.

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