VAT Rates and Operations API Documentation

This API retrieves the list of VAT rates and operations for a specified country. The country is identified using its ISO 3166-1 alpha-2 code, passed in the COUNTRY_CODE parameter.

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Languages

The API response includes multilingual descriptions. The fields description_it and description_en provide VAT operation descriptions in Italian and English, respectively.

Preconditions

A valid COUNTRY_CODE must be provided as an ISO 3166-1 alpha-2 code (e.g., IT for Italy).

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.

Pagination parameters (page, pageSize) must be specified for large datasets.

Main Success Scenario

The client sends a GET request to the endpoint with the COUNTRY_CODE, page, and pageSize parameters.

The API responds with a list of VAT rates and operations for the specified country, including details such as tax rates, descriptions, and validity dates.

The client processes the moreRows flag to determine if further pages need to be requested.

Response Example

Explanation of the `vat_type` Field

The vat_type field represents the category or nature of the VAT rate applied to a specific operation or product. This field helps distinguish between different taxation scenarios and provides critical information for compliance with tax regulations.

The possible default values for vat_type include:

NO_IMPONIBILE (Not Taxable): Operations or goods exempt from VAT due to specific regulatory conditions.

RIDOTTA (Reduced): A lower VAT rate applied to certain categories of goods or services.

MINIMA (Minimum): The minimum VAT rate set for specific operations or product types.

NORMALE (Standard): The standard VAT rate applied to most goods and services.

MARGINE (Margin): Special VAT calculation rules based on the profit margin instead of the total price.

ESENZIONE (Exemption): Transactions exempt from VAT, often for specific legal reasons.

SPLIT_PAYMENT (PA Split Payment): A VAT mechanism where the VAT is paid directly to the tax authority by the buyer, typically a public administration entity.

These default values are preconfigured in the system but may vary if the tenant has custom configurations. For specific implementations, users should verify the available vat_type values within their application settings.

Alternate Flows

Invalid COUNTRY_CODE: The system returns an error indicating an invalid or unsupported country code.

Authentication Failure: The client provides invalid credentials, and the API responds with an authorization error.

No VAT Data: If no VAT rates exist for the given country, the API returns an empty vats array.

Sequence Diagram

Best Practices

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Code Examples in Node.js

Node.js Example

Responses

🟢200OK

application/json

Body

Examples

SuccessSuccess

{
    "vat_type": {
        "prog_id": 4628,
        "vat_type": "SPLIT_PAYMENT",
        "description_it": "Split payment",
        "description_en": "Split payment",
        "description_de": "Split payment",
        "description_es": "Split payment",
        "description_fr": "Split payment",
        "description_pt": "Split payment",
        "description_ru": "Split payment",
        "description_zh": "Split payment",
        "description_ar": "Split payment",
        "description_ja": "Split payment"
    }
}

🟠422Vat type not found

Get VAT type

VAT Rates and Operations API Documentation

Actors

Languages

Preconditions

Main Success Scenario

Explanation of the `vat_type` Field

Alternate Flows

Sequence Diagram

Code Examples in Node.js

Request

Request Code Samples

Responses

Get VAT type

VAT Rates and Operations API Documentation#

Actors#

Languages#

Preconditions#

Main Success Scenario#

Explanation of the vat_type Field#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

VAT Rates and Operations API Documentation

Actors

Languages

Preconditions

Main Success Scenario

Explanation of the `vat_type` Field

Alternate Flows

Sequence Diagram

Code Examples in Node.js