finerio-pfm-unnax
v2.0.9
Published
This SDK lets you connect to [Finerio PFM API Unnax](http://ec2-3-16-174-50.us-east-2.compute.amazonaws.com:8082/swagger-ui/index.html#/) in an easier way.
Downloads
24
Readme
Finerio PFM Web SDK
This SDK lets you connect to Finerio PFM API Unnax in an easier way.
Table of contents
Installation
NPM:
npm i finerio-pfm-unnaxSetup
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:
204
If the account was deleted code 204 will be returned.
Categories
Categories are the classification of transactions and budgets.
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:
204
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:
204
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:
204
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 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:
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",
},