# PRECISION PLANTING - TAX API

## Introduction

Taking into consideration Brasil's intricate taxing system and the objective of providing users with valid tax amounts within the quoting application without duplicating too much information we reached to the conclusion that the best approach would be to have an intermediate API to handle:

- Client, dealer and product metadata retrieval. Example: NCM, CEST, etc.
- Tax amounts calculations. Example: IPI, ICSM, etc.

The metadata retrieval in most cases will be donde using each of the entities JDE ID.

In order to reduce the amount of requests we believe that an API that processes multiple products at the same time would be best.

The API will return the `amount` and `name` of ech of the product taxes.

## Authentication

Communication between the quoting application and the "TAX API" will be done "server-to-server" so we think that the best way to get an efficient and secure communication would be using an `API_KEY` included in each request.

This `API_KEY` would be configured as an environment variable in each deployment of the platform and will only be used server-side.

## Definitions

The quoting application will provide the API with the following information for each entity:

### General
- `purpose (string)`: the purpose of the quote.
- Options: [{codename: 'USO', label: "Uso ou consumo"}, {codename: 'ATI', label: "Ativo"}, {codename: 'COM', label: "Comercializaçao"}, {codename: 'IND', label: "Industrializaçao"}]

### Dealer
- `jde_id (string)`: JDE ID of the dealer.
- `tax_id (string)`: CPF/CNPJ of the dealer.
- `state (string)`: state code of the dealer.

*Note: `state` and `tax_id` parameters will be sent if available but in case `jde_id` is present that should take precedence.*

### Account

#### Existent account
- `jde_id (string)`: JDE ID of the account.

#### New account
- `tax_id (string)`: CPF/CNPJ of the account.
- `state (string)`: state code of the account.
- `activity_type (string)`:
- `recap (boolean)`: ?
- `simple_national (boolean)`: ?
- `suframa_benefit (boolean)`: ?
- `fidelity_index (boolean)`: ?

##### TO-DO
- Secify missing fields: 

#### Notes
1. The fields `state` and `tax_id` parameters will be sent if available but in case `jde_id` is present that should take precedence.
2. The fields `activity_type`, `recap`, `simple_national`, `suframa_benefit`, `fidelity_index` will be sent in case the account doesn't have a `jde_id` value.

#### TO-DO
- Define posible values for `activity_type`.

### Product
- `jde_id (string)`: JDE ID of the product.
- `price (string)`: net price of the product.
- `quantity (number)`: the quantity that is being ordered.
- `price_includes_icms (boolean)`: specifies if the price already includes the ICMS tax.
- `price_includes_piscofins (boolean)`: specifies if the price already includes the PIS/COFINS tax

#### Notes
- `price_includes_icms` and `price_includes_piscofins` will always be true for Precision Planting products.

## Endpoints

### Tax

##### Request

{
    "purpose": "USO",
    "customer": {
        "jdeId": "10161",
        "taxId": "55962369000924",
        "state": "MT"
    },
    "products": [
        {
            "jdeId": "29020011P",
            "netPrice": 100,
            "priceIncludesIcms": true,
            "priceIncludesPisCofins": true
        },
        {
            "jdeId": "29020012P",
            "netPrice": 50,
            "priceIncludesIcms": true,
            "priceIncludesPisCofins": true
        }
    ]
}

##### Response

{
    "products": [
        {
            "jdeId": "29020011P",
            "netPrice": 100,
            "calculatedPrice": 100,
            "invoiceValue": 100,
            "fiscalValue": 100,
            "accountingValue": 100,
            "taxes": [
                {
                    "name": "COFINS",
                    "amount": 7.6
                },
                {
                    "name": "PIS",
                    "amount": 1.65
                },
                {
                    "name": "IPI",
                    "amount": 0
                },
                {
                    "name": "ICMS",
                    "amount": 4.09
                },
                {
                    "name": "ICMS_ST",
                    "amount": 0
                },
                {
                    "name": "ICMS_ST_FCP",
                    "amount": 0
                },
                {
                    "name": "ICMS_ST_FRONTEIRA",
                    "amount": 0
                }
            ]
        },
        {
            "jdeId": "29020012P",
            "netPrice": 50,
            "calculatedPrice": 50,
            "invoiceValue": 50,
            "fiscalValue": 50,
            "accountingValue": 50,
            "taxes": [
                {
                    "name": "COFINS",
                    "amount": 3.8
                },
                {
                    "name": "PIS",
                    "amount": 0.82
                },
                {
                    "name": "IPI",
                    "amount": 0
                },
                {
                    "name": "ICMS",
                    "amount": 2.05
                },
                {
                    "name": "ICMS_ST",
                    "amount": 0
                },
                {
                    "name": "ICMS_ST_FCP",
                    "amount": 0
                },
                {
                    "name": "ICMS_ST_FRONTEIRA",
                    "amount": 0
                }
            ]
        }
    ]
}

###### Notes
- If `price_includes_icms` and `price_includes_piscofins` are true for a `product` the API won't return `ICMS` and/or `PIS/COFINS` tax items for that product.