Open Finance e Monitoramento Financeiro

Resumo

Para o monitoramento financeiro pessoal de Yan, há duas abordagens práticas: um agregador oficial de Open Finance, como a Pluggy, para sincronização estruturada; ou a captura de notificações do celular e envio para um webhook do n8n, para receber eventos quase em tempo real. A primeira é a opção mais adequada como fonte principal de dados; a segunda pode funcionar como complemento ou protótipo de baixo custo.

Por que é relevante para Yan

O projeto Home Finance Tracker já prevê múltiplas contas, cartões, faturas, reconciliação bancária, receitas de RPG e alertas. A integração automática reduz a manutenção manual que tornou o Firefly III pouco conveniente para esse uso e pode alimentar o ledger e os fluxos existentes de n8n.

Opções de integração

Agregador via Open Finance

Confirmado por fonte externa, consultada em 2026-10-16: a documentação da Pluggy descreve conectores de Open Finance regulado que seguem o modelo de dados da plataforma, incluindo itens, contas e transações. A API também documenta transações de cartão e consulta por fatura. O fluxo exige consentimento do usuário na instituição financeira; não é uma API aberta para ignorar autenticação ou consentimento.

Fluxo proposto:

1. Autorizar cada instituição na interface de consentimento do provedor.
2. Sincronizar contas, saldos, transações e dados de cartão por um job diário ou periódico.
3. Normalizar os dados no Home Finance Tracker.
4. Deduplicar por identificador externo e reconciliar divergências antes de gerar alertas.
5. Manter tokens e segredos fora do vault e fora de mensagens ou logs públicos.

Vantagens: dados estruturados, menor dependência de scraping e melhor cobertura para extratos e cartões.

Cuidados: cobertura, produtos disponíveis, frequência de atualização, limites e preço variam por instituição e plano; validar cada conector antes de adotar a integração como fonte contábil definitiva.

Notificações do Android para webhook

Confirmado por fonte externa, consultada em 2026-10-16: a documentação do MacroDroid lista gatilhos relacionados a notificações e ações para chamar serviços web. Uma macro pode filtrar notificações bancárias e enviar um POST ao n8n com o texto recebido.

Fluxo de protótipo:

1. Filtrar apenas notificações dos aplicativos bancários autorizados.
2. Extrair valor, tipo, estabelecimento e data sem enviar credenciais, códigos ou conteúdo desnecessário.
3. Enviar o evento para um webhook protegido do n8n.
4. Classificar como pendente até a confirmação por uma fonte bancária ou por conciliação posterior.

Vantagens: baixo custo inicial e baixa latência para compras, Pix e cobranças notificadas.

Limitações: notificações podem ser alteradas, atrasadas, agrupadas ou não disparadas; o texto pode não conter todos os campos necessários. Portanto, esse caminho não deve ser a única fonte de verdade para saldos, faturas ou impostos.

Decisão atual

Provável: começar pelo agregador de Open Finance como fonte estruturada e usar notificações via n8n apenas como sinal de evento ou fallback. Antes de implementar em produção, comparar cobertura, custo, estabilidade e dados de cartão da Pluggy com as instituições efetivamente usadas.

Não armazenar neste vault credenciais bancárias, tokens de consentimento, cookies, números completos de conta/cartão, identificadores privados ou conteúdo bruto de notificações.

Relações no vault

• Home Finance Tracker — requisitos de contas, cartões, faturas, reconciliação e alertas.
• Fluxo Financeiro WhatsApp com n8n e WAHA — automações financeiras já documentadas com n8n.

Atualização operacional — 2026-10-16

Confirmado por relato local: Yan já integrou cinco bancos ao Pluggy e quer avaliar a inclusão das contas da esposa, além de sincronizar os dados com o Firefly III e um watcher do Hermes.

Confirmado por documentação atual da Pluggy: o caminho gratuito para uso pessoal é o Meu Pluggy, com até cinco conexões ativas do mesmo titular e atualização automática própria do serviço. O limite de cinco não deve ser generalizado para todos os planos ou ambientes da API: a documentação também descreve limites diferentes para sandbox/desenvolvimento e para uso comercial.

Decisão técnica recomendada: tratar o limite como uma restrição de titularidade e produto, não criar uma segunda conta como workaround automático. Uma conta separada da esposa pode ser investigada somente se o uso, consentimento, titularidade dos dados e termos da Pluggy forem compatíveis; não persistir credenciais no vault. Enquanto isso, o sincronizador deve aceitar múltiplas fontes de credenciais por configuração externa e rotular as contas por titular, sem misturar segredos ou dados brutos no repositório.

Integração com Firefly III: a deduplicação por external_id é compatível com a documentação do Firefly III, que permite pesquisar esse campo e usá-lo para detectar duplicatas. Isso é uma estratégia de implementação, não prova de que o identificador entregue pela Pluggy seja globalmente único: o sincronizador deve compor uma chave estável com a origem/item quando necessário e testar transações pendentes versus confirmadas.

Status do watcher: o desenho Pluggy → sincronizador/n8n → Firefly III → alertas do Hermes permanece uma proposta de automação; o lote não fornece evidência de que essa integração já esteja implementada ou validada em produção.

Fontes

• Pluggy — Personal use: read your own data with Meu Pluggy, documentação oficial consultada em 2026-10-16.
• Pluggy — Item, documentação oficial consultada em 2026-10-16.
• Pluggy — Pricing, página oficial consultada em 2026-10-16.
• Pluggy — Open Finance Connectors, documentação oficial consultada em 2026-10-16.
• Pluggy — Credit Card Installments, documentação oficial consultada em 2026-10-16.
• Banco Central do Brasil — Open Finance, referência institucional consultada em 2026-10-16.
• Firefly III — Data field roles, documentação oficial consultada em 2026-10-16.
• Firefly III — All search options, documentação oficial consultada em 2026-10-16.
• MacroDroid Wiki — Triggers, documentação do produto consultada em 2026-10-16.
• n8n — Email Trigger (IMAP), documentação oficial consultada em 2026-10-16.

Segurança operacional para credenciais

Decisão: nunca enviar client_secret, tokens, cookies, senhas ou cabeçalhos de autorização pelo chat, nem persistir esses valores no vault, no batch de captura ou em logs. A configuração deve ficar fora do conteúdo versionado, em arquivo local protegido ou em um gerenciador de segredos; o sincronizador deve receber apenas a configuração necessária em tempo de execução. O arquivo local também deve ser excluído do Git e ter permissões restritas.

A orientação do lote para compartilhar chaves diretamente na conversa foi tratada como inadequada e não deve ser repetida. O fato de um serviço estar rodando ou de um sincronizador ter sido declarado como “testado” na conversa não substitui a verificação independente de filesystem, execução e leitura de retorno antes de registrar o status como produção.

Atualização operacional — custo do Pluggy e alternativa por e-mail

Relato local, ainda não verificado externamente: ao abrir o dashboard da Pluggy, Yan percebeu o início aparente de um trial associado a um plano pago e sinalizou que não deseja assumir uma mensalidade corporativa. O valor mencionado na conversa não foi tratado como preço confirmado. O status de cobrança, método de pagamento e condições do trial devem ser conferidos diretamente em Billing/Subscription e, se necessário, com o suporte oficial; não presumir que a ausência de cartão ou contrato elimine automaticamente qualquer obrigação.

Decisão de arquitetura: não avançar com uma integração paga da Pluggy sem confirmar explicitamente o plano, o trial, os limites e a forma de cobrança. Como alternativa de baixo custo, avaliar um fluxo baseado em notificações por e-mail dos bancos:

1. Aplicar uma etiqueta/filtro às mensagens financeiras autorizadas.
2. Receber as mensagens no n8n por Email Trigger (IMAP) ou Gmail Trigger.
3. Extrair somente data, valor, instituição, tipo e estabelecimento; descartar credenciais, códigos e conteúdo desnecessário.
4. Enviar a transação para o Firefly III local após validação, normalização e deduplicação.
5. Marcar o registro como pendente quando o e-mail não trouxer dados suficientes para conciliação.

Esse fluxo é uma proposta de protótipo, não evidência de implementação ou validação em produção. E-mails podem atrasar, faltar ou conter campos incompletos; portanto, não devem ser a única fonte de verdade para saldo, fatura ou obrigações fiscais. Credenciais IMAP/Gmail devem permanecer nas credenciais protegidas do n8n, fora do vault e de logs.

Localização operacional dos identificadores no dashboard

Confirmado por evidência visual local, consultada em 2026-10-16: no painel em português da Pluggy, os bancos conectados podem ser inspecionados pelo menu Dados Financeiros, nas áreas Execuções ou Eventos. Essas telas exibem as execuções de login/conexão e os eventos de criação correspondentes; ao abrir uma entrada, o painel apresenta o identificador da conexão/item.

Esse procedimento serve para localizar IDs durante diagnóstico e configuração do sincronizador, mas os identificadores não devem ser copiados para o vault, para mensagens ou para logs públicos. Os rótulos e a organização do dashboard podem mudar; confirmar a tela diretamente antes de atualizar procedimentos operacionais.

Fluxo pessoal via Meu Pluggy — atualização operacional

Confirmado por documentação oficial da Pluggy, consultada em 2026-10-16: o fluxo de uso pessoal não exige contratar o plano comercial nem termina com o trial. No Dashboard, o usuário deve abrir a aplicação, entrar em Demo e usar Connect Account; no widget, deve selecionar o conector MeuPluggy, em vez de escolher diretamente um banco ou o Sandbox. Cada banco já conectado no Meu Pluggy aparece como um item da aplicação e é atualizado automaticamente pelo serviço.

Para obter um identificador sem persistir segredo no vault:

1. Acessar a página Demo da aplicação no Dashboard.
2. Abrir Connected Items.
3. Selecionar o item correspondente e copiar o itemId apenas para a configuração protegida do sincronizador.
4. Manter clientId, clientSecret, API keys e demais credenciais fora do vault, do chat e dos logs.

A documentação oficial informa que esse caminho é pessoal, limitado a até cinco conexões e não deve ser tratado como autorização para uso comercial. A disponibilidade e os rótulos da interface podem mudar; confirmar o painel antes de atualizar o procedimento.

Validação do sincronizador Pluggy → Firefly III — 2026-10-16

Confirmado por teste local em modo seguro: cinco conexões foram consultadas contra a API da Pluggy. Quatro retornaram contas e transações normalmente; uma não retornou contas na primeira consulta. O teste dry-run encontrou 110 lançamentos e não gravou nenhum lançamento no Firefly III.

Correção de integração: o sincronizador deve usar GET /v2/transactions, com paginação por cursor. A API oficial marca o endpoint antigo baseado em páginas como depreciado; a documentação também confirma que transações de faturas abertas e parcelas futuras chegam como PENDING até afetarem o saldo devido.

Bloqueios antes da importação real: não importar parcelas futuras como despesas já realizadas; o cartão observado contém lançamentos futuros até 2027. Pagamentos de fatura também podem aparecer no cartão e na conta bancária, portanto a reconciliação precisa identificar e excluir a duplicidade antes de escrever no Firefly III. A importação real permanece bloqueada até essas regras serem implementadas e testadas.

Segurança: nenhum identificador de conexão, token, segredo ou cabeçalho de autorização foi persistido nesta nota. O acesso ao Firefly III deve continuar em configuração protegida, fora do vault, do chat e dos logs.

Fontes adicionais

• Pluggy — Transactions, documentação oficial consultada em 2026-10-16.
• Pluggy — List transactions by cursor, documentação oficial consultada em 2026-10-16.
• Pluggy — Basic concepts, documentação oficial consultada em 2026-10-16.
• Firefly III — Duplicate detection, documentação oficial consultada em 2026-10-16.

Registro de captura — 2026-10-16

Confirmado por relato local: uma execução de dry-run do sincronizador financeiro identificou 84 transações dos últimos 15 dias, abrangendo Nubank, PicPay, Inter e InfinitePay, e reportou conexão com uma instância Firefly III v6.7.9. O registro não confirma gravação de transações no Firefly III nem deve ser interpretado como validação de produção.

A credencial recebida, o token, o caminho exato de configuração e quaisquer identificadores de conta foram deliberadamente omitidos desta nota. O status efetivo da integração deve continuar sendo verificado por execução independente e leitura do retorno, não apenas por uma mensagem de sucesso.

Objetivo de reconciliação Pluggy → Firefly III — 2026-10-16

Objetivo operacional: sincronizar as transações dos últimos 15 dias no Firefly III e validar o fluxo financeiro entre entradas, compras no crédito, faturas e transferências, sem duplicidade.

Regras de processamento:

• Importar recebimentos e Pix como entradas nas contas de ativo correspondentes.
• Registrar compras de cartão realizadas no período, mas não tratar parcelas futuras como despesas já realizadas.
• Classificar pagamentos de fatura e transferências internas como transferências entre contas, evitando uma segunda saída contábil.
• Garantir idempotência por meio do banco local de transações sincronizadas e de uma chave external_id estável, composta com a origem quando necessário.
• Conferir, após a sincronização, os saldos e o balanço líquido do período.

Critérios de parada: interromper o processo diante de divergência superior a R$ 1,00 no fluxo líquido ou saldo, ou diante de erro de schema na API. O objetivo descreve o contrato de validação; não comprova que a importação foi executada ou validada em produção.

Fonte: registro operacional local de captura, consultado em 2026-10-16. Segredos, identificadores privados e comandos contendo credenciais foram omitidos deliberadamente.