Update an Orchestrated Order

Use Case Description

An external system (e.g., e-commerce frontend) creates a new sales order by calling saveOrder_v1.
The platform processes the order asynchronously and returns the created order identifier in a callback (only if transactionId was not provided).
Later the external system needs to change the order contents (for example remove a product) and calls updateOrder_v1 providing the same transactionId and rowId's returned by the platform (or the previously supplied transactionId) to update the exact same order.

VERY IMPORTANT INFO

Please note that the update and insert structure are identical; in effect, the order is replaced, so all information must be passed for a correct update.

If updateOrder_v1 is called with a different or missing transactionId the API returns an error indicating no documents were found.

Receipt Order

The order must not have already been finalized, that is, the administrative document that concludes the sale must not have been issued.

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.

Callback Endpoint (External Client): The callback used by Four Way Shop to asynchronously notify the client of success/failure and to return the order ID must be handled (How Testing callback response).

Monitoring / Alerting System: Handling integration errors and retries logs and warnings, as reported inBest Practices for Error Handling in External System.

Main Success Scenario

Client prepares full order JSON (see sample) and POSTs to Orchestrated Order.

API gateway accepts request, returns HTTP 202/200 (depending on implementation) and schedules processing.

Order Processor validates the payload (business rules, inventory holds, discounts).

If transactionId is not provided, the Order Processor generates an internal transactionId/orderId.

Once processing finishes successfully, the platform posts a callback to the client's callback URL containing the order reference and status.

Client receives callback with transactionId (or orderId) and stores it.

Client decides to remove a product and builds an updated order JSON containing the same transactionId and rowId's except for the removed line of course.

Client POSTs updated order to updateOrder_v1.

Order Processor finds the original order by transactionId, applies updates, revalidates totals and inventory, and returns success in callback with the updated order references.

Validate Cart

Before invoking the order update service it is useful to validate the cart or order via the API Cart Full Validation.

Alternate Flows

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

Authentication Error Example

Missing or mismatched transactionId at update

Client calls updateOrder_v1 with a different or missing transactionId.

API responds (synchronously or via callback) with:

Missing or mismatched transactionId Error Example

Client must use the transactionId returned in the original callback or re-create the order.

Validation error on save

Processor finds invalid data (e.g., negative qty, missing required fields).

Callback contains validation error details; client must correct and resend.

JSON Structure for Sale Order Document (high-level schema)

Below is the canonical structure and an annotated example.
Not all fields are strictly mandatory; required fields are marked.

VERY IMPORTANT INFO

Please note that the update and insert structure are identical; in effect, the order is replaced, so all information must be passed for a correct update.
Same transactionId and rowId's.

Example schema (JSON example trimmed for clarity)

{
  "transactionId": "{{UUID}}-trs",         // optional on save, required on update
  "seller": "Marco Bianchi",
  "sellerId": "1001",
  "startDate": "2020-02-06 13:12:30",
  "endDate": "2020-02-06 13:22:19",
  "items": [
    {
      "rowId": "76c55f38-9586-462b-bdb6-9e45f9ba98b8",
      "rowType": "ITEM",
      "barcode": "010005600109",
      "itemCode": "BO00P794101",
      "description": "POLO IN COTONE PIQUET",
      "unitPrice": 19.9,
      "qty": 1,
      "taxRate": 22,
      "vatCode": 20,
      "rowTotal": 16.66,
      "discount": 10,
      "discountType": "P",
      "rowOrder": 1,
      "channel": "INSTORE"
    }
    // more items...
  ],
  "payments": [
    {
      "paymentType": "E",
      "paymentAmount": 10,
      "paymentCash": 10,
      "paymentCode": "21",
      "paymentDescription": "Carta di credito",
      "paymentProgr": "64231ea7-..."
    }
  ],
  "totals": {
    "totalDiscountAmount": 2.5,
    "total": 27.32,
    "vat": 6.01,
    "grandTotal": 33.32
  },
  "invoiceClient": { /* billing / customer info */ },
  "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback",
  "forceUndoAll": false
}

Notes on important fields

rowId: unique per item row — system may require stable rowId same of saveOrder_v1 if later updates reference the same row.

transactionId: external idempotency key. If client supplies it when creating the order, platform should honor it and return it back in callbacks. If omitted, platform generates one and returns it in the callback; that id must be reused to update the order.

items array in updateOrder_v1 normally contains the resulting items after the update (not a diff) — the platform will replace/reconcile the order content accordingly. Confirm with API contract if diffs are supported.

Callback Response

When processing finishes (both for save and update), the platform POSTs a JSON payload to the callback URL. Example success callback (trimmed):

{
  "success": true,
  "message": "Order processed successfully",
  "transactionId": "11111111-2222-3333-4444-trs",
  "orderId": "ORD-20200206-0001",
  "docNumber": 1,
  "siteId": "501",
  "companyId": "TEMP1",
  "status": "PROCESSED",
  "totals": {
    "total": 27.32,
    "vat": 6.01,
    "grandTotal": 33.32
  },
  "items": [
    {
      "rowId": "76c55f38-9586-462b-bdb6-9e45f9ba98b8",
      "itemCode": "BO00P794101",
      "qty": 1
    }
  ],
  "timestamp": "2025-09-18T08:01:00Z"
}

Example error callback for update with unknown transactionId (or synchronous response from update endpoint):

{
  "success": false,
  "message": "No documents found for the provided transactionId"
}

external system and transactionId and rowId

Set a unique transactionId on saveOrder_v1 and then reuse it in updateOrder_v1, or if transactionId is omitted on saveOrder_v1 this will return the transactionId in the callback response, reuse it in updateOrder_v1 as a reference to the order to update.
Also rowId's must be the same on saveOrder_v1 and updateOrder_v1 as we report below the order will be replaced with the one provided on call body.

Sequence Diagram (Mermaid)

Use this Mermaid diagram in markdown-capable docs or convert to an image in your docs tool:

Code Examples in Node.js

Below are two example flows: (A) create order (save), (B) update order (remove an item). Use axios or node-fetch style — examples use axios for clarity. Always handle network errors and make your callbacks idempotent.

Best Practices

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

Update an Orchestrated Order

Update an Orchestrated Order

Use Case Description

Actors

Actors

Preconditions

Main Success Scenario

Alternate Flows

JSON Structure for Sale Order Document (high-level schema)

Example schema (JSON example trimmed for clarity)

Callback Response

Sequence Diagram (Mermaid)

Code Examples in Node.js

A. Save order (create)

B. Update order (remove a product)

C. Minimal callback receiver (Express)

Update an Orchestrated Order

Update an Orchestrated Order#

Use Case Description#

Actors#

Actors#

Preconditions#

Main Success Scenario#

Alternate Flows#

JSON Structure for Sale Order Document (high-level schema)#

Example schema (JSON example trimmed for clarity)#

Callback Response#

Sequence Diagram (Mermaid)#

Code Examples in Node.js#

A. Save order (create)#

B. Update order (remove a product)#

C. Minimal callback receiver (Express)#

Update an Orchestrated Order

Use Case Description

Actors

Actors

Preconditions

Main Success Scenario

Alternate Flows

JSON Structure for Sale Order Document (high-level schema)

Example schema (JSON example trimmed for clarity)

Callback Response

Sequence Diagram (Mermaid)

Code Examples in Node.js

A. Save order (create)

B. Update order (remove a product)

C. Minimal callback receiver (Express)