Save Sale Order

Create Sales Order Document

This API allows external systems, such as e-commerce platforms, to create a sales order document in the 4ws.trade suite. Once an order is placed by a customer, the system forwards the details to 4ws.trade, enabling processing and fulfillment through the Manager application.

Document prices

The external system must ensure that prices in the documents are valued according to the following rules:

priceSale: the product's selling price is a gross VAT amount;

priceInvoice: the product's invoice price (purchase invoice) is a net VAT amount;

pricePurchase: the product's purchase price (typically purchase order) is a net VAT amount.

For more detail about sale order features please refer to E-commerce Order sale Processing and E-commerce Return Order Processing.

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.

Mandatory fields in documentHeader and documentRows must be included in the payload.

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

Maximum Number Of Rows

The maximum number of rows for calls is 999, if 1000 or more rows are passed the following error will be returned: Exceeded row limit for document

Payment

The order can accept a single payment method in the paymentCode field and only accepts payment codes enabled for the Manager application.
To find out the payment methods, check the "Payment Methods" master data in KeepIT, or in the PAYMENT_METHODS_EXPORT export CSV.

Main Success Scenario

API Client sends a POST request with order details, customer information, and a callback URL.

4ws.trade acknowledges receipt by returning:

success: Confirms the request was received.

id: A unique identifier for tracking the document.

The platform processes the order asynchronously and sends the final details to the callback URL, including:

id: Document identifier.

barcode: Barcode for the document must be unique.

documentNumber: The sales order number must be unique.

documentStatus: Final status of the document

OPEN: the order can be updated or modified with new products, discounts, quantities etc... .

CLOSE: the order is ready for fulfillment and the products, quantities, discounts are final.

SKU Management in Document Handling

The SKU of a product to be managed in the document can be specified in two different ways:

Using Product Code and Barcode

"itemCode": "010223_PANTA_ROSSO",
"barcode": "2000013787231"

In this case, the suite automatically retrieves the dimensions associated with the product's barcode.

Using Product Code and Dimensions

"itemCode": "010223_PANTA_ROSSO",
"dimension1": "..",
"dimension2": "..",
"dimension3": ".."

In this scenario, the suite retrieves the barcode associated with the specified SKU. If multiple barcodes are linked to the same SKU, one will be selected at random.

ODV (Order Document Open)

If documentStatus is OPEN API creates only the sales order document in an open state. Goods are neither committed nor issued. Operators must manually close the order from the Order Management functionality in Manager before proceeding with fulfillment.

ODV (Order Document Closed)

If documentStatus is OPEN API creates the sales order document in a closed state and the commitment document in an open state. Operators must manually close the delivery request from the Order Management functionality in Manager before proceeding with fulfillment.

Sample Request Payload

Sample Immediate Response

Sample Callback Response

Alternate Flows

Invalid Request: Missing required fields or incorrect data will result in an error response.

Callback Failure: If the callback URL is unavailable, the document details can be retrieved manually using the id.

Maximum Number Of Rows: If 1000 or more rows are passed the following error will be returned: Exceeded row limit for document.

Callback Response

The callback URL receives the processed document details asynchronously. Ensure the callback endpoint is prepared to handle POST requests with the structure described above.

Callback Response

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

Send Sales Order Request:

Request

Query Params

Header Params

Body Params application/json

Example

{
  "documentHeader": {
    "id": "02931b8a-a6c8-4e47-b3f1-041ffb1e432q",
    "branchCode": 2,
    "currency": "EUR",
    "currencySymbol": "€",
    "discount": 10,
    "discountType": "P",
    "documentDate": "2022-05-30 00:00:00",
    "deliveryDate": "2022-05-31 00:00:00",
    "confirmationDateOrder": "2022-05-31 00:00:00",
    "documentType": "ORDER",
    "cause": "SALE",
    "commitmentBranchCode": 1001,
    "docNumberDigital":"WEB00001",
    "system" : "ECOMMERCE",
    "cardBarcode" : "00055584848486",
    "clientDescription": "Mario Rossi",
    "billingAddress": "Via Roma, 1",
    "billingCity": "Roma",
    "billingCompanyName": "Rossi Mario",
    "billingCountry": "IT",
    "billingDenomination": "Rossi Mario",
    "billingEmail": "mario.rossi@email.mail",
    "billingIsCompany": "Y",
    "billingName": "Mario",
    "billingPec": "rossi.pec@pecpec.it",
    "billingPhone": "334.384.848.44",
    "billingSdiCode": "2234455",
    "billingSubjectCompanyName": "Rossi Mario",
    "billingSurname": "Rossi",
    "billingVatCode": "08100750010",
    "billingZipCode": "30801",
    "shippingAddress1": "Viale Repubblica 22",
    "shippingCity": "Roma",
    "shippingCountry": "IT",
    "shippingProvince": "RM",
    "shippingSubjectCompanyName": "Rossi Mario",
    "shippingZipCode": "02589"
  },
  "documentRows": [
    {
      "itemCode": "ITEM_CODE",
      "barcode": "010005600109",
      "quantity": 1,
      "taxRate": 22,
      "unitPrice": 19.9
    }
  ],
  "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Create Sales Order Document#

Actors#

Preconditions#

Payment#

Main Success Scenario#

SKU Management in Document Handling#

ODV (Order Document Open)#

ODV (Order Document Closed)#

Alternate Flows#

Callback Response#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Create Sales Order Document

Actors

Preconditions

Payment

Main Success Scenario

SKU Management in Document Handling

ODV (Order Document Open)

ODV (Order Document Closed)

Alternate Flows

Callback Response

Sequence Diagram

Code Examples in Node.js