Cart Validation

Validate Sales Cart

This API allows an external system to validate an e-commerce cart. The validation process includes:

Product recognition

Price and applied discount verification

Automatic promotions applicable to the customer

The external system will receive the same cart with the applied validations.

The body of a cart consists of the following sections:

items this array contains the cart items

payments this array contains the payment methods (optional)

totals this object contains the cart total

Limitation on Handling Multiple Manual Discounts per Cart row

The API currently does not support applying multiple manual discounts to a single cart line.

Details:

Only one manual discount per cart line is supported.

If multiple manual discounts are sent for the same line, only the first one (based on submission order) will be applied, and the others will be silently ignored.

This limitation applies exclusively to manual discounts (submitted via API). It does not affect any automatic discounts managed by 4ws.suite.

Implications:

It is recommended to aggregate multiple discounts into a single total value before submission.

If you need to represent multiple separate discounts on a single line, we suggest implementing an aggregation logic upstream, on the client or originating system side.

Actors

API Client: The system or user initiating the request.

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

Preconditions

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

Main Success Scenario

The external system sends a request with the cart details.

This service validate the cart items and applies the rules of the promotional engine and the promotional loyalty engine.:

candidatePromos this array contains the list of promotions that could be applied to the cart

appliedPromotions this array contains the list of promotions applied to the cart by the promotional engine

Unique rowId

Each items row on request must have a unique rowId

Request cart example

Item validation:

The service will automatically check the information of all past items, such as: description, price, discounts. If you don't want the service validate the article information and you want the service use the information passed in the request, specify the following parameter in the item object: alreadyValidate: Y/N, if Y use the request informations

NOTE: Use this attribute alreadyValidate only if you are sure the client has the most up-to-date information.

Transaction Id `transactionId`

If the transactionId is set, the API will try to retrieve the cart with that transaction ID; if it is not found, it will return an error.

TransactionId not found

  {
  "success": false,
  "errorCode": 1,
  "message": "Cart not found, resend it."
}

Movement type `movementType`

The movementType field allows you to identify the type of movement requested V sale of goods and R return of goods.

Payments `payments`

Payments collected to pay off the cart must be tracked in the payments array.

Credit card payment

More Request sample

Simple cart

Discount

Forced price

Shipping cost or service

Return card

Alternate Flows

Invalid Product Code: If a product code is incorrect, the API returns an error message specifying the issue.

Callback Response

The API response includes:

success: Boolean indicating if the validation was successful.

transactionId: Unique identifier for the validation transaction.

items: Array containing validated product details with applied discounts and taxes.

totals: Object with total amounts, including discounts, VAT, and grand total.

appliedPromotions: List of promotions applied during validation.

More use cases

Please refer to these use cases for more information on how to process your sales:

E-commerce Recipt Processing;

E-commerce Return Receipt Processing;

E-commerce Order sale Processing;

E-commerce Return Order Processing

Sequence Diagram (Mermaid)

Best Practices

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

Code Examples in Node.js

Request

Query Params

Header Params

Body Params application/json

Example

{
  "appliedVouchers": [
    {
      "id": "2aad3cf7-bd0d-48fc-b16d-526d0496ec0b",
      "barcode": "0000000000178",
      "totalAmount": 21.76
    }
  ],
  "branchCode": 1001,
  "clientBarcode": "0099000001209",
  "currency": "EUR",
  "currencySymbol": "€",
  "discountsManualCumulative": "Y",
  "entityCode": 210,
  "filling": "LAST",
  "items": [
    {
      "rowId": "1",
      "rowType": "ITEM",
      "barcode": "010005600109",
      "barcodeType": "BARCODE_ARTICOLO",
      "qty": 1,
      "qtyType": "N",
      "seller": "1",
      "rowTaxableIncome": 16.31,
      "rowVat": 3.59,
      "rowTotal": 19.9,
      "itemCode": "BO00P794101",
      "currencySymbol": "€",
      "currency": "EUR",
      "rounding": 2,
      "shopDescription": "POLO IN COTONE",
      "description": "POLO IN COTONE PIQUET",
      "havingTailoring": "N",
      "dimensionDescription1": "M",
      "dimensionDescription2": "BLU",
      "itemType": "PRODUCT",
      "vatCode": 20,
      "taxRate": 22,
      "printerDepartmentCode": 2,
      "dimension1": "9",
      "dimension2": "BLU",
      "dimensionType1": "TAGLIA",
      "dimensionType2": "COLORE",
      "dimensionType3": "DROP",
      "dimensionType4": "STATURA",
      "dimensionType1Desc": "Taglia",
      "dimensionType2Desc": "Colore",
      "unitPrice": 19.9,
      "priceList": "1001",
      "discountAmount": 0,
      "discountTotalAmount": 0,
      "discountRowTotalAmount": 0,
      "hierarchyLevel1": "MAN",
      "attributeLevel1": "ITEM",
      "alreadyValidate": "Y"
    },
    {
      "rowId": "1",
      "rowType": "ITEM",
      "barcode": "01234567890",
      "barcodeType": "BARCODE_ARTICOLO",
      "qty": 1,
      "qtyType": "N",
      "seller": "1",
      "rowTaxableIncome": 25.84,
      "rowVat": 5.69,
      "rowTotal": 31.53,
      "itemCode": "BATTERIA_10",
      "currencySymbol": "€",
      "currency": "EUR",
      "rounding": 2,
      "shopDescription": "Batteria 5V",
      "description": "Batteria 5V",
      "havingTailoring": "N",
      "dimensionDescription1": ".",
      "itemType": "PRODUCT",
      "vatCode": 20,
      "taxRate": 22,
      "dimension1": 9,
      "dimensionType1": "TAGLIA",
      "dimensionType2": "COLORE",
      "dimensionType3": "DROP",
      "dimensionType4": "STATURA",
      "dimensionType1Desc": "Taglia",
      "dimensionType2Desc": "Colore",
      "unitPrice": 46.8,
      "priceList": "1001",
      "discountAmount": 0,
      "discountTotalAmount": 15.27,
      "discountRowTotalAmount": 15.27,
      "channel": "INSTORE",
      "oldUnitPrice": 19.9,
      "oldTaxRate": 22,
      "hierarchyLevel1": "BRAND",
      "attributeLevel1": "SERVIZI",
      "alreadyValidate": "Y"
    }
  ],
  "payments": [],
  "registerCode": 1,
  "rounding": 2,
  "totals": {
    "totalDiscount": 0,
    "totalDiscountType": "",
    "totalDiscountReason": "",
    "totalDiscountAmount": 0,
    "total": 32.62,
    "vat": 7.18,
    "grandTotal": 39.8,
    "allowance": 0,
    "alreadyPayed": 0,
    "taxableIncome": 32.62,
    "inStoreGrandTotal": 39.8,
    "digitalGrandTotal": 0
  }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Cart Validation with loylty voucher - success

application/json

Body

Example

{
    "success": true,
    "responseType": "AMOUNTS",
    "clientBarcode": "0099000001209",
    "transactionId": "cc254e29-c7fb-4fd3-82d6-0691bcada379",
    "items": [
        {
            "rowId": "1",
            "rowType": "ITEM",
            "barcode": "010005600109",
            "barcodeType": "BARCODE_ARTICOLO",
            "qty": 1,
            "qtyType": "N",
            "seller": "1",
            "rowTaxableIncome": 10.99,
            "rowVat": 2.42,
            "rowTotal": 13.41,
            "itemCode": "BO00P794101",
            "currencySymbol": "€",
            "currency": "EUR",
            "rounding": 2,
            "shopDescription": "POLO IN COTONE",
            "description": "POLO IN COTONE PIQUET",
            "havingTailoring": "N",
            "dimensionDescription1": "M",
            "dimensionDescription2": "BLU",
            "itemType": "PRODUCT",
            "vatCode": 20,
            "taxRate": 22,
            "printerDepartmentCode": 2,
            "dimension1": "9",
            "dimension2": "BLU",
            "dimensionType1": "TAGLIA",
            "dimensionType2": "COLORE",
            "dimensionType3": "DROP",
            "dimensionType4": "STATURA",
            "dimensionType1Desc": "Taglia",
            "dimensionType2Desc": "Colore",
            "unitPrice": 19.9,
            "priceList": "1001",
            "discountAmount": 0,
            "discountTotalAmount": 6.49,
            "discountRowTotalAmount": 6.49,
            "alreadyValidate": "Y",
            "channel": "INSTORE"
        },
        {
            "rowId": "1",
            "rowType": "ITEM",
            "barcode": "01234567890",
            "barcodeType": "BARCODE_ARTICOLO",
            "qty": 1,
            "qtyType": "N",
            "seller": "1",
            "rowTaxableIncome": 25.84,
            "rowVat": 5.69,
            "rowTotal": 31.53,
            "itemCode": "BATTERIA_10",
            "currencySymbol": "€",
            "currency": "EUR",
            "rounding": 2,
            "shopDescription": "Batteria 5V",
            "description": "Batteria 5V",
            "havingTailoring": "N",
            "dimensionDescription1": ".",
            "itemType": "PRODUCT",
            "vatCode": 20,
            "taxRate": 22,
            "dimension1": 9,
            "dimensionType1": "TAGLIA",
            "dimensionType2": "COLORE",
            "dimensionType3": "DROP",
            "dimensionType4": "STATURA",
            "dimensionType1Desc": "Taglia",
            "dimensionType2Desc": "Colore",
            "unitPrice": 46.8,
            "priceList": "1001",
            "discountAmount": 0,
            "discountTotalAmount": 15.27,
            "discountRowTotalAmount": 15.27,
            "channel": "INSTORE",
            "oldUnitPrice": 19.9,
            "oldTaxRate": 22,
            "hierarchyLevel1": "",
            "attributeLevel1": "",
            "alreadyValidate": "Y"
        }
    ],
    "totals": {
        "totalDiscount": 0,
        "totalDiscountType": "",
        "totalDiscountReason": "",
        "totalDiscountAmount": 0,
        "total": 36.83,
        "vat": 8.1,
        "grandTotal": 44.94,
        "allowance": 0,
        "alreadyPayed": 0,
        "taxableIncome": 36.84,
        "inStoreGrandTotal": 44.94,
        "digitalGrandTotal": 0
    },
    "candidatePromos": [],
    "appliedPromotions": [],
    "payments": [],
    "currencySymbol": "€",
    "currency": "EUR",
    "rounding": 2,
    "filling": "LAST",
    "discountsManualCumulative": "Y",
    "entityCode": 210,
    "branchCode": 1001,
    "registerCode": 1,
    "onlineValidation": "Y",
    "appliedVouchers": [
        {
            "id": "2aad3cf7-bd0d-48fc-b16d-526d0496ec0b",
            "barcode": "0000000000178",
            "totalAmount": 21.76,
            "onlineValidation": "Y"
        }
    ]
}

🟢200Cart Validation - invalid voucher

🟠422Unique constraint error

Validate Sales Cart#

Details:#

Implications:#

Actors#

Preconditions#

Main Success Scenario#

Transaction Id transactionId#

Movement type movementType#

Payments payments#

More Request sample#

Alternate Flows#

Callback Response#

More use cases#

Sequence Diagram (Mermaid)#

Code Examples in Node.js#