Cargon ICMS Library

- _Website:_ https://cargon.com.br/
- ICMS Library with two main functionalities:
- _findTaxBracket( ):_ Find up-to-date ICMS tax brackets data, including exempt states.
- _calculateIcms( ):_ ICMS calculator with an "inside" operation and reduction of calculation base.

Usage

``
npm install @cargon_logtech/icms
`

Then require or import the functions before start using it

`
import { findTaxBracket, calculateIcms } from '@cargon_logtech/icms';

//OR

const icms = require('@cargon_logtech/icms');
`

findTaxBracket( )

This function queries our up-to-date database and returns the tax bracket data for in-state or interstate transactions, even when they are exempt from taxes.

- Inputs:

> first parameter = origin state. ("PR", "SP", "MG", ...)

> second parameter = optional destination state. ("SP", "RJ", ...)

- Outputs:

> bracket = tax bracket percentage in an integer number. (12 = 12%, 7 = 7%).

> legal_text = legal text regarding an specific state policy, if there is one.

`
import { findTaxBracket } from '@cargon_logtech/icms'

const result = findTaxBracket("PR", "PR");
/*
result = {
bracket: 0,
legal_text: 'ICMS Isento conforme Convênios ICMS 4/2004, 111/2012, 60/2014, 29/2015 e 65/2015; Convênios ICMS 107/2015 e 133/2019'
}
*/
`

$3

- Transaction where the origin state is the same as the destination state.
- The second parameter is optional, if you dont include it, we will consider the destination state the same as the origin state, meaning an in-state transaction.

`
const result = findTaxBracket("PR", "PR");

// OR

const result = findTaxBracket("PR");
/*
result = {
bracket: 0,
legal_text: 'ICMS Isento conforme Convênios ICMS 4/2004, 111/2012, 60/2014, 29/2015 e 65/2015; Convênios ICMS 107/2015 e 133/2019'
}
*/
`

$3

- Transaction where the destination state is different from the origin state.
- In this case, you are required to inform the second parameter of the function.

`
const result = findTaxBracket("ES", "SP");

/*
result = {
bracket: 12,
legal_text: null
}
*/
`

#### Observation & other cases:

1. _No data found:_ if no data about the states inputted in the functon was found, we will throw an error.

2. _State is exempt from taxes:_ if the state has an exempt policy and doesn't have tax brackets, we will return 0 as the "bracket" result:

`
{
bracket: 0, //Tax bracket = 0%, meaning it is exempt from taxes
legal_text: 'ICMS Isento conforme Convênios ICMS 4/2004, 111/2012, 60/2014, 29/2015 e 65/2015; Convênios ICMS 107/2015 e 133/2019'
}
`

3. _Legal text_: if there is an legal text, we will return it; otherwise, we will return null

`
{
bracket: 12,
legal_text: null //No legal text
}
`

---

calculateIcms( )

Function that calculate ICMS tax bracket with an "inside" operation.

- Required input object "values":

> ammount = initial ammount used to calculate the new calculation base.

> bracket = percentage of tax bracket being applied to the calculation base. (20 = 20%, 3 = 3%)

> reducedBasePercentage = optional percentage that will reduce the calculation base ammount. (13 = 13%, 8 = 8%)

- Optional input object "options":
> decimals = the level of precision in regards to the decimal values being returned.
- Outputs:

> initialAmmount = initial ammount inputted by the user.

> icmsPercentage = tax percentage inputted by the user.

> baseReductionPercentage = base reduction percentage inputted by the user (if there's one).

> icmsAmmount = ammount of ICMS tax bracket. The result of applying the ICMS percentage into the calculation base.

> calculationBase = calculation base used to calculate the Tax Bracket. Can be inferred as the final ammount.

> insidePercent = percentage of the ammount inputted by the user compared with the total ammount (initial ammount + tax bracket)

`
import { calculateIcms } from '@cargon_logtech/icms'

const result = calculateIs(
{
ammount: 1000,
bracket: 18,
reducedBasePercentage: 20, //OPTIONAL
},
{
decimals: 2, //OPTIONAL
}
);

/*
result = {
initialAmmount: 1000,
icmsPercentage: 0.18,
baseReductionPercentage: 0.2,
calculationBase: 975.61,
icmsAmmount: 175.61,
insidePercent: 0.82
}
*/
`

$3

- The base reduction percentage is applied directly into the calculation base, reducing its ammount.
- If you don't want to apply it, you simply put "0" in the field, or don't even include it in the parameters.

`
const result = calculateIcms(
{
ammount: 1000,
bracket: 18,
reducedBasePercentage: 0,
},
{
decimals: 2,
}
);

//OR

const result = calculateIcms(
{
ammount: 1000,
bracket: 18,
},
{
decimals: 2,
}
);

/*
result = {
initialAmmount: 1000,
icmsPercentage: 0.18,
baseReductionPercentage: 0,
calculationBase: 1219.51,
icmsAmmount: 219.51,
insidePercent: 0.82
}
*/
`

$3

- The percentage of ICMS tax bracket being applied into the calculation base.
- If the calculation is for an exempt state, simply put 0 into the "bracket" field.

`
const result = calculateIcms(
{
ammount: 1000,
bracket: 0,
reducedBasePercentage: 10,
},
{
decimals: 0,
}
);

/*
result = {
initialAmmount: 1000,
icmsPercentage: 0,
baseReductionPercentage: 0.1,
calculationBase: 900,
icmsAmmount: 0,
insidePercent: 1
}
*/
``

$3

1. _Percentage is returned in decimals:_ All the percentage values used in the calculation are returned in decimals. If you want to convert them to integer, multiply them by 100.

2. _Percentages are applied in the calculation base_: Both the icms percentage and the base reduction percentage are applied in the new calculation base, not necessarily in the ammount inputted by the user. That's how the calculation works.

Cargon, 2022.