VAT Type

This API retrieves the list of VAT type operations.

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

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 types 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.

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

Main Success Scenario

If the request is successful, the system will return an HTTP 200 response with the paginated list of vat type and a nextCursor indicating whether there are more vat type 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.

Alternate Flows

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

Error Example

Empty Result: If no collections exist, the seasons 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

Responses

🟢200Vat

application/json

Body

Example

{
    "vat_types": [
        {
            "prog_id": 3129,
            "vat_type": "ESENZIONE",
            "description_it": "Esenzione IVA",
            "description_en": "VAT exemption"
        },
        {
            "prog_id": 3127,
            "vat_type": "MINIMA",
            "description_it": "Aliquota minima",
            "description_en": "Super reduced rate",
            "description_de": "Super reduced rate"
        }
    ],
    "nextCursor": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTB2"
}

Get VAT types

VAT Type

Languages

Actors

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 types

VAT Type#

Languages#

Actors#

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 Type

Languages

Actors

Preconditions

Main Success Scenario

Explanation of the `vat_type` Field

Alternate Flows

Sequence Diagram

Code Examples in Node.js