Finerio-pfm-unnax NPM

Finerio PFM Web SDK

This SDK lets you connect to Finerio PFM API Unnax in an easier way.

Installation

NPM:

npm i finerio-pfm-unnax

Setup

import { FinerioConnectSDK } from "finerio-pfm-unnax";
import { CATEGORY_TYPE, TRANSACTION_TYPE } from "finerio-pfm-unnax";

//The constructor can receive an object as parameter specifying in the includes key the SDK instances you want to use as an array of types or a single type, depending on which SDK instances you want to use and in sandbox key the environment to use.
//If serverUrl is not specified sandbox url will be used.
//If constructor has no parameters all the SDK instances will be returned and sandbox url will be used.
const fcPfm = new FinerioConnectSDK({
  includes: [CATEGORY_TYPE, TRANSACTION_TYPE],
  serverUrl: "https://unnax-gateway.finerioconnect.com/",
});

//Call the login method to obtain the object(s) with the previously established instances.
const headers = { Authorization: "isnjsbfyuw" };
fcPfm
  .login(username, password, clientId, headers)
  .then(({ Categories, Transactions }) => {
    ...
  })
  .catch((error) => console.log(error));


//In the other hand you can call the connect passing AuthToken method to obtain the object(s) with the previously established instances.
const { Categories, Transactions } = fcPfm.connect(AUTH_TOKEN);

The following constant types can be used: | Instance Types | Instance returned when you connect | | --------------------- | ---------------------------------- | | ACCOUNT_TYPE | Accounts | | CATEGORY_TYPE | Categories | | TRANSACTION_TYPE | Transactions | | BUDGET_TYPE | Budgets | | INSIGHTS_TYPE | Insights | | FINANCIAL_ENTITY_TYPE | FinancialEntities |

Usage

Finerio PFM Web uses Promises to fetch responses from the API.

Accounts

An account is the representation of your users' bank accounts.

List Accounts

Fetches a list of accounts per user, sorted by ID in descending order.

Accounts.list(id)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

The list starts with the item that has that ID.

Output:

[
  Account {
    userId: 41,
    id: 2230303,
    providerId : "45454",
    financialEntityId: 103,
    dateCreated: 1646243107260,
    lastUpdated: 1646243107260,
    nature: "Mortgage",
    name: "nas",
    number: "1234126312341234",
    balance: 100,
    chargeable: false,
    extra_data: {
      last_update: '2022-11-09T16:10:20+00:00',
      credit_limit: '16680000',
      minimum_payment: '208500',
      payment_due_date: '2022-11-28',
      active: 'true',
      type: '1'
    }
  },
  Account {
    userId: 41,
    id: 2230304,
    providerId : "7898",
    financialEntityId: 103,
    dateCreated: 1645212332784,
    lastUpdated: 1645212433106,
    nature: "Investment",
    name: "Investment Account",
    number: "0277",
    balance: 251.03,
    chargeable: false
  }
  ...
]

Get Account

Given a valid account ID, fetches the information of an account.

Accounts.get(accountId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Account {
  userId: 41,
  id: 2230303,
  providerId : "9878",
  financialEntityId: 103,
  dateCreated: 1646243107260,
  lastUpdated: 1646243107260,
  nature: "Mortgage",
  name: "nas",
  number: "1234126312341234",
  balance: 100,
  chargeable: false,
  extra_data: {
    last_update: '2022-11-09T16:10:20+00:00',
    credit_limit: '16680000',
    minimum_payment: '208500',
    payment_due_date: '2022-11-28',
    active: 'true',
    type: '1'
  }
},

Create Account

Creates an account. A previosuly created user and a financial entity is required. You have to import the Account Payload Model to create a new one.

import { Account } from "finerio-pfm-unnax";

...
const financialEntityId = 1115164;
const nature = "Mortgage",;
const name = "Cuenta prueba",;
const number = "1111 1111 1111 1111",;
const balance = 1000;
const account = new Account(
        financialEntityId,
        nature,
        name,
        number,
        balance
      );

Accounts.create(account)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Account {
  userId: 41,
  id: 2230303,
  financialEntityId: 103,
  dateCreated: 1646243107260,
  lastUpdated: 1646243107260,
  nature: "Mortgage",
  name: "Cuenta prueba",
  number: "1111 1111 1111 1111",
  balance: 1000,
  chargeable: false
}

Update Account

Updates an account. You have to import the Account Payload Model to update it.

import { Account } from "finerio-pfm-unnax";

...

const financialEntityId = 1115164;
const nature = "Mortgage",;
const name = "Cuenta prueba 2",;
const number = "1111 1111 1111 1111",;
const balance = 1000;
const account = new Account(
        financialEntityId,
        nature,
        name,
        number,
        balance
      );

Accounts.update(accountId, account)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Account {
  userId: 41,
  id: 2230303,
  financialEntityId: 103,
  dateCreated: 1646243107260,
  lastUpdated: 1646243107260,
  nature: "Mortgage",
  name: "Cuenta prueba 2",
  number: "1111 1111 1111 1111",
  balance: 1000,
  chargeable: false
}

Delete Account

Deletes an account and all its information, including transactions.

Accounts.delete(accountId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

If the account was deleted code 204 will be returned.

List Categories

Fetches a list of categories, sorted by ID in ascending order. The API is able to fetch up to 100 categories.

Categories.list()
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Categories are fetched.

Output:

[
  Category {
    id: 1,
    name: 'Hogar',
    color: '#A3CB38',
    parentCategoryId: null,
    userId: null,
    imagePath: 'https://cdn.finerio.mx/pfm/categories/1.svg',
    dateCreated: null,
    lastUpdated: null
  },
  Category {
    id: 2,
    name: 'Alimentos',
    color: '#FECA46',
    parentCategoryId: null,
    userId: null,
    imagePath: 'https://cdn.finerio.mx/pfm/categories/2.svg',
    dateCreated: null,
    lastUpdated: null
  },
  Category {
    id: 1024,
    name: 'Teléfono',
    color: '#A3CB38',
    parentCategoryId: 2,
    userId: null,
    imagePath: 'https://cdn.finerio.mx/pfm/categories/default.svg',
    dateCreated: null,
    lastUpdated: null
  },
  Category {
    id: 1032,
    name: 'Lavandería',
    color: '#0000FF',
    parentCategoryId: null,
    userId: 41,
    imagePath: 'https://cdn.finerio.mx/pfm/categories/default.svg',
    dateCreated: null,
    lastUpdated: null
  },
  ...
]

List Categories And Subcategories

Fetches a list of categories, sorted by ID in ascending order grouped by parent category and subcategories. The API is able to fetch up to 100 categories.

Categories.listWithSubcategories()
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Categories grouped by subcateogires are fetched.

Output:

[
  ParentCategory {
    id: 1,
    name: 'Hogar',
    color: '#A3CB38',
    parentCategoryId: null,
    userId: null,
    imagePath: 'https://cdn.finerio.mx/pfm/categories/1.svg',
    dateCreated: null,
    lastUpdated: null,
    subcategories: [
      [Category], [Category],
      [Category], [Category],
      [Category], [Category],
      [Category], [Category],
      [Category]
    ]
  },
  ParentCategory {
    id: 2,
    name: 'Alimentos',
    color: '#FECA46',
    parentCategoryId: null,
    userId: null,
    imagePath: 'https://cdn.finerio.mx/pfm/categories/2.svg',
    dateCreated: null,
    lastUpdated: null,
    subcategories: [ [Category], [Category], [Category] ]
  },
  ParentCategory {
    id: 1032,
    name: 'Lavandería',
    color: '#0000FF',
    parentCategoryId: null,
    userId: 41,
    imagePath: 'https://cdn.finerio.mx/pfm/categories/default.svg',
    dateCreated: null,
    lastUpdated: null,
    subcategories: [ [Category], [Category], [Category] ]
  },
  ...
]

Get Category

Given a valid category ID, fetches the information of a category.

const categoryId = 27;
Categories.get(userId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Category {
  id: 27,
  name: 'Otros Auto y Transporte',
  color: '#99ECD8',
  parentCategoryId: 5,
  userId: 41,
  imagePath: 'https://cdn.finerio.mx/pfm/categories/27.svg',
  dateCreated: 1662592896338,
  lastUpdated: 1662592896338
}

Create Category

Creates a category. If a user ID is not specified, the category is considered as a system category. If a parent category ID is specified, the category is considered a subcategory. You have to import the Category Payload Model to update it.

import { Category } from "finerio-pfm-unnax";

...
const name = "Streaming";
const color = "#FF0000";
const parentCategoryId = 1859616;
const category = new Category(name, color, parentCategoryId, [userId]);

Categories.create(category)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Category {
  id: 1859620,
  name: 'Streaming',
  color: '#FF0000',
  parentCategoryId: 1859616,
  userId: 41,
  imagePath: 'https://cdn.finerio.mx/pfm/categories/default.svg',
  dateCreated: 1647380144534,
  lastUpdated: 1647380144534
}

Update Category

Given a valid category id updates a category. You have to import the Category Payload Model to update it.

import { Category } from "finerio-pfm-unnax";

...
const name = "Streaming Test";
const color = "#00FF00";
const parentCategoryId = null;
const category = new Category(name, color, parentCategoryId);

Categories.create(category)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Category {
  id: 1859621,
  name: 'Streaming Test',
  color: '#00FF00',
  parentCategoryId: null,
  userId: 41,
  imagePath: 'https://cdn.finerio.mx/pfm/categories/default.svg',
  dateCreated: 1647380312266,
  lastUpdated: 1647380312266
}

Delete Category

Given a valid category id deletes a category.

const categoryId = 1859621;
Categories.delete(categoryId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

If the category was deleted code 204 will be returned.

Transactions

A transaction is the representation of the financial movements within an account.

List Transactions

Fetches a list of transactions per account, sorted by ID in descending order.

Transactions.list([options])
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

If an options object is specified, the list is filtered based on the added properties.

The following properties can be used: | Name | Type | Example | Description | | --------------------- | ---------------------------------- | ---------------------------------- |---------------------------------- | | accountIds | array | number | accountIds=123&accountIds=456 | An array with the IDs of the accounts or the ID of the account. | | categoryId | integer | categoryId=123 | The ID of the category. | | description | string | description=UBER | The description of the transaction. It can be partial. | | charge | boolean | charge=true | The type of the transaction (true = charge, false = deposit) | | minAmount | number | minAmount=123.45 | The minimum amount of the transaction. | | maxAmount | number | maxAmount=123.45 | The maximum amount of the transaction. | | dateFrom | number | dateFrom=1587567125458 | The minimum date of the transaction, in UNIX format. | | dateTo | number | dateTo=1587567125458 | The maxumum date of the transaction, in UNIX format. | | page | integer | page=2 | The Number of page where the list starts. | | size | integer | size=100 | It is the number of transactions that will be displayed in the list. | | field | string | field=executionDate | The field by which the ordering of transactions will be applied. | | order | string | order=desc | ThIndicates if the order of the list will be ascending(asc) or descending(desc). |

Output:

{
  transactions: [
    Transaction {
      id: 123,
      date: 1587567125458,
      charge: true,
      description: "UBER EATS",
      amount: 1234.56,
      categoryId: 123,
      dateCreated: 1587567125458,
      lastUpdated: 1587567125458
      accountId: 4811245,
      accountProviderId: "778878",
      calculable: true
    },
    Transaction {
      id: 456,
      date: 1587567145458,
      charge: true,
      description: "RAPPI",
      amount: 1234.56,
      categoryId: 123,
      dateCreated: 1646259197099,
      lastUpdated: 1646259197099,
      accountId: 4811245,
      accountProviderId: "778878",
      calculable: false
    }
  ],
  currentPage: 0,
  totalPages: 1,
  totalItems: 2
}

Get Transaction

Given a valid transaction ID, fetches the information of a transaction.

Transactions.get(transactionId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Transaction {
  id: 123,
  date: 1587567125458,
  charge: true,
  description: "UBER EATS",
  amount: 1234.56,
  categoryId: 123,
  calculable: true,
  dateCreated: 1587567125458,
  lastUpdated: 1587567125458
}

Create Transaction

Creates a transaction. A previosuly created account is required. You have to import the Transaction Payload Model to create a new one.

import { Transaction } from "finerio-pfm-unnax";

...
const accountId = 23;
const date = new Date().getTime();
const charge = true;
const description = "Transaction Test";
const amount = 1111;
const categoryId = 26;
const calculable = false; //This value is optional
const transaction = new Transaction(
        accountId,
        date,
        charge,
        description,
        amount,
        categoryId,
        calculable
      );

Transactions.create(transaction)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Transaction {
  id: 789,
  date: 1587567145458,
  charge: true,
  description: "Transaction Test",
  amount: 1111,
  categoryId: 79,
  calculable: false,
  dateCreated: 1587567145458,
  lastUpdated: 1587567145458
}

Update Transaction

Given a valid transaction id updates a transaction. The new name should not be previously registered. You have to import the Transaction Payload Model to update it.

import { Transaction } from "finerio-pfm-unnax";

...

const accountId = 23;
const date = new Date().getTime();
const charge = true;
const description = "Edited Transaction Test";
const amount = 1111;
const categoryId = 26;
const calculable = true; //This value is optional
const transaction = new Transaction(
        accountId,
        date,
        charge,
        description,
        amount,
        categoryId
      );

Transactions.update(transactionId, transaction)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Transaction {
  id: 789,
  date: 1587567165458,
  charge: true,
  description: "Edited Transaction Test",
  amount: 1111,
  categoryId: 79,
  calculable: true,
  dateCreated: 1587567145458,
  lastUpdated: 1587567165458
}

Delete Transaction

Deletes a transaction and all its information.

Transactions.delete(transactionId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

If the transaction was deleted code 204 will be returned.

Budgets

A budget is the representation of your users' budget plan.

List Budgets

Fetches a list of budgets per user, sorted by ID in descending order.

Budgets.list(cursor?)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

If a cursor is specified, the list starts with the item that has that ID.

Output:

[
  Budget {
    id: 1486872,
    categoryId: 3,
    name: 'Streaming services',
    amount: 1500,
    warningPercentage: 0.6,
    spent: 0,
    leftToSpend: 1500,
    status: 'ok',
    dateCreated: 1646257102160,
    lastUpdated: 1646257642253,
    dateDeleted: null
  },
  Budget {
    id: 1486874,
    categoryId: 87,
    name: 'Sports',
    amount: 178.17999267578125,
    warningPercentage: 0.7,
    spent: 0,
    leftToSpend: 178.17999267578125,
    status: 'ok',
    dateCreated: 1646259181915,
    lastUpdated: 1646259181915,
    dateDeleted: null
  },
  ...
]

Get Budget

Given a valid budget ID, fetches the information of a budget.

const budgetId = 1486874;
Budgets.get(budgetId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Budget {
  id: 1486874,
  categoryId: 87,
  name: 'Sports',
  amount: 178.17999267578125,
  warningPercentage: 0.7,
  spent: 0,
  leftToSpend: 178.17999267578125,
  status: 'ok',
  dateCreated: 1646259181915,
  lastUpdated: 1646259181915,
  dateDeleted: null
}

Create Budget

Creates a budget. You have to import the Budget Payload Model to create a new one.

import { Budget } from "finerio-pfm-unnax";

...
const name = "Budget Test";
const amount = 5000;
const warningPercentage = 0.5;
const categoryId = 15;

const newBudget = new Budget(
  name,
  amount,
  warningPercentage,
  categoryId
);

Budgets.create(newBudget)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

Budget {
  id: 1858596,
  categoryId: 15,
  name: 'Budget Test',
  amount: 5000,
  warningPercentage: 0.5,
  spent: 0,
  leftToSpend: 5000,
  status: 'ok',
  dateCreated: 1647299628041,
  lastUpdated: 1647299628041,
  dateDeleted: null
}

Update Budget

Given a valid budget id updates a budget. You have to import the User Payload Model to update it.

import { Budget } from "finerio-pfm-unnax";

...

const name = "Budget";
const amount = 5000;
const warningPercentage = 0.5;
const categoryId = 16;

const budget = new Budget(name, amount, warningPercentage [, categoryId]);
const budgetId = 1858596;

Budgets.update(budgetId, budget)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

categoryId is optional, set only if you want to change the budget's category.

Output:

Budget {
  id: 1858596,
  categoryId: 16,
  name: 'Budget',
  amount: 5000,
  warningPercentage: 0.5,
  spent: 0,
  leftToSpend: 5000,
  status: 'ok',
  dateCreated: 1647299628041,
  lastUpdated: 1647299628041,
  dateDeleted: null
}

Delete Budget

Given a valid budget id deletes budget.

const budgetId = 1858596;
Budgets.delete(budgetId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

If the budget was deleted code 204 will be returned.

Insights

Analysis

Fetches an analysis of the financial information of a user.

Insights.analysis([options])
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

The options is an optional object with the following properties: | Name | Type | Example | Description | | --------------------- | ---------------------------------- | ---------------------------------- |---------------------------------- | | accountsId | Integer, Array | accountsId=123 | The ID of the account. You can add multiple account IDs in an Array. This parameter is optional.| | dateFrom | number | dateFrom=1587567125458 | The minimum date of the transaction, in UNIX format. This parameter is optional. | | dateTo | number | dateTo=1587567125458 | The maxumum date of the transaction, in UNIX format. This parameter is optional.|

The dateFrom and dateTo parameters are optional, so not adding them will return results form the last 6 months.

Not setting an options object all data are returned.

Output:

[
  Analysis {
    date: 1646114400000,
    categories: [
      CategoryAnalysis {
        categoryId: 12,
        amount: 400,
        subcategories: [
          SubcategoryAnalysis {
            categoryId: 82,
            amount: 400,
            average: 200,
            quantity: 2,
            transactions: [
              TransactionAnalysis {
                accounts: [
                    229
                ],
                description: 'RAPPI',
                amount: 400,
                average: 200,
                quantity: 2,
                calculable: true
              }
            ]
          }
         ],
      }
    ]
  }
]

Resume

Fetches a resume of the financial information of a user. It contains expenses, incomes and balances.

Insights.resume([options])
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

The dateFrom and dateTo parameters are optional, so not adding them will return results form the last 6 months.

Not setting an options object all data are returned.

Output:

Resume {
  incomes: [
    IncomeExpense {
      date: 1651381200000,
      amount: 1111.00,
      categories: [
        CategoryResume {
          categoryId: 12,
          amount: 1111.00,
          subcategories: [
            SubcategoryResume {
              categoryId: 82,
              amount: 1111.00,
              transactionsByDate: [
                TransactionsByDate {
                  date: 1653541200000,
                  transactions: [
                    {
                      id: 2230310,
                      accountId: 23,
                      amount: 1111.00,
                      charge: false,
                      description: 'Transferencia',
                      categoryId: 82,
                      calculable: true,
                      date: 1653582673141,
                      dateCreated: 1653582672457,
                      lastUpdated: 1653582673472,
                    }
                  ]
                }
              ],
            }
          ],
        }
      ],
    }
  ],
  expenses: [
    IncomeExpense {
      date: 1651381200000,
      amount: 2222.00,
      categories: [
        CategoryResume {
          categoryId: 3,
          amount: 1111.00,
          subcategories: [
            SubcategoryResume {
              categoryId: 26,
              amount: 1111.00,
              transactionsByDate: [
                TransactionsByDate {
                  date: 1653886800000,
                  transactions: [
                    {
                      id: 886,
                      accountId: 33,
                      amount: 1111.00,
                      charge: true,
                      description: 'Wal Mart',
                      categoryId: 26,                      calculable: true,
                      date: 1653944106551,
                      dateCreated: 1653944281394,
                      lastUpdated: 1653944281394,
                    }
                  ]
                }
              ],
            }
          ],
        },
        CategoryResume {
          categoryId: 11,
          amount: 1111.00,
          subcategories: [
            SubcategoryResume {
              categoryId: 79,
              amount: 1111.00,
              transactionsByDate: [
                TransactionsByDate {
                  date: 1653541200000,
                  transactions: [
                    {
                      id: 873,
                      accountId: 23,
                      amount: 1111.00,
                      charge: true,
                      description: 'Restaurante',
                      categoryId: 79,
                      calculable: true,
                      date: 1653944106551,
                      dateCreated: 1653944281394,
                      lastUpdated: 1653944281394,
                    }
                  ]
                }
              ],
            }
          ],
        }
      ],
    }
  ],
  balances: [
    Balance { incomes: 1111.0, expenses: 2222.0, date: 1651381200000 },
  ]
}

Financial Entities

Financial entities represents the financial institutions where your customers keep their money, or something else that helps you modelling the way you manage the accounts of your users.

List Financial Entities

Fetches a list of financial entities per client,, sorted by ID in descending order.

FinancialEntities.list(cursor)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

The list starts with the item that has that ID.

Output:

[
  FinancialEntity {
    id: 12,
    dateCreated: 1646243107260,
    lastUpdated: 1646243107260,
    name: "New Bank",
    code: "NBK",
    imagePath: "https://cdn.finerio.mx/pfm/financial-entities/default.jpg",
  },
  FinancialEntity {
    id: 13,
    dateCreated: 1646114400000,
    lastUpdated: 1646114400000,
    name: "Central Bank",
    code: "CBK",
    imagePath: "https://cdn.finerio.mx/pfm/financial-entities/default.jpg",
  }
  ...
]

Get Financial Entity

Given a valid financial entity ID, fetches the information of an financial entity.

FinancialEntities.get(financialEntityId)
  .then((data) => console.log(data))
  .catch((error) => console.log(error));

Output:

FinancialEntity {
  id: 13,
  dateCreated: 1646243107260,
  lastUpdated: 1646243107260,
  name: "Central Bank",
  code: "CBK",
  imagePath: "https://cdn.finerio.mx/pfm/financial-entities/default.jpg",
},

open-banking

axios dotenv

@infinitebrahmanuniverse/nolb-fine @everything-registry/sub-chunk-1669 @zalastax/nolb-fine

1 year ago

2 years ago

2 years ago

1 year ago