Orchestrated Update order

Update An Existing Sale Order

This API allows external systems to update an existing sale order identified by a unique transactionId.
The API checks whether the provided transactionId exists.

If the order is found, it is updated with the new details provided in the request payload.

If the transactionId does not exist, the API returns an error indicating that no matching order was found.

This integration ensures data consistency across systems (e.g., POS, CRM, eCommerce) by enabling reliable updates to existing transactions.

Document date

All Date information within the API is expressed in the GMT time zone.
API users are therefore responsible for converting dates to their desired time zone if needed.
Please refer to Date Handling

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.

The transactionId must exist in the system for the update to succeed.

The callback URL must be functional and ready to receive POST requests.

Main Success Scenario

The caller sends a POST request with a valid transactionId and updated sale order data.

The API validates authentication and request payload.

The system checks if the transactionId exists.

If found, the sale order is updated successfully.

The callback URL provided in the request (callback) is invoked with the updated order status and confirmation.

external system and transactionId

It is strongly recommended that the external system store the unique doc ID 02931b8a-a6c8-4e47-b3f1-041ffb1e432q.

Request example

Removing or Replacing an Item

Removing an Item
To remove an item, simply send the original validated order JSON while removing the specific row from the items array that should no longer be orchestrated.

Replacing an Item
To replace an item, keep the same rowId and update the values of the row (e.g., price, description, etc.).
If you need to replace a product with another one, you only need to keep the rowId and change the product’s barcode, then call the Cart Full Validation API again, followed by the product update API.

Important:

it is considered a best practice to always invoke Cart Full Validation before performing any update.

Field `receiptType`

The receiptType field defines the type of administrative document that will be generated when creating a sales order.
The following values are allowed:

TICKET → the issued document will be a fiscal receipt.

INVOICE → the issued document will be a sales invoice. In this case, the invoiceClient field must also be provided, containing the tax and personal details of the customer requesting the invoice.

The invoiceClient field is a JSON object that may include information such as address, tax code, VAT number, legal nature, and contact details.

Note:

the invoiceClient data is not validated by the Four Way Shop api. It is the caller’s responsibility to ensure the correctness and completeness of the provided information.

`receiptType = INVOICE`

Callback

The callback url will be called in POST when the request has ended. In case of success the callback reuqest body is the following JSON:

{
    "success": true,
    "barcode": "123456789012",
    "documentNumber": "1",
    "payload": "request payload"
}

otherwise:

{
    "success": false,
    "message": "Error message"
}

Alternate Flows

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

Authentication Error Example

Invalid TransactionId Error: If the client does not provide valid transactionId an error response is returned.

Invalid TransactionId Error Example

Invalid Product or Barcode Code: If an invalid itemCode o barcode is provided, the API returns an error.

Invalid Product or Barcode Code Example

Update order not allowed for channel Code: If the sales channelchannelis IN STORE or DIGITAL, order updates are not permitted.

Invalid Product or Barcode Code Example

Manually managed order cannot be updated: If the order is managed manually by the head office, updating is not permitted.

Invalid Product or Barcode Code Example

Sequence Diagram (Mermaid)

Code Examples in Node.js

Request

Query Params

Header Params

Body Params application/json

Example

{
    "seller": "Filippo Giacomelli",
    "zReportNumber": "20220621",
    "clientName": "DANIEL",
    "pointsUsed": "0400",
    "docNumber": 11,
    "endDate": "2022-06-21 13:13:44",
    "goodsVoucher": [],
    "payments": [
        {
            "paymentType": "E",
            "paymentCode": "CC",
            "paymentDescription": "Carta di credito",
            "paymentImg": "carte-ok.png",
            "paymentCash": 368,
            "channel": "IN_STORE",
            "paymentProgr": "70AE705B-147F-4E46-8569-F9441DEA128C",
            "paymentRoundingAmount": 0,
            "paymentAmount": 368,
            "paymentChange": 0,
            "paymentDone": "Y"
        },
        {
            "paymentType": "C",
            "paymentCode": "CONTANTI",
            "paymentDescription": "Contanti",
            "paymentImg": "contanti-euro.png",
            "paymentCash": 150,
            "channel": "IN_STORE",
            "paymentProgr": "9090BAEE-0C8E-4E88-A955-8A9194093DA6",
            "paymentRoundingAmount": 0,
            "paymentAmount": 122,
            "paymentChange": 28,
            "paymentDone": "Y"
        }
    ],
    "masterRegister": "N",
    "clientDenomination": "GIACOMELLI DANIEL",
    "clientSurname": "GIACOMELLI",
    "deviceId": "5327E23B-CB96-4BAF-AC01-88E978267021",
    "pointsCode": "OK",
    "printerCode": "LUNGO_501_501_1070_TM-m30II-NT",
    "pointsEarned": 980,
    "sellerId": "777",
    "movementType": "V",
    "pointsPrevious": 720,
    "barcodeInfo": "10701070222062100011",
    "currency": "EUR",
    "discountsManualCumulative": "Y",
    "deliveryDate": "2022-06-28 15:07:12",
    "registerCode": "10702",
    "clientBarcode": "8966",
    "delivery": [],
    "entityCode": "501",
    "clientId": 47109,
    "ticket": 11,
    "clientEmail": "scazdaniel@gmail.com",
    "pointsBalance": 1300,
    "pointsMessage": "OK",
    "currencySymbol": "€",
    "rounding": 2,
    "totals": {
        "totalDiscount": 10,
        "totalDiscountType": "N",
        "totalDiscountReasonDescription": "LOYALTY - Sconto con scelta fasce",
        "totalDiscountAmount": 10,
        "total": 490,
        "vat": 0,
        "grandTotal": 490,
        "inStoreGrandTotal": 490,
        "digitalGrandTotal": 0,
        "totalDeposits": 0,
        "totalDepositsVat": 0,
        "allowance": 0,
        "alreadyPayed": 0,
        "taxableIncome": 490,
        "autoTotalDiscountType": "PROMO"
    },
    "transactionId": "1fe0a4f9-a1ce-4963-9f18-94eb5fbf16a4",
    "branchCode": "1070",
    "onlineValidation": "Y",
    "filling": "FIRST",
    "appliedPromotions": [
        {
            "idPromozione": "50120220505104019",
            "description": "LOYALTY - Sconto con scelta fasce",
            "multipleDiscount": 1,
            "discounts": [
                {
                    "vantaggio": 10,
                    "consumedPoints": 400
                }
            ],
            "barcode": "13061360122101101",
            "status": "ACCEPTED",
            "discountType": "TOTAL",
            "callbackAction": 10609,
            "vantaggio": "10",
            "consumedPoints": "400"
        }
    ],
    "ticketRT": 11,
    "candidatePromos": [
        {
            "idPromozione": "50120220505104019",
            "description": "LOYALTY - Sconto con scelta fasce",
            "multipleDiscount": 1,
            "discounts": [
                {
                    "vantaggio": 10,
                    "consumedPoints": 400
                }
            ],
            "barcode": "13061360122101101",
            "status": "ACCEPTED",
            "discountType": "TOTAL",
            "callbackAction": 10609,
            "vantaggio": "10",
            "consumedPoints": "400"
        }
    ],
    "items": [
        {
            "rowId": "B59FAFB3-6265-4EAD-B3AD-B4B2B0582425",
            "rowType": "ITEM",
            "barcode": "13061360122101101",
            "barcodeType": "BARCODE_ARTICOLO",
            "unitPrice": 500,
            "qty": 1,
            "qtyType": "N",
            "itemState": "SERVER_OK",
            "seller": "Filippo Giacomelli",
            "sellerId": "777",
            "taxRate": 0,
            "vatCode": "4",
            "rowTaxableIncome": 490,
            "rowVat": 0,
            "rowTotal": 490,
            "itemType": "PRODUCT",
            "movementType": "V",
            "havingTailoring": "N",
            "priceList": "1070",
            "channel": "IN_STORE",
            "addTimestamp": 1655816803158,
            "itemCode": "SA1VX0009 P4517",
            "currencySymbol": "€",
            "currency": "EUR",
            "rounding": 2,
            "shopDescription": "PORTACARTE",
            "description": "PORTACARTE",
            "dimensionDescription1": "TU",
            "dimensionDescription2": "T8013 - BLACK",
            "attributeLevel1": "1",
            "hierarchyLevel1": "30",
            "attributeLevel2": "1",
            "hierarchyLevel2": "3063",
            "attributeLevel3": "360",
            "hierarchyLevel3": "61",
            "dimension1": "TU",
            "dimension2": "T8013#@#BLACK",
            "dimensionType1": "TAGLIA",
            "dimensionType2": "COLORE",
            "dimensionGroup1": "TAUN",
            "dimensionGroup2": "360",
            "discountTotalAmount": 10,
            "discountRowTotalAmount": 10,
            "originalUnitPrice": 180,
            "priceForcingReason": "FORZA",
            "rowOrder": 1
        }
    ],
    "transactionState": 1,
    "startDate": "2022-06-21 13:06:43",
    "printerSerial": "NOFISCAL",
    "printerTaxation": "NOFISC"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Orchestrated Update order

Update An Existing Sale Order#

Actors#

Preconditions#

Main Success Scenario#

Removing or Replacing an Item#

Field receiptType#

Callback#

Alternate Flows#

Sequence Diagram (Mermaid)#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Update An Existing Sale Order

Actors

Preconditions

Main Success Scenario

Removing or Replacing an Item

Field `receiptType`

Callback

Alternate Flows

Sequence Diagram (Mermaid)

Code Examples in Node.js