cei-crawler 💸

Crawler para ler dados do Canal Eletrônico do Investidor

Descrição

O cei-crawler utiliza o puppeteer para fazer o scrapping das informações do usuário. Para isso, basta criar uma instância do CeiCrawler e chamar os métodos necessários.

Instalação

Basta instalar utilizando o NPM:

npm install --save cei-crawler

Utilização

Crie uma instância do CeiCrawler passando os parametros necessários e invoque o método desejado:

let ceiCrawler = new CeiCrawler('username', 'password', {/* options */});

Métodos disponíveis

getWallet

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 3 meses, aparentemente.

let wallets = await ceiCrawler.getWallet(date);

Resultado:

[
  {
    "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
      }
    ]
  }
]

getStockHistory

Método que processa o 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.

let stockHistory = await ceiCrawler.getStockHistory(startDate, endDate);

Resultado:

[
    {
        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
            }
        ]
    }
]

getDividends

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 a 2001-01-01 são de proventos anunciados mas sem data definida de pagamento.

let dividends = await ceiCrawler.getDividends();

Resultado:

[
  {
    stockType: 'ON NM',
    code: 'EGIE3',
    date: 2001-01-01T02:00:00.000Z,     
    type: 'JUROS SOBRE CAPITAL PRÓPRIO',
    quantity: 70,
    factor: 1,
    grossValue: 30.03,
    netValue: 20.58
  },
  {
    stockType: 'PN EDJ N1',
    code: 'ITSA4',
    date: 2020-04-01T03:00:00.000Z,
    type: 'DIVIDENDO',
    quantity: 450,
    factor: 1,
    grossValue: 9.9,
    netValue: 9.9
  }
]

close

O método close deve ser chamado quando é terminado o processamento dos dados e a instancia do CeiCrawler não será reutilizada em um curto espaço de tempo. Esse método simplesmente fecha o browser do puppeteer, liberando memória. Exemplos do comportamento:

// Ambas as chamadas são executadas numa mesma janela do browser, somente um login é feito
let stockHistory = await ceiCrawler.getStockHistory(startDate, endDate);
let dividends = await ceiCrawler.getDividends();
await ceiCrawler.close();

// Se intercalarmos chamadas ao método close entre os métodos, o login é realizado duas vezes
let stockHistory = await ceiCrawler.getStockHistory(startDate, endDate); // Abre browser, faz login e pega o histórico
await ceiCrawler.close(); // Fecha o browser

let dividends = await ceiCrawler.getDividends(); // Abre novamente, faz login e pega os dividendos
await ceiCrawler.close(); // Fecha o browser

Opções

Na criação de um CeiCrawler é possivel especificar alguns valores para o parâmetro options que modificam a forma que o crawler funciona. As opções são:

Propriedade	Tipo	Default	Descrição
puppeteerLaunch	Object	{}	Esse objeto é passado ao método launch do Puppeteer. As opções estão listadas aqui.
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. Diversas vezes, como a noite e aos fins de semana, o sistema do CEI parece ficar muito instavél e causa diversos timeouts.
trace	Boolean	false	Printa mensagens de debug no log. Útil para desenvolvimento.

Exemplo:

const ceiCrawlerOptions = {
    puppeteerLaunch: {
        headless: false,
        timeout: 0
    },
    trace: false,
    capEndDate: true
};

let ceiCrawler = new CeiCrawler('username', 'password', ceiCrawlerOptions);

Error Handling

O CEI Crawler possui um exceção própria, CeiCrawlerError, que é lançada em alguns cenários. Essa exceção possui um atributo type para te direcionar no tratamento:

type	Descrição
LOGIN_FAILED	Lançada quando o login falha por timeout ou por CPF errado digitado
WRONG_PASSWORD	Lançada quando a senha passada está errada

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.name === 'TimeoutError') {
    // Handle timeout after 'navigationTimeout'
  }
}

Features

• Histórico de ações
• Dividendos
• Carteira de ações
• Tesouro Direto

Licença

MIT