Autonomia & Tecnologia

Libertando os dados bancários

Uma biblioteca, que com apenas um comando, ajuda você a baixar seus extratos da conta corrente e do cartão de crédito do Itaú.

18

As APIs vieram para ficar, mas a maioria dos bancos ainda não oferecem forma fácil para seus clientes extraírem seus próprios dados. Algo tão simples quanto obter o seu extrato bancário é um sofrimento para automatizar.

Pesquisando se existia algo pronto para o Itaú, encontrei o bankscraper do Kamus que disponibiliza vários scripts interessantes. Infelizmente o do Itaú não estava mais funcionando, mas estudando seu código encontrei uma boa dica:

O site do Itaú para desktop é todo complicado para navegar cheio de mágicas em javascript. Mas e o site para disponsitivos móveis?

Ativei o “mobile mode” do Chrome com o Postman e o Postman Interceptor para rastrear todas as requisições e bingo. De fato é bem mais simples.

O resultado dessa exploração foi o Itauscraper, uma biblioteca para baixar seus extratos da conta corrente e do cartão de crédito do Itaú com apenas um comando.

O Design

Inicialmente meu objetivo era apenas resolver o meu problema o mais rápido possível. Mas após fazer funcionar, decidi revisitar o código e fazer direito para compartilhar com você o código e uma visão de futuro.

Neste outro artigo eu explico o processo de fazer funcionar, fazer direito e fazer ficar rápido.

Mas neste caso, o que é exatamente fazer direito? São as decisões de design do projeto:

  • Deve ser instalável como um simples pip install.
  • Deve funcionar na linha de comando como um programa unix qualquer.
  • Na linha de comando deve dar saída em CSV e humanizada em tabelas.
  • Deve ter uma API simples para importar o scraper em outro script ou projeto.
  • Deve proporcionar fácil manutenção mantendo o código objetivo refletindo a sequência de passos imposta pelo site do banco.
  • Deve internalizar todas as conversões necessárias retornando sempre objetos Python. Nada de datas como string e números como float!
  • Deve documentar bem o funcionamento permitindo que outras pessoas corrijam e adicionem novas funcionalidades a partir do que já existe.

Além disso eu acredito que o scraper deva ser específico para um site de um banco, evitando a tentação de criar um ”one ring to rule them all” que na prática tornará mais lenta a evolução da solução.

Pensei neste design para servir de inspiração para os outros scrapers e conversores que pretendo desenvolver para libertar meus dados das instituições financeiras. Na minha mira estão instituições como:

A ideia é que cada projeto seja simplesmente o nome da instituição seguido pelo sufixo scraper. Simples assim. 😉

Se você tem interesse em fazer para algum desses ou qualquer outro, deixe um comentário no fim deste artigo e bora conversar!

O Desafio

O protocolo HTTP é stateless exigindo que cada requisição envie novamente todas as informações necessárias.

No entanto, o site do banco cria uma dinâmica cliente-servidor estabelecendo dependência entre as requisições mudando inclusive as urls de navegação.

Por isso todo o processo acontece sequencialmente, cheio de etapas intermediárias que não seriam necessárias em condições normais de uso do protocolo HTTP.

O Itauscraper funciona apenas para contas Pessoa Física, pois o Itaú força empresas a usarem seu aplicativo no celular não dando acesso ao site móvel pelo navegador.

Como funciona

O código é simples e usa Python 3 com a biblioteca requests para a navegação e lxml processando o html com xpath, evitando grandes lógicas de extração de dados.

Usando o requests.Session conseguimos reproduzir o efeito de navegação contínua entre várias páginas propagando cookies e outros http headers.

A classe MobileSession implementa os cabeçalhos para sermos reconhecidos como um browser de celular.

A classe ItauScraper usa a session para executar toda a lógica de navegação auxiliada pelas Pages que sabem como extrair os dados das páginas.

Mais do que explicar o código em si, o importante é entender o fluxo de navegação que ele precisa reproduzir.

O Login

Para fazer o login no site do banco é preciso acessar uma url inicial para descobrirmos a url de login correta, que muda de tempos em tempos.

Com a url de login correta, agora é preciso fazer um novo GET para obter informações que o ASP.NET injeta no formulário de login e então realizar o POST efetuando a autenticação.

Depois do login feito, somos redirecionados para uma página com um menu de navegação. Esta página não é usada diretamente no fluxo, mas quando quisermos implementar novas funcionalidades no ItauScraper é nela que deveremos começar.

Página de login do itau

O Extrato da Conta

Quando acessamos a url do extrato, por padrão é exibido o extrato dos últimos 3 dias. No fim da página do extrato tem 4 links para listar os extratos dos períodos 7, 15, 30 e 90 dias. Estas urls parecem mudar de tempos em tempos, como a do login, então é preciso extrair o link para 90 dias e obter o extrato com outro GET.

primeira tela mostrando dados bancarios

Com o extrato do período de 90 dias:

  1. Extraímos a informação do html;
  2. Reconstruímos a tabela com as colunas: data, descrição e valor;
  3. Filtramos as linhas de saldo que não correspondem a um lançamento;
  4. Convertemos cada data para o tipo datetime.date;
  5. Convertemos cada valor para o tipo Decimal;

No final, temos uma tupla de tuplas na forma:

O Extrato do Cartão

Quando acessamos a url do cartão, são exibidas 3 opções para listar:

  1. a fatura anterior;
  2. a fatura atual;
  3. os lançamentos parciais da próxima fatura.

Estas urls mudam de tempos em tempos, então é preciso extrair o link para a fatura atual e realizar um novo GET para obter o extrato de lançamentos da fatura.

tela mostrando o extrato do cartao

Além dos lançamentos, a página tem um resumo com totais.

Com o extrato da fatura atual do cartão:

  1. Extraímos a informação do html;
  2. Reconstruímos o resumo como um dicionário.
  3. Reconstruímos a tabela com as colunas: data, descrição e valor;
  4. Convertemos cada data para o tipo datetime.date;
  5. Convertemos cada valor para o tipo Decimal;

No final, temos um dicionário com o sumário da fatura e uma tupla de tuplas na forma:

Como usar

Instale o Itauscraper com o comando:

Então use pela linha de comando:

Ou importe direto no seu código:

Próximos passos

Meu plano é criar bibliotecas específicas para libertar os dados que estão presos nas instituições financeiras.

É preciso reduzir a energia dedicada aos inputs , para focar no output que é onde faremos o que importa: tomar melhores decisões estratégicas.

O que você acha da ideia? Anima em contribuir? Deixa aí seu comentário dizendo que tipo de informação financeira é importante pra você? Qual instituição você tem interesse em automatizar? Liste aí os projetos que você conhece que se propõe a algo parecido.

Bora hackear!

Abração, HB!

você pode gostar também
  • Anderson Marques

    Fala Henrique, muito Massa a tua ideia.
    Eu me interessei em participar, mas não sou o cara mais sáfo em python, então se tu quiser
    ser meu orientador eu aceito o desafio :D.

    Quero fazer o scraper para o banco do brasil, que é o meu banco e muito me interessa essa liberdade, quer dizer, isso se você já não começou ou sabe de alguém que
    já iniciou.

    E Parabéns.

    • Falaê, @disqus_6JJSZ5z8GT:disqus! Sensacional! Chega mais! 😀

      Acho que o 1º passo é estudar a estrutura do internet banking do BB pra encontrarmos um caminho possível.

      O Bankscraper do Kamus tem um script para BB. Tenta rodar pra ver se ainda tá funcionando. Daí a gente empacota direitinho pra facilitar a parada. 😉

      https://github.com/kamushadenes/bankscraper

      • Anderson Marques

        BLZ,
        vou testar o script do Kamus e ver se tá funcionando ainda.
        😀

  • kneipp

    Henrique Bastos : Uber = Instituições : Táxis

  • Cleiton Junior Mittmann

    É excelente essa ideia de automatizar ou mesmo facilitar a coleta de SEUS dados, tendo em vista a dificuldade em obter pela interface oficial (acessar o internet banking, sair navegando pelos menus confusos até chegar ao dado não formatado) ou até mesmo ter uma informação mais útil para VOCÊ.
    Recentemente montei um script que coleta dados do portal do investidor CEI, mas utilizei o Selenium com lxml.

    • Sensacional, @cleitonjuniormittmann:disqus! Tem como colocar no Github?

      Sim, eu decidi focar nos meus dados porque no fundo, todo mundo tá afim de te separar dos seus dados. De um lado as instituições financeiras e o governo não fornecem informações do jeito fácil. Do outro tem uma fila de iniciativas que “te ajudam” coletando os seus dados com a sua permissão e trancando da mesma forma tipo o que faz o Guia Bolso.

      Eu quero criar soluções que coloquem a pessoa, o dono dos dados, no centro do processo.

  • Clayton

    Achei excelente as decisões de design do projeto. Em vez de criar uma grande solução que engloba todas as instituições financeiras, criar micro-soluções fáceis de serem reutilizadas. Parabéns.

    • Valeu, Clayton! Isso mesmo! O foco é baixar o custo de manutenção, facilitar a entrada de novos colaboradores e oferecer um “design padrão” que pode ser facilmente adaptado pra outros bancos. 😉

  • Muito foda. Esses projetos juntam duas coisas que eu curto demais: scrapers e informações financeiras. Tenho muito interesse em participar dos próximos.
    Certo que vou colocar o Itauscraper para rodar diariamente e alimentar minha planilha de gastos.

    Para Nubank é mais fácil, pois eles já disponibilizam uma API (não documentada) retornando JSON (https://twitter.com/nubankbrasil/status/766665014161932288) com as informações das transações. Já tem até um projeto parecido em Python: https://github.com/andreroggeri/pynubank

    • Show de bola, @lucas_rangel_cezimbra:disqus! Bora fazer essas ferramentas todas. Uma coisa que andei pensando seria tentar monitorar a comunicação que rola entre o app dos bancos e seus servidores tentando fazer uma engenharia reversa nas APIs e fazer um scrapper a partir disso. Mas foi só um pensamento até agora. Já viu algo assim?

    • Acabei de dar uma olhada no pynubank. Bem massa!

      Vi que vc contribuiu. Eu escrevi este post pra enfatizar as minhas exigências do design das bibliotecas que botei logo no início. O que vc acha dessa visão? Será que tem espaço no pynubank pra alinharmos isso?

      • Achei muito bom o design que você propôs. Acredito que seja possível alinhar com o pynubank sim.

        Outra ideia que tive foi usar o tapioca (https://github.com/vintasoftware/tapioca-wrapper) já que o Nubank tem uma API que retorna JSON.

      • Masa! Eu pensei nisso tb. Eu acho que um tapioca-nubank merece existir, mas não substitui o pynubank ou um nubankscrapper. Eles usariam o wrapper trazendo os princípios de design que levantei no post.

  • Rael Max

    Muito bom, Henrique! Na parte que você diz “O protocolo HTTP é assíncrono exigindo que cada requisição envie novamente todas as informações necessárias” acredito que você quis dizer que o protocolo HTTP é Stateless, essa é a característica que faz com que dados do estado sejam guardados e reenviados pelo cliente em cada requisição.

    Achei bem foda a biblioteca e a explicação detalhada de como usar! 🙂