Orchestrated Order

Save A New Sale Order

This API allows an external system to create a order receipt and apply the loyalty rules within the 4ws.sale platform.

Validate Cart

Before invoking the saving of the receipt, the sales cart must be validated by invoking the API Cart Validation.

The order process includes:

Capturing product details via barcode

Assigning the receipt to a seller and a customer

Calculating total price, taxes, and any discounts

Storing the transaction with a unique ID number

Warehouse and sale

This service create only sale order o return order, no sale documents and warehouse documents are created.

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.

In the order header you have to specify the transactionId, this id must be unique, for example an UUID, a progressive or a unique combination of information.This id will be used to refer to this document in the future requests, for example in the case of a return.

For each row you must specify a unique rowId. As for the header this id must be unique, for example an UUID, a progressive or a unique combination of information and this id will be used to refer to this row in the case of a return.

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

Main Success Scenario

The external system sends a request containing order receipt details.

The API processes the order receipt by:

Validating product details

Assigning seller and customer information

Calculating total cost, taxes, and any applicable discounts

The system stores the order receipt transaction and generates a unique ticket.

The response includes confirmation details along with the order receipt summary.

Date fields

All date fields in the JSON body for this sales document creation service must be provided in GMT (Greenwich Mean Time) format.

Sample Sales Receipt

Unique rowId

Each items row on request must have a unique rowId

Movement type `movementType`

The movementType field allows you to identify the type of movement requested V order receipt goods and R for a return order receipt of goods.
On return movementType=V is usefull set rowIdRef field should be filled in with the corresponding rowId of the order receipt, this allows you to link the two documents and verify that the product(s) of the order receipt document are displayed as returns in the order receipt document.

Remember:

transcationId of returned cart is different from the original cart

specify the originalCart in the json (if you don't have the entire cart available, pass just the transactionId)

specify cart movementType R

items movementType R

Sample Return Receipt

Payments `payments`

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

Credit card payment

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

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

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

{
  "seller": "Marco Bianchi",
  "zReportNumber": "",
  "docNumber": 1,
  "endDate": "2020-02-06 13:22:19",
  "goodsVoucher": [],
  "payments": [
    {
      "paymentType": "E",
      "paymentAmount": 10,
      "paymentCash": 10,
      "paymentCode": "21",
      "paymentDescription": "Carta di credito",
      "paymentImg": "carte-ok.png",
      "paymentProgr": "{{$guid}}",
      "paymentDone": "Y"
    },
    {
      "paymentType": "C",
      "paymentAmount": 23.32,
      "paymentCash": 23.32,
      "paymentCode": "1",
      "paymentDescription": "Contanti",
      "paymentImg": "contanti-euro.png",
      "paymentProgr": "{{$guid}}",
      "paymentDone": "Y"
    }
  ],
  "clientContractDescription": "Associazione Alumni 2019",
  "clientContractEndDate": "2020-10-29 23:00:00",
  "clientDenomination": "Biasotto Luca",
  "printerCode": "BOGGI_500_210_1001_5",
  "sellerId": "1001",
  "clientContractDiscount": 10,
  "movementType": "V",
  "pointsPrevious": 0,
  "barcodeInfo": "10010820020600001",
  "clientContractCode": "31031989123456",
  "currency": "EUR",
  "discountsManualCumulative": "Y",
  "deliveryDate": "2020-02-13 14:13:36",
  "registerCode": "8",
  "clientBarcode": "0099000001209",
  "entityCode": "210",
  "clientId": 31031989,
  "ticket": 1,
  "pointsMessage": "Customer NOT enabled for points because customer NOT found into registry",
  "currencySymbol": "€",
  "rounding": 2,
  "totals": {
    "totalDiscountAmount": 2.5,
    "total": 27.32,
    "vat": 6.01,
    "grandTotal": 33.32,
    "totalDiscount": "7",
    "totalDiscountType": "P",
    "totalDiscountReason": "BIRTHDAY",
    "allowance": 0,
    "alreadyPayed": 0,
    "taxableIncome": 27.31,
    "totalDiscountReasonDescription": "Sconto Compleanno"
  },
  "transactionId": "{{UUID}}-trs",
  "invoiceClient": {
    "zipCode": "31046",
    "subjectTypeDescription": "Tipo 4",
    "city": "Oderzo",
    "cardSubtype": 3,
    "cardSubtypeDescription": "CONVENZIONATO",
    "province": "TV",
    "fiscalCode": "BSTLCU99F99F999F",
    "cardBarcode": "0099000001209",
    "email": "luca.biasotto@xxxx.it",
    "subjectName": "Luca",
    "entityCode": 210,
    "foreignPerson": "F",
    "address1": "via Comunale di Camino 22/D",
    "sex": "M",
    "subjectSubtype": "4",
    "subjectSurname": "Biasotto",
    "subjectDenomination": "Biasotto Luca",
    "subjectCode": 31031989,
    "discountsManualCumulative": "Y",
    "contractDiscount": 11,
    "contractDescription": "Associazione Alumni 2019",
    "contractCode": "31031989123456",
    "contractEndDate": "2021-03-02 23:00:00",
    "country": "IT",
    "isCompany": "N",
    "pec": "luca.biasotto@xxxx.pec.it",
    "paIndex": "",
    "companyVatCode": "",
    "invoiceChannel": "STORE"
  },
  "branchCode": "1001",
  "onlineValidation": "N",
  "filling": "LAST",
  "appliedPromotions": [],
  "ticketRT": "",
  "candidatePromos": [],
  "items": [
    {
      "rowId": "{{$guid}}",
      "rowType": "ITEM",
      "barcode": "010005600109",
      "barcodeType": "BARCODE_ARTICOLO",
      "unitPrice": 19.9,
      "qty": 1,
      "qtyType": "N",
      "itemState": "SERVER_OK",
      "seller": "Marco Bianchi",
      "sellerId": "1001",
      "taxRate": 22,
      "vatCode": 20,
      "rowTaxableIncome": 13.66,
      "rowVat": 3,
      "rowTotal": 16.66,
      "description": "POLO IN COTONE PIQUET",
      "discount": 10,
      "discountReason": "31031989123456",
      "discountReasonDescription": "Associazione Alumni 2019",
      "discountType": "P",
      "discountAmount": 1.99,
      "itemType": "PRODUCT",
      "qtaConfirmed": "Y",
      "movementType": "V",
      "printerDepartmentCode": 2,
      "note": "",
      "havingTailoring": "N",
      "itemCode": "BO00P794101",
      "imgUrl": "https://storage.googleapis.com/app-mobileshop-items-images/BOGGI/500/210/BO00P794101/BLU/M/BO00P794101_BLU_M_1.jpg?GoogleAccessId=711439762495-38h1rs18fbp4scgt4th1gqok4qjltb2u@developer.gserviceaccount.com&Expires=1580995352202&Signature=DPpknotgLGvIFsbPrRL2k7DWj6pcJ6TeSSwc0nmK1X%2BFjIOx0s24KtBcsTAy7%2FOiHFSnfa5Dx4c%2BwoDx9RLRvta9qSjAOYm56QY0dznpVCjHUIDxRyyQslQY%2F69GzA3vFo1O4O1HjFlGWNCRT0SV05zhazeamzjR4u5M%2FVCLMjU%3D",
      "currencySymbol": "€",
      "currency": "EUR",
      "rounding": 2,
      "shopDescription": "POLO IN COTONE",
      "dimensionDescription1": "M",
      "dimensionDescription2": "BLU",
      "dimension1": "9",
      "dimension2": "BLU",
      "dimensionType1": "TAGLIA",
      "dimensionType2": "COLORE",
      "dimensionType3": "DROP",
      "dimensionType4": "STATURA",
      "dimensionType1Desc": "Taglia",
      "dimensionType2Desc": "Colore",
      "oldUnitPrice": 19.9,
      "oldTaxRate": 22,
      "priceList": "1001",
      "autoDiscountType": "CONTRACT",
      "discountTotalAmount": 3.24,
      "contractCode": "31031989123456",
      "discountRowTotalAmount": 1.25,
      "discountType1": "",
      "discount1": "",
      "discountAmount1": "",
      "discountReason1": "",
      "discountType2": "",
      "discount2": "",
      "discountAmount2": "",
      "discountReason2": "",
      "discountType3": "",
      "discount3": "",
      "discountAmount3": "",
      "discountReason3": "",
      "discountType4": "",
      "discount4": "",
      "discountAmount4": "",
      "discountReason4": "",
      "discountType5": "",
      "discount5": "",
      "discountAmount5": "",
      "discountReason5": "",
      "rowOrder": 1,
      "channel": "INSTORE"
    },
    {
      "rowId": "{{UUID}}-r2",
      "rowType": "ITEM",
      "barcode": "010005600108",
      "barcodeType": "BARCODE_ARTICOLO",
      "unitPrice": 19.9,
      "qty": 1,
      "qtyType": "N",
      "itemState": "SERVER_OK",
      "seller": "Marco Bianchi",
      "sellerId": "1001",
      "taxRate": 22,
      "vatCode": 20,
      "rowTaxableIncome": 13.66,
      "rowVat": 3,
      "rowTotal": 16.66,
      "description": "POLO IN COTONE PIQUET",
      "discount": 10,
      "discountReason": "31031989123456",
      "discountReasonDescription": "Associazione Alumni 2019",
      "discountType": "P",
      "discountAmount": 1.99,
      "itemType": "PRODUCT",
      "qtaConfirmed": "Y",
      "movementType": "V",
      "printerDepartmentCode": 2,
      "note": "",
      "havingTailoring": "N",
      "itemCode": "BO00P794101",
      "imgUrl": "https://storage.googleapis.com/app-mobileshop-items-images/BOGGI/500/210/BO00P794101/BIANCO/M/BO00P794101_BIANCO_M_1.jpg?GoogleAccessId=711439762495-38h1rs18fbp4scgt4th1gqok4qjltb2u@developer.gserviceaccount.com&Expires=1580995356963&Signature=rBd%2FdJCPp9WEKPaPqPJWq46bqZAmL%2BsbyHlwiB%2B1M1P%2Boml1FAn3Xwe0mg1nwekFT0iUFR80IFOF0TQCQe5xkeZoCworrUPHPQVzs7c%2B6PRevr0HD7Ch6%2BcjgQ%2Fd4jtxwY%2BsbknjN5%2FrgXUJzICKUtmKu28nI%2FRxXYqxOsCwqdc%3D",
      "currencySymbol": "€",
      "currency": "EUR",
      "rounding": 2,
      "shopDescription": "POLO IN COTONE",
      "dimensionDescription1": "S",
      "dimensionDescription2": "BIANCO",
      "dimension1": "8",
      "dimension2": "BIANCO",
      "dimensionType1": "TAGLIA",
      "dimensionType2": "COLORE",
      "dimensionType3": "DROP",
      "dimensionType4": "STATURA",
      "dimensionType1Desc": "Taglia",
      "dimensionType2Desc": "Colore",
      "oldUnitPrice": 19.9,
      "oldTaxRate": 22,
      "priceList": "1001",
      "autoDiscountType": "CONTRACT",
      "discountTotalAmount": 3.24,
      "contractCode": "31031989123456",
      "discountRowTotalAmount": 1.25,
      "discountType1": "",
      "discount1": "",
      "discountAmount1": "",
      "discountReason1": "",
      "discountType2": "",
      "discount2": "",
      "discountAmount2": "",
      "discountReason2": "",
      "discountType3": "",
      "discount3": "",
      "discountAmount3": "",
      "discountReason3": "",
      "discountType4": "",
      "discount4": "",
      "discountAmount4": "",
      "discountReason4": "",
      "discountType5": "",
      "discount5": "",
      "discountAmount5": "",
      "discountReason5": "",
      "rowOrder": 2,
      "channel": "INSTORE"
    }
  ],
  "transactionState": 1,
  "startDate": "2020-02-06 13:12:30",
  "printerSerial": "",
  "forceUndoAll" : false,
  "callback" : "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Orchestrated Order

Save A New Sale Order#

Actors#

Preconditions#

Main Success Scenario#

Movement type movementType#

Payments payments#

Field receiptType#

Callback#

Alternate Flows#

Sequence Diagram (Mermaid)#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Save A New Sale Order

Actors

Preconditions

Main Success Scenario

Movement type `movementType`

Payments `payments`

Field `receiptType`

Callback

Alternate Flows

Sequence Diagram (Mermaid)

Code Examples in Node.js