4WS Suite
Home
API Reference
  • Data mangement API
  • Documents API
Home
API Reference
  • Data mangement API
  • Documents API
Fourwayshop
  1. Vat types
  • Login
    • login
      POST
  • Product
    • Brand
      • Get All Brands
      • Get A Brand
      • Insert brand
      • Update brand
    • Season
      • Get All Seasons
      • Get A Season
      • Insert season
      • Update season
    • Attribute
      • Get All Attribute Types
      • Get Attribute Type
      • Get Attribute
      • Insert attribute
      • Update attribute
    • Hierarchy
      • Insert hierarchy
      • Update hierarchy
    • Dimension groups
      • Insert dimension group
      • Update dimension group
    • Dimension
      • Insert dimension
      • Update dimension
      • Delete dimension
    • Product
      • Get products
      • Get product
      • Get product grouping
      • Get SKU's barcodes
      • Get product stock
      • Insert product
      • Update product
    • Activate dimensions on products
      • Insert active dimensions
      • Delete active dimensions
    • Barcode
      • Get SKU from barcode
      • Generate missing barcodes
      • Generate missing barcode for SKU
      • Insert barcode
      • Delete barcode
    • Prices
      • Get product prices
    • Price dimension groupings
      • Get Dimension Price Grouping
      • Get All Dimension Price Grouping
      • Insert dimension grouping
      • Update dimension grouping
      • Delete dimension grouping
    • Assortment
      • insert product assortment
      • delete product assortment
    • Image
      • Get images
      • Add image
      • Replace image
      • Delete image
    • Supplier
      • Get Item suppliers
      • Insert item supplier
      • Delete item supplier
      • Update item supplier
    • Custom category
      • Get Custom code
      • Insert Custom code
      • Update Custom code
    • Vat
      • Vat types
        • Get VAT type
          GET
        • Get VAT types
          GET
      • VATs
        • Get VATs
        • Get VATs by type
        • Get VAT
      • Vat rates
        • Get VAT rates
        • Get single VAT rates
    • Stock
      • Insert stock
      • Get stock
  • Price lists
    • Get price lists
      GET
    • Get price lists by type
      GET
    • Get price list
      GET
    • Get prices from price list
      GET
    • Get entities from price lists
      GET
    • Insert Price List
      POST
    • Insert Product Price
      POST
    • Insert Entity On Price Lists
      POST
    • Update price list
      PATCH
    • Delete all product prices
      DELETE
    • Delete single product price
      DELETE
    • Delete entity from a price lists
      DELETE
  • Supplier
    • Supplier contacts
    • Supplier addresses
    • Get Suppliers
    • Get A Specific Supplier
    • Insert supplier
    • Update supplier
  • Entities
    • Get entities
    • Get entity
    • Insert entity
    • Update entity
  • Miscellaneous
    • Get requests rate limits
  • Catalog
    • Get Catalogs details
    • Get Catalog details by Code
    • Get products by Catalog Code
  • Export
    • Get bulk CSV Export
  1. Vat types

Get VAT type

GET
/api/v1/vatTypes/{VAT_TYPE}
Last modified:2025-02-07 14:57:59

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#

1.
A valid COUNTRY_CODE must be provided as an ISO 3166-1 alpha-2 code (e.g., IT for Italy).
2.
The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.
3.
Pagination parameters (page, pageSize) must be specified for large datasets.

Main Success Scenario#

1.
The client sends a GET request to the endpoint with the COUNTRY_CODE, page, and pageSize parameters.
2.
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.
3.
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#

1.
Invalid COUNTRY_CODE: The system returns an error indicating an invalid or unsupported country code.
2.
Authentication Failure: The client provides invalid credentials, and the API responds with an authorization error.
3.
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

Request

Path Params

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request GET '/api/v1/vatTypes/'

Responses

🟢200OK
application/json
Body

Examples
{
    "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
Modified at 2025-02-07 14:57:59
Previous
Update Custom code
Next
Get VAT types
Built with