Get VAT rates

VAT Rates

This API retrieves the list of VAT rates and operations.

The API supports pagination to navigate through large lists of VAT rates.

Paginated Responses

The service is paginated to handle large sets of data efficiently.
For detailed information on how to handle pagination, refer to our Paginated Responses

Languages

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

Manage languages

For detailed information on how to handle languages, refer to our Managing Languages

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request and returns the VAT data.

Preconditions

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

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

Pagination parameters cursor and nextCursor must be correctly configured in the request.

Main Success Scenario

The external system sends a GET request to the endpoint for all country.

or sends a GET request to the endpoint, providing the country_code in the URL path.

If the request is successful, the system will return an HTTP 200 response with the paginated list of vats and a nextCursor indicating whether there are more vats to retrieve. If nextCursor is setted, the external system must be call again, this service, setting cursor as nextCursor value.

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.

Explanation of the `vat_code` Field

The vat_code field represents the vat code applied to a specific operation or product. This field helps distinguish between different tax rates that are applicable to the tenant's products.
the vat_code and vat_type fields allow you to identify a specific tax rate.
For example, in the case of exemptions, the vat_type could be ESENZIONE and the vat_code diversifies the various exemptions allowed.

Alternate Flows

Authentication Error: If the client does not provide valid credentials, an error response is returned.

Error Example

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

Error Example

Empty Result: If no collections exist, the vats array will be empty.

Cursor & PageSize Used Together: Cursor and PageSize parameters in the request: If you specify a Cursor you cannot specify the page size. This information will already be contained within the cursor.

Error Example

Pagination Error: If invalid cursor parameters are provided, an error response is returned.

Rate Limiting: If the API rate limits are exceeded, the client must respect the retry interval indicated in the response headers Rate Limits.

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

application/json

Body

Example

{
    "vat_rates": [
        {
            "prog_id": 42967,
            "tax_rate": 20,
            "not_deductible_tax": 20,
            "vat_department": "A",
            "validity_date": "2022-12-14",
            "country_nature_VAT_code": null,
            "country_nature_VAT_description": null,
            "country": "AT",
            "vat_type": "NORMALE",
            "vat_code": "4"
        }
    ],
    "nextCursor": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTB2"
}

VAT Rates

Languages

Actors

Preconditions

Main Success Scenario

Explanation of the `vat_type` Field

Explanation of the `vat_code` Field

Alternate Flows

Sequence Diagram

Code Examples in Node.js

Request

Request Code Samples

Responses

Get VAT rates

VAT Rates#

Languages#

Actors#

Preconditions#

Main Success Scenario#

Explanation of the vat_type Field#

Explanation of the vat_code Field#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

VAT Rates

Languages

Actors

Preconditions

Main Success Scenario

Explanation of the `vat_type` Field

Explanation of the `vat_code` Field

Alternate Flows

Sequence Diagram

Code Examples in Node.js