CEI Wrapper

This library is a NodeJS wrapper that expose an modern API for CEI service.

The project exploits CEI's "New Logon Area" which now has a captcha for login 🙄 CeiWrapper has integration with the anti-captcha to solve the problem (If there is a need in the future we can implement support for similar services like 2captcha)

Please keep in mind that this is a work in progress. Pull requests welcome!

Features

Use the new CEI's API.
Support anti-captcha to solve login.
Written in TypeScript.
Easy to use with an elegant API.

How to works

To instantiate CeiWrapper we need an authentication context, something like this

const authenticateContext = {
  cacheId: "f8f7cac9-5b99-4160-94ae-eddd5dd2218",
  token: "eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiZmFr....",
};

To achieve this we can use the static authenticateUser method

const authenticateContext = await CeiWrapper.authenticateUser({
  captchaSolvingServiceKey: "Your Key",
  username: "CEI's User",
  password: "CEI's Pass",
});

This is useful because the token generated by CEI has a lifetime of about 1h, so we can store these credentials in Redis or any other caching asset for example and be able to make several calls without having to authenticate again (and saving the cost of resolving the captcha) 🎉

With the credentials in hand we can begin the work

const ceiWrapper = new CeiWrapper(authenticateContext);

const result = await ceiWrapper.getConsolidatedValues();

All methods use a standardized response for both success and error. e.g.

ResultError {
  isError: true;
  status: 0;
  errorMessage: "Error Message";
}

ResultSuccess {
  isError: false,
  status: 1,
  data: <data_from_CEI>
}

you can see a complete example here

Documentation

getConsolidatedValues()

Returns the consolidated investments in a total amount and divided into subcategories

ResultSuccess.data:

{
  "total": "1000.50",
  "values": [
    {
      "product": "Renda Variável",
      "totalAmount": "600.54",
      "percentage": "0.607"
    },
    {
      "product": "Tesouro Direto",
      "totalAmount": "300.92",
      "percentage": "0.393"
    }
  ]
}

getInvestments(date?, page?)

Returns the investments with details divided into categories

Argument	Type	Description
`date`	Date	Position date. By default use the last processing date of the CEI.
`page`	Number	Data paging. By default returns the first page.

ResultSuccess.data:

{
  "currentPage": 1,
  "totalPages": 1,
  "types": [
    {
      "category": "RendaVariavel",
      "name": "Acao",
      "products": VariableIncomeProduct[],
      "totalAmount": 111.07
    },
    {
      "category": "TesouroDireto",
      "name": "TesouroDireto",
      "products": FixedIncomeProduct[],
      "totalAmount": 224.1
    }
  ]
}

VariableIncomeProduct example

{
  "company": "AMBEV S.A.",
  "code": "ABEV3",
  "type": "ON",
  "amount": 10,
  "price": 16.13,
  "exchange": "CLEAR CORRETORA - GRUPO XP",
  "exchangeId": "02332886001178",
  "bookkeeper": "BANCO BRADESCO S/A",
  "available": 10
},

FixedIncomeProduct example

{
  "name": "Tesouro Selic 2023",
  "index": "SELIC",
  "expirationSate": "2023-03-01T03:00:00.000Z",
  "amount": 0.56,
  "initialValue": 530.23,
  "currentValue": 615.94,
  "netValue": 604.39,
  "initialProfitability": 0.01,
  "exchange": "XP INVESTIMENTOS CCTVM S/A",
  "exchangeId": "02332886000104",
  "available": 0.56
},

Warning! The price or the currentValue are from the last processing date of the CEI.

New methods are coming...

Debugging

If you find any strange behavior you can turn on the logs to find out what might be going on. To turn on the logs just pass as second parameter an options object with a property debug = true. e.g

const ceiWrapper = new CeiWrapper(authenticateContext, { debug: true });

// or

const authenticateContext = await CeiWrapper.authenticateUser(
  {
    // authentication params
  },
  { debug: true },
);

this will start logging everything the lib is doing, following example

{"context":{},"level":"info","datetime":"2021-09-21T15:23:53.871Z","message":"LoggerService.info(): Executing http request","extra":{"options":{"url":"https://investidor.b3.com.br/api/sistema/v1/carga/ultima-execucao","method":"GET","headers":{"Authorization":"*sensitive*"}

{"context":{},"level":"error","datetime":"2021-09-21T15:50:45.536Z","message":"LoggerService.error(): The http request result in a status code 4xx or 5xx","extra":{"options":{"url":"https://investidor.b3.com.br/api/sistema/v1/carga/ultima-execucao","method":"GET","headers":{"Authorization":"*sensitive*"},"params":{"cache-guid":"8de6e874-d5e8-45dc-8328-f31f2d29bfed"}},"error":"Request failed with status code 429"}}

{"context":{},"level":"error","datetime":"2021-09-21T15:50:45.542Z","message":"LoggerService.error(): Fail to fetch the latest processing dates from CEI","extra":{"response":{"isError":true,"status":0,"errorMessage":"Failed to fetch request"}}}

making it easier to understand what is going on

Autor

Made by Michael Santillán (Mike) 👋🏽 Say Hi!

mikejavier / cei-wrapper