O Finanly é um app de finanças pessoais e de pequenos negócios. A parte mais trabalhosa da engenharia foi a importação: trazer fatura de cartão, extrato, boleto, Pix e nota fiscal de consumidor (NFC-e) para dentro do app sem digitação. Este artigo conta como funciona.

Um leitor genérico em vez de um parser por banco

Cada banco formata a fatura de um jeito. Em vez de escrever um parser por banco, construímos um leitor genérico de linhas de documento. Ele procura o padrão data + descrição + valor e lida com as variações comuns: datas como "20 OUT", sinal de débito e crédito (D/C), parcelas, documentos em duas colunas e o ano inferido a partir do vencimento. No fim, o leitor confere o resultado com o total ou o saldo do próprio documento, e isso nos avisa quando algo foi lido errado.

Além do PDF, o sistema lê arquivos OFX (o formato de extrato que os bancos exportam) e códigos: o código de barras de boletos, o QR Code de NFC-e e o BR Code do Pix.

Boletos têm pegadinhas

A linha digitável do boleto traz um fator de vencimento, e esse fator voltou ao início em 22/02/2025 (ele só tem quatro dígitos). Um leitor que ignore isso calcula datas erradas. O mesmo vale para boletos de arrecadação (44 e 48 dígitos) e de cobrança (44 e 47), que têm regras diferentes.

Importar duas vezes não duplica

Cada linha importada recebe um identificador estável (um hash SHA-1 do conteúdo), guardado na despesa. Reimportar o mesmo arquivo gera os mesmos identificadores e o sistema reconhece o que já existe. Há também um registro de cada importação, o que permite desfazer uma carga inteira.

Para duplicatas "quase iguais" (por exemplo, o mesmo gasto vindo da fatura e do extrato), a regra é: mesmo valor com diferença de até R$ 0,05 e datas a até três dias. A chave de 44 dígitos de uma NFC-e bloqueia duplicata de forma definitiva. Pagamento de fatura e transferências entre contas próprias vêm desmarcados, para não contar o mesmo dinheiro duas vezes.

Categorização em duas camadas, sem IA externa

A primeira camada usa o histórico do próprio usuário e grupos de palavras-chave. A segunda é um modelo de embeddings (multilingual-e5-small, quantizado) que roda dentro do nosso servidor, empacotado na imagem do container. Algumas regras de segurança que adotamos:

  • O modelo só sugere categoria se a nota de similaridade for de pelo menos 0,80 e a margem sobre a segunda melhor opção for de pelo menos 0,02;
  • Há um limite de 25 segundos e, passado esse tempo, o sistema volta para a primeira camada;
  • Nenhum extrato ou fatura é enviado para um serviço de IA de terceiros. Isso foi decisão de produto: são dados financeiros sensíveis.

Stack

NestJS e Prisma no servidor, React e Vite no cliente, PostgreSQL, Docker e assinatura recorrente pelo Asaas, com período de teste. As páginas públicas são pré-renderizadas no build, para carregar rápido e serem bem lidas por buscadores.

Aprendizados

Dois que valem registro: o e-mail de verificação enviado no cadastro é um link (não um código numérico), e cada reenvio invalida os anteriores, o que evita confusão; e o CNPJ alfanumérico, que passou a existir em 2026, já é aceito na chave da NFC-e (veja como preparamos os sistemas).

Veja o Finanly funcionando ou conheça os outros sistemas.