Crawler para pegar dados do CEI 🤑💰💸
Crawler para ler dados do Canal EletrĂ´nico do Investidor
O
cei-crawlerutiliza as seguintes dependências: * cheerio para fazer o parse do HTML. * node-fetch para fazer as requisições * abort-controller para controlar o timeout das requisições * tough-cookie para auxiliar no gerenciamento dos cookies * normalize-html-whitespace para fazer a limpeza do HTML do CEI
Cada instância do
CeiCrawlerroda em um contexto separado, portante Ă© possĂvel realizar operações em usuários diferentes de forma simultânea
Caso o
cei-crawlertenha te ajudado e você queira fazer alguma doação pra me ajudar a mantê-lo, utilize o QR code abaixo :) Mande também seu nome e usuário do GitHub (caso tenha) que eu coloco aqui no README. Obrigado!
Criei o
cei-crawlerpara um projeto de acompanhamento de investimentos. Caso esteja procurando algo nesse sentido, confira o Stoincs!
Basta instalar utilizando o NPM:
npm install --save cei-crawler
Crie uma instância do
CeiCrawlerpassando os parametros necessários e invoque o método desejado:
let ceiCrawler = new CeiCrawler('username', 'password', {/* options */}); ceiCrawler.login(); // Login é opcional, pois antes de cada método o cei-crawler irá verificar se já esta logado. // A vantagem em realizar o login em um passo diferente é para o tratamento de erros
Retorna os dados das carteiras no CEI. As carteiras contém as posições consolidades de ativos e tesouro direto. O retorno será uma lista com cada item representando os dados de uma instituição e conta. O método recebe uma data como parâmetro para pegar a foto das carteiras no dia escolhido. Se nenhuma data for passada, será utilizada a data padrao do CEI que é o dia corrente. O CEI disponibiliza datas somente em um range de 2 meses, aparentemente.
let wallets = await ceiCrawler.getWallet(date);
Resultado:
javascript [ { "institution": "1111 - INTER DTVM LTDA", "account": "111111", "stockWallet": [ { "company": "BANCO INTER", "stockType": "PN N2", "code": "BIDI4", "isin": "BRBIDIACNPR0", "price": 11.43, "quantity": 100, "quotationFactor": 1, "totalValue": 1143 }, { "company": "CENTAURO", "stockType": "ON NM", "code": "CNTO3", "isin": "BRCNTOACNOR5", "price": 29, "quantity": 100, "quotationFactor": 1, "totalValue": 2900 } ], "treasureWallet": [] }, { "institution": "222222 - RICO INVESTIMENTOS - GRUPO XP", "account": "2222222", "stockWallet": [ { "company": "TENDA", "stockType": "ON NM", "code": "TEND3", "isin": "BRTENDACNOR4", "price": 25.14, "quantity": 100, "quotationFactor": 1, "totalValue": 2514 } ], "treasureWallet": [ { "code": "Tesouro IPCA+ 2024", "expirationDate": "2019-06-12T03:00:00.000Z", "investedValue": 1000.00, "grossValue": 1500.00, "netValue": 1400.00, "quantity": 0.25, "blocked": 0 } ] } ]
Retorna as opções dos formulários da página de carteira de ativos
javascript const walletOptions = await ceiCrawler.getWalletOptions();Resultado:
javascript { "minDate": "02/06/2020", "maxDate": "31/07/2020", "institutions": [ { "value": "123", "label": "123 - RICO INVESTIMENTOS - GRUPO XP", "accounts": [ "12345" ] }, { "value": "321", "label": "321 - INTER DTVM LTDA", "accounts": [ "54321" ] } ] }
MĂ©todo que processa o histĂłrico e o resumo do histĂłrico de compra e venda de ações. O retorno será um uma lista com todas operações de compra ou venda efetuadas dentro do perĂodo informado, se nenhuma data for passada o mĂ©todo retornará todo o histĂłrico disponĂvel.
javascript let stockHistory = await ceiCrawler.getStockHistory(startDate, endDate);Resultado:
javascript [ { institution: 'Banco Inter', account: 12345, stockHistory: [ { date: "2019-06-12T03:00:00.000Z", operation: "C", // C (Compra) ou V (Venda), market: "Mercado a Vista", expiration: "", code: "BTOW3", name: "B2W DIGITAL ON NM", quantity: 200, price: 32.2, totalValue: 6440, cotation: 1 } ] } ]
Retorna as opções dos formulários da página de negociações de ativos
javascript const stockHistoryOptions = await ceiCrawler.getStockHistoryOptions();Resultado:
javascript { "minDate": "08/02/2019", "maxDate": "31/07/2020", "institutions": [ { "value": "123", "label": "123 - RICO INVESTIMENTOS - GRUPO XP", "accounts": [ "12345" ] }, { "value": "321", "label": "321 - INTER DTVM LTDA", "accounts": [ "54321" ] } ] }
MĂ©todo que processa todos os dados disponĂveis sobre proventos recebidos em um perĂodo e retorna como uma lista. Usualmente os proventos disponĂveis na página do CEI sĂŁo os creditados no mĂŞs atual e os já anunciados pela empresas com e sem data definida. Registros com date igual
nullsĂŁo de proventos anunciados mas sem data definida de pagamento.
javascript let dividends = await ceiCrawler.getDividends(date);Resultado:
javascript [ { "institution": "1099 - INTER DTVM LTDA", "account": "12345", "futureEvents": [ { "stock": "BANCO INTER", "stockType": "PN N2", "code": "BIDI4", "date": "2020-08-20T03:00:00.000Z", "type": "JUROS SOBRE CAPITAL PRÓPRIO", "quantity": 200, "factor": 1, "grossValue": 7.88, "netValue": 5.8 }, { "stock": "CIA HERING", "stockType": "ON NM", "code": "HGTX3", "date": null, "type": "JUROS SOBRE CAPITAL PRÓPRIO", "quantity": 100, "factor": 1, "grossValue": 21.96, "netValue": 18.67 }, ], "pastEvents": [ { "stock": "ITAUSA", "stockType": "PN N1", "code": "ITSA4", "date": "2020-07-01T03:00:00.000Z", "type": "DIVIDENDO", "quantity": 300, "factor": 1, "grossValue": 6, "netValue": 6 } ] }, { "institution": "386 - RICO INVESTIMENTOS - GRUPO XP", "account": "12345", "futureEvents": [], "pastEvents": [ { "stock": "FII CSHG LOG", "stockType": "CI", "code": "HGLG11", "date": "2020-07-14T03:00:00.000Z", "type": "RENDIMENTO", "quantity": 100, "factor": 1, "grossValue": 78, "netValue": 78 } ] } ]
Retorna as opções dos formulários da página de proventos
javascript const dividendsOptions = await ceiCrawler.getDividendsOptions();Resultado:
javascript { "minDate": "27/07/2020", "maxDate": "31/07/2020", "institutions": [ { "value": "123", "label": "123 - RICO INVESTIMENTOS - GRUPO XP", "accounts": [ "12345" ] }, { "value": "321", "label": "321 - INTER DTVM LTDA", "accounts": [ "54321" ] } ] }
MĂ©todo que processa todos os dados disponĂveis sobre Tesouro Direto em um perĂodo e retorna como uma lista e tambĂ©m uma lista das transações.
javascript let treasures = await ceiCrawler.getTreasures(date);Resultado:
javascript [ { "institution": "3 - XP INVESTIMENTOS CCTVM S/A", "account": "123456", "treasures": [ { "code": "Tesouro IPCA+ 2045", "expirationDate": "2045-05-15T03:00:00.000Z", "investedValue": 12.34, "grossValue": 13.43, "netValue": 10.12, "quantity": 0.01, "blocked": 0, "transactions": [ { "tradeDate": "2020-11-27T03:00:00.000Z", "quantity": 0.01, "price": 1234.56, "notional": 12.34, "profitability": "IPCA + 4,05%", "grossProfitability": "IPCA + 566,89%", "grossProfitabilityPercent": 12.34, "grossValue": 45.67, "investmentTerm": 18, "taxBracket": 23.4, "taxIrValue": 0.12, "taxIofValue": 1.94, "feeB3Value": 0, "feeInstitutionValue": 0, "netValue": 42.67 } ] } ] } ]
Retorna as opções dos formulários da página de tesouro direto
javascript const treasureOptions = await ceiCrawler.getTreasureOptions();Resultado:
javascript { "institutions": [ { "value": "123", "label": "123 - RICO INVESTIMENTOS - GRUPO XP", "accounts": [ "12345" ] }, { "value": "321", "label": "321 - INTER DTVM LTDA", "accounts": [ "54321" ] } ] }
Na criação de um
CeiCrawleré possivel especificar alguns valores para o parâmetro
optionsque modificam a forma que o crawler funciona. As opções são:
| Propriedade | Tipo | Default | Descrição | |-----------------------|-----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | capDates | Boolean | false | Se
true, as datas utilizadas de input para buscas serão limitadas ao range de datas válidas do CEI, impedindo que ocorra um erro caso o usuário passe uma data maior ou menor. | | navigationTimeout | Number | 30000 | Tempo, em ms, que o crawler espera por uma ação antes de considerar timeout. | | loginTimeout | Number | 180000 | Tempo, em ms, que o crawler espera para realizar login antes de considerar timeout. Diversas vezes, como a noite e aos fins de semana, o sistema do CEI parece ficar muito instavél e causa diversos timeouts no login. | | trace | Boolean | false | Printa mensagens de debug no log. Útil para desenvolvimento. |
Exemplo:
const ceiCrawlerOptions = { trace: false, capEndDate: true, navigationTimeout: 60000, loginTimeout: 240000,};
let ceiCrawler = new CeiCrawler('username', 'password', ceiCrawlerOptions);
O CEI Crawler possui um exceção própria,
CeiCrawlerError, que é lançada em alguns cenários. Essa exceção possui um atributo
typepara te direcionar no tratamento:
| type | Descrição | |----------------|---------------------------------------------------------------------------------------------------------------------------| | LOGINFAILED | Lançada quando o login falha por timeout ou por CPF errado digitado | | WRONGPASSWORD | Lançada quando a senha passada está errada | | SUBMITERROR | Lançada quando acontece um erro ao submeter um formulario de pesquisa em alguma página do CEI. Por exemplo: data inválida | | SESSIONHASEXPIRED | Lançada quando a sessão do usuário expira, nesse caso é necessário realizar o login novamente
ceiCrawler.login()| | NAVIGATIONTIMEOUT | Lançada quando a requisição estoura o tempo limite definida na opção
navigationTimeout|
Exemplo de como fazer um bom tratamento de erros:
const CeiCrawler = require('cei-crawler'); const { CeiErrorTypes } = require('cei-crawler')const ceiCrawler = new CeiCrawler('usuario', 'senha', { navigationTimeout: 20000 });
try { const wallet = ceiCrawler.getWallet(); } catch (err) { if (err.name === 'CeiCrawlerError') { if (err.type === CeiErrorTypes.LOGIN_FAILED) // Handle login failed else if (err.type === CeiErrorTypes.WRONG_PASSWORD) // Handle wrong password else if (err.type === CeiErrorTypes.SUBMIT_ERROR) // Handle submit error else if (err.type === CeiErrorTypes.SESSION_HAS_EXPIRED) // Handle session expired else if (err.type === CeiErrorTypes.NAVIGATION_TIMEOUT) // Handle request timeout } else { // Handle generic errors } }
MIT