Dev.to AI 🤖 Ai 👁 0 📖 10 min read

Como montei um robô que lê meus boletos do Gmail e confere o código de barras

O problema Todo mês é a mesma coisa. Condomínio, escola, plano de saúde, internet, aquele fornecedor que manda o boleto em PDF dentro de um e-mail com assunto "Documento disponível". Uns chegam no corpo do e-mail, outr

O problema

Todo mês é a mesma coisa. Condomínio, escola, plano de saúde, internet, aquele fornecedor que manda o boleto em PDF dentro de um e-mail com assunto "Documento disponível". Uns chegam no corpo do e-mail, outros em anexo, outros como foto tirada no celular.

Eu já perdi vencimento por isso. E, trabalhando com IA há alguns anos, fiquei com aquela coceira: dá pra resolver isso de um jeito bem feito, sem gambiarra e sem depender de uma ferramenta paga.

O resultado foi um pipeline em Python que lê meu Gmail, descobre sozinho quais e-mails têm boleto, extrai o código de barras dos anexos, confere se o código é válido e monta uma planilha com tudo. Roda no meu notebook, num Docker ou em qualquer cloud.

Neste artigo eu explico os conceitos por trás de cada peça. A ideia é que, mesmo quem nunca mexeu com embeddings ou OCR, termine a leitura entendendo como as coisas se encaixam.

O desenho geral

Antes dos detalhes, o caminho completo de um e-mail até virar linha na planilha:

flowchart TD
  A["1. Gmail (somente leitura)<br/>Busca e-mails novos e guarda o .eml"] --> B["2. Triagem com EmbeddingGemma 2<br/>Regra da linha digitável, depois embeddings"]
  B -- não --> X["Não é boleto<br/>Fica só registrado, não vai para o OCR"]
  B -- boleto --> C["3. Leitura do anexo<br/>Texto do PDF → barras ITF → Indra OCR"]
  C --> D["4. Validação dos dígitos<br/>Módulo 10 e 11, banco, valor, vencimento"]
  D -- inválido --> Y["Conta não fecha<br/>Vai para a aba Revisar com o motivo"]
  D -- válido --> E["5. Planilha<br/>Abas Boletos válidos, Revisar e Resumo"]
  Y --> E

Repare que cada etapa filtra a anterior. A IA faz a triagem e a leitura, mas quem decide se o boleto entra na planilha é uma conta matemática. Vou explicar etapa por etapa.

Etapa 1: separar o que é boleto (embeddings)

A primeira ideia de todo mundo é procurar a palavra "boleto" no e-mail. Funciona até o dia em que chega "Sua fatura de novembro está disponível" ou "Segue documento para pagamento". Nenhum dos dois tem a palavra mágica, e os dois são boleto.

É aí que entram os embeddings.

Pensa num mapa. Cada texto vira um ponto nesse mapa, e textos com significado parecido ficam perto um do outro. "Segue o boleto do condomínio" e "Sua fatura vence dia 10" caem no mesmo bairro. "Promoções da Black Friday" fica do outro lado da cidade. Tecnicamente, esse "ponto" é uma lista de números (um vetor), e a distância entre dois pontos mede o quanto os textos se parecem no sentido, não nas palavras.

Eu usei o EmbeddingGemma 2, modelo aberto do Google, por alguns motivos bem práticos:

  • É pequeno. A parte de texto tem 270 milhões de parâmetros e roda tranquilo em CPU, sem placa de vídeo.
  • Entende português (são mais de 100 idiomas).
  • Licença Apache 2.0, então dá pra usar sem dor de cabeça.
  • Tem uma coisa chamada Matryoshka: o vetor completo tem 768 números, mas você pode cortar e usar só os primeiros 256 perdendo pouquíssima qualidade. Como as bonecas russas, uma dentro da outra.

Como o classificador decide, em três camadas:

  1. Regra antes de modelo. Se o corpo do e-mail já tem uma linha digitável válida, é boleto e acabou. Não precisa de IA pra isso.
  2. Zero-shot. Escrevi meia dúzia de frases típicas de boleto e meia dúzia de frases de "não boleto" (newsletter, nota fiscal, comprovante de Pix). Cada e-mail novo vira um ponto no mapa e eu vejo de qual grupo ele está mais perto. Zero exemplos rotulados.
  3. Classificador treinado. Quando juntei uns 150 e-mails de cada tipo, treinei uma regressão logística em cima dos vetores. Treina em segundos, porque o modelo de embedding fica congelado.

Um detalhe que me pegou: esse modelo não pode rodar em float16. Ele não dá erro, só devolve vetores quebrados em silêncio. Em CPU eu uso float32 e pronto.

E a decisão de projeto mais importante: o classificador é só um porteiro barato. Ele não precisa acertar 100%. Na dúvida, deixa passar. Quem dá a palavra final é a validação matemática, lá na etapa 3.

Etapa 2: ler o anexo (código de barras e OCR)

Separado o e-mail, falta tirar o número do boleto de dentro do PDF ou da imagem. Aqui tem uma ordem que faz toda a diferença, do mais barato e confiável para o mais caro:

  1. Texto embutido no PDF. Muito boleto gerado por sistema já tem o texto "de verdade" dentro do arquivo. Se tem, é só ler. Custo zero.
  2. Ler as barras. As barrinhas do boleto seguem um padrão chamado ITF (Intercalado 2 de 5). Eu renderizo a página em 300 dpi e uso a biblioteca zxing-cpp pra decodificar. Aqui não tem "interpretação": ou as barras batem com o padrão, ou não. É o caminho mais confiável de todos.
  3. OCR. Se o boleto é uma foto torta ou um scan ruim e as barras não leem, aí sim entra o OCR.

OCR (Optical Character Recognition) é o processo de olhar uma imagem e transformar os desenhos das letras em texto. É o que você faz quando lê um papel, só que feito por um modelo.

Eu usei o Indra OCR, da Datalab, lançado este ano. O que me chamou atenção: o reconhecedor principal tem cerca de 1 milhão de parâmetros (sim, um milhão, não um bilhão), roda em CPU com ONNX Runtime e os modelos inteiros têm uns 76 MB. Ele devolve texto, posição de cada linha e um nível de confiança.

Só que OCR erra. Ele confunde a letra O com o número 0, o l minúsculo com o 1, quebra a linha digitável em pedaços. Por isso, depois do OCR, eu normalizo esses erros comuns e procuro sequências de 47 ou 48 dígitos no meio do texto.

E como eu sei que a sequência que achei é mesmo um boleto, e não um telefone, um CPF e um número de pedido grudados? Aqui entra a parte que eu mais gosto.

Etapa 3: validar o código (a matemática que ninguém vê)

Todo boleto tem dígitos verificadores. É o mesmo princípio do dígito do CPF ou da conta bancária: uma conta feita com os outros números gera um dígito de controle. Se alguém digitar (ou o OCR ler) um número errado, a conta não fecha.

No boleto bancário, a linha digitável tem 47 dígitos e vem dividida em campos:

  • Os três primeiros campos têm, cada um, seu dígito verificador calculado em módulo 10.
  • Existe um dígito geral, calculado em módulo 11 sobre o código de barras inteiro.
  • No meio disso tudo estão o código do banco, o valor e o vencimento.

O módulo 10, de forma simples: você multiplica os dígitos alternando por 2 e 1, da direita para a esquerda, soma tudo e vê quanto falta pra fechar a próxima dezena. O módulo 11 é parecido, com pesos de 2 a 9 e resto da divisão por 11. Parece bobo, mas pega praticamente todo erro de um dígito trocado.

Contas de consumo e tributos (luz, água, DAS, IPTU) usam outro formato: começam com 8, têm 48 dígitos em quatro blocos, e o terceiro dígito diz se a conta é em módulo 10 ou 11. O código trata os dois.

Uma pegadinha recente: o fator de vencimento. A data do boleto não vem escrita no código. Vem como um número de dias contados a partir de 07/10/1997. Esse contador só tem 4 dígitos, chegou em 9999 em fevereiro de 2025 e voltou para 1000. Ou seja, o mesmo número hoje pode significar duas datas com 25 anos de diferença. Resolvi escolhendo a data mais próxima da data em que o e-mail chegou.

Isso muda tudo no projeto: nada vira boleto válido sem passar na matemática. O embedding pode errar, o OCR pode errar, mas um número aleatório passar em quatro dígitos verificadores ao mesmo tempo é muito improvável. O que falha vai para uma aba "Revisar" na planilha, com o motivo exato (por exemplo, "DV do campo 2 inválido").

Rodar em qualquer lugar (e escalar)

Minha primeira versão era toda em AWS: SQS, DynamoDB, Lambda, ECS. Funcionava, mas me prendia a um fornecedor. Refiz pensando em uma pergunta: o que precisa mudar para isso rodar no meu notebook, numa VM qualquer ou em outra cloud?

A resposta ficou em duas variáveis de ambiente:

  • Onde ficam os dados: SQLite no notebook, Postgres no resto (RDS, Cloud SQL, Azure, tanto faz).
  • Onde ficam os arquivos: uma pasta local, S3, Google Cloud Storage ou Azure Blob. A biblioteca fsspec deixa o código igual para todos.

A fila mora no Postgres. Parece estranho no começo, mas o Postgres tem um recurso chamado FOR UPDATE SKIP LOCKED: vários workers pedem trabalho ao mesmo tempo e cada um pega uma tarefa diferente, sem briga. Testei com 8 workers disputando 200 tarefas e nenhuma foi processada duas vezes. Para o volume de e-mails de boleto, isso sobra, e é um componente a menos para cuidar.

Alguns conceitos que fizeram diferença:

  • Workers sem estado. Cada etapa lê do banco, faz o trabalho e grava de volta. Quer ler mais anexos ao mesmo tempo? Sobe mais cópias do worker de OCR.
  • Idempotência. Rodar duas vezes não duplica nada. O e-mail é identificado pelo id do Gmail e o boleto pelo próprio código de barras. Se o mesmo boleto chegar em dois e-mails (o famoso "lembrete de vencimento"), vira uma linha só na planilha.
  • Retentativa e "fila morta". Se uma tarefa falha, ela volta para a fila com espera crescente. Depois de 3 tentativas, fica marcada para eu olhar. Se um worker morre no meio, a tarefa volta sozinha depois de um tempo.
  • Escala até zero. No Kubernetes, o KEDA olha quantas tarefas estão pendentes no banco e liga ou desliga workers. Sem e-mail novo, não tem nada rodando.

No Gmail, usei a API oficial com permissão somente leitura. O sistema nunca apaga nem marca nada na minha caixa. Quem lembra o que já foi processado é o banco.

Na prática, são três jeitos de rodar: um comando só no notebook, um docker compose up ou o deploy em qualquer Kubernetes.

O que eu levo desse projeto

IA é uma peça, não o sistema inteiro. O modelo de embedding faz a triagem e o OCR lê o que é imagem. Quem garante o resultado é uma conta de módulo 10 que existe há décadas. Os melhores sistemas que conheço combinam modelo com regra determinística.

Modelo pequeno resolve muita coisa. Um embedding de 270 milhões de parâmetros e um OCR de 1 milhão, tudo em CPU. Para esse problema não precisei de GPU nem de LLM gigante.

Comece pelo caminho mais barato. Texto do PDF, depois as barras, e só no fim o OCR. A maioria dos boletos se resolve antes de qualquer IA rodar.

E três cuidados que eu não deixaria de fora:

  • Licença. O código do Indra é Apache 2.0, mas os pesos do modelo têm licença própria: liberada para pesquisa, uso pessoal e empresas com menos de US$ 20 milhões de faturamento ou captação. Empresa maior precisa de licença comercial. Leia sempre a licença dos pesos, não só a do código.
  • Dígito válido não é boleto legítimo. Golpista gera boleto com a matemática certinha. Se a ideia for evitar fraude, é preciso conferir beneficiário e banco com uma lista de fornecedores conhecidos.
  • LGPD. E-mail e boleto têm dado pessoal. Criptografia no armazenamento e prazo para apagar os arquivos fazem parte do projeto, não são detalhe.

O código está no meu GitHub, com testes, Docker e o manifesto de Kubernetes. Se você também vive caçando boleto no e-mail, ou se tem uma ideia melhor para alguma dessas etapas, me conta nos comentários. Vou gostar de saber como você resolveria.

📰 Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.