4WS Suite
Home
API Reference
  • Data mangement API
  • Documents API
Home
API Reference
  • Data mangement API
  • Documents API
Fourwayshop
  1. VATs
  • Four Way Shop API
  • Before start develop
  • Why we use Resource-oriented design
  • Technical Prerequisites
  • Concepts
    • Date Handling
    • Managing Languages
    • Handling Field Updates and Null Values in Service Requests
    • ISO Code
    • Vat rates
    • Product structure
    • Product Images
    • Product dimensions
    • Product pricing
    • Dimension group vs Dimension grouping
    • Subjects overview
    • Documents structure
  • Best Practices
    • Best Practices for Error Handling in External System
    • How Testing callback response
    • Best Practices for delopers
  • Data management
    • Authentication
    • Rate Limits
    • Paginated Responses
    • Getting Started
    • API Changelog
    • Use cases
      • Cataloging a Dimension
      • Creating a New Product
      • Retriving a product details
      • Defining Product Pricing
      • Updating External System Product Catalog
      • Activate product variants and add barcodes to SKUs
      • Move a Barcode from One Product to Another
    • API
      • Login
        • login
      • 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 VAT types
          • VATs
            • Get VATs
              GET
            • Get VATs by type
              GET
            • Get VAT
              GET
          • Vat rates
            • Get VAT rates
            • Get single VAT rates
        • Stock
          • Insert stock
          • Get stock
      • Price lists
        • Get price lists
        • Get price lists by type
        • Get price list
        • Get prices from price list
        • Get entities from price lists
        • Insert Price List
        • Insert Product Price
        • Insert Entity On Price Lists
        • Update price list
        • Delete all product prices
        • Delete single product price
        • Delete entity from a price lists
      • 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
  • Documents
    • Authentication
    • Paginated responses
    • Managing API Callbacks
    • Document notifications
    • Customer promo data notifications
    • Use cases
      • Updating External System Stock
      • E-commerce Recipt Processing
      • E-commerce Return Receipt Processing
      • E-commerce Order sale Processing
      • E-commerce Return Order Processing
      • E-commerce Order Handling and Internal Stock Transfer
      • E-commerce & Gift Card
      • Creating a free entry
      • Retrieving a Document by Identifier
      • Cart Validation Service
      • Sale and Shipping costs
      • Handling Line Item Discounts
      • Managing Price Forcing in Cart Items
      • Purchase Order Registration
      • Supplier Goods Entry From Purchase Order
      • Update an Orchestrated Order
      • New Orchestrated Return Orders
    • API
      • Document Manager
        • Orders
          • Save Sale Order
          • Save Return Order
        • Orchestrated Orders
          • Orchestrated Order
          • Orchestrated Return order
          • Orchestrated Update order
        • Cart
          • Cart Validation
          • Cart Full Validation
        • Sales
          • Save receipt
          • Salve only Order
          • Replace or update sale
          • Get last digital order
        • Warehouse
          • Save Entry from supplier
          • Save Transfer document
          • Save Free Entry
        • Purchase
          • Save Purchase
        • Get Document
        • Update Document external references
      • Customer
        • Get Customer
        • Set Customer Opt-in
      • Loyalty vouchers
        • Get customer loyalty vouchers
        • Get loyalty vouchers at a time interval
        • Get last loyalty vouchers
      • Giftcard
        • Get Giftcard
        • Update Giftcard
        • Generate Gift Card Barcode
        • Gift Card PDF Generation
      • Stock
        • Get Stock
        • Get last stock
        • Insert Stock
  • 🚫 KeepIT
    • Authentication
    • Use cases
    • Articles (deprecated)
      • Get Articles
      • Insert/Update dimensional groups
      • Insert/Update price groupings
      • Insert/Update dimensions
      • Insert/Update attributes
      • Insert/Update hieararchies
      • Insert/Update seasons
      • Insert/Update articles
      • Insert/Update Articles Master data
      • Insert/Update Lists
      • Insert/Update Dimensions Groups
      • Create EAN13 barcode
      • Insert/Update Barcode
      • Assign dimensions to groupings
    • Price Lists (deprecated)
      • Insert price list
      • Add entity to price list
      • Add item price to price list
      • Insert sale profile
      • Insert sale period
      • Add item price to sale period
    • Stock (deprecated)
      • Get Stock
      • Get Stock Date
      • Get Stock CSV
      • Insert/Update Stock
    • Sales (deprecated)
      • Insert/Update sales
      • Delete sales
      • Upload printer sales archive
    • Deposit (deprecated)
      • Insert/Update deposits
    • Services
      • Insert/Update services
      • Delete services
    • Points
      • Insert/Update points
      • Calculate and Insert/Update Points
      • Delete points
    • Subjects
      • Check customers
      • Anonymize customers
      • Get subject data
      • Get customer discount
      • Insert/Update customer
      • Insert/Update billing customers
      • Insert/Update CRM customer
      • Insert/Update children
      • Change/Replacement card
      • Insert CRM user
    • Giftcards & Vouchers
      • Get giftcard
      • Insert/Update giftcards
      • Insert/Update Vouchers
    • Missed Opportunity
      • Get Lost Opportunities
      • Insert/Update missed opportunities
      • Delete missed opportunity
    • Documents (deprecated)
      • Insert documents
      • Get document
    • Catalogs
      • Get Catalog
      • Insert/update catalog
      • Insert/Update hierarchies item catalog
      • Insert/Update entity clusters
    • Suppliers (deprecated)
      • Insert/Update tailor
      • Insert/Update supplier
    • Export (deprecated)
      • Get Items Export
      • Get Barcodes Export
      • Get Prices Export
      • Get Customers Export
      • Get Suppliers Export
      • Get Sales Export
      • Get Movements Export
      • Get Vouchers Export
    • Configuration Mobile Shop (deprecated)
      • Insert/Update Entities
      • Insert Seller
    • Mappings
      • Insert Mappings
      • Get Mappings
  1. VATs

Get VAT

GET
/api/v1/vats/{VAT_TYPE}/{VAT_CODE}
Last modified:2025-02-07 14:58:53

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/vats//'

Responses

🟢200OK
application/json
Body

Example
{"vat":{"prog_id":6056,"vat_code":"1","description_it":"Aliquota ridotta 1","description_en":"Aliquota ridotta 1","description_de":"Aliquota ridotta 1","description_es":"Aliquota ridotta 1","description_fr":"Aliquota ridotta 1","description_pt":"Aliquota ridotta 1","description_ru":"Aliquota ridotta 1","description_zh":"Aliquota ridotta 1","description_ar":"Aliquota ridotta 1","description_ja":"Aliquota ridotta 1","vat_department":3,"intra_cee":false,"note":null,"vat_type":"RIDOTTA"}}
🟠422Parameter Error
Modified at 2025-02-07 14:58:53
Previous
Get VATs by type
Next
Get VAT rates
Built with