E-commerce Order sale Processing

E-Commerce Sale Order Processing

Use Case Description

This document describes the use case for an e-commerce system that, upon collecting a sales order, sends it to 4ws.trade using the Save Order service for the virtual e-commerce store. Based on the available stock in the network of physical stores, the system specifies in the commitmentBranchCode parameter which warehouse will commit and subsequently ship the goods.

Actors

Ecommerce System: The external system initiating the order processing and stock commitment.

4ws.trade Service: The service handling the creation of sales orders and stock commitment documents.

Preconditions

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

APIs Used

Save Order

Purpose: create a e-commerce sale order document.

Input: JSON containing the document with header information and product line items (items) being sold.

Output: JSON of the result operation.

Date fields

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

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.

If the fields priceSale is mandotary instead priceInvoice, and pricePurchase are not provided, the system will attempt to retrieve prices based on the branchCode and the sale, invoice, and purchase price lists. If no matching price is found, the API will return an error, and the document will not be created.

Main Success Scenario

Order Collection: The e-commerce system collects a sales order from a customer.

Send Order to 4ws.trade: The order is sent to 4ws.trade using the Save Order service.

Specify Commitment Branch: The system specifies which warehouse commitmentBranchCode will commit and ship the goods.

Callback Handling: The e-commerce system handles the callback from 4ws.trade to confirm the processing result.

Warehouse Operations:

Close the sales order and create the commitment document.

Create the goods issue document to remove the goods from stock.

Create the invoice document to finalize the sale.

Alternate Flows

If the document creation fails, an error message is returned, and the external system may retry the request.

JSON Structure for Sales Order Document

{
  "documentHeader": {
    "id": "02931b8a-a6c8-4e47-b3f1-041ffb1e432q",
    "branchCode": 2,
    "currency": "EUR",
    "currencySymbol": "€",
    "discount": 10,
    "discountType": "P",
    "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",
    "appearance": "BOXES",
    "transportType": "V",
    "carrierCode": "BART",
    "carrierAddress":"Via Bart 22",
    "withdrawalDate": "2022-06-01 00:00:00",
    "step":"ODV"
  },
  "documentRows": [
    {
      "barcode": "010005600109",
      "dimension1": "9",
      "dimension2": "BLU",
      "dimension3": ".",
      "dimension4": ".",
      "itemCode": "BO00P794101",
      "quantity": 1,
      "taxRate": 22,
      "unitPrice": 19.9
    }
  ],
  "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

Callback Response Structure

Success Response

{
  "success": true,
  "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aca"
}

Error Response

{
  "success": false,
  "id": "64ee5dda-d2b5-4fbc-ae6d-fbd2ff13352b",
  "message": "Invalid barcode value: 87654321 at row: 1"
}

e-commerce and transactionId

It is strongly recommended that the e-commerce site stores the unique sale order ID 02931b8a-a6c8-4e47-b3f1-041ffb1e432q and links it uniquely to the collected order.

Warehouse Operations

After the order is created in 4ws.trade, warehouse operators are required to:

Close the Sales Order: Create a commitment document that reserves the goods for the order.

Create the Goods Issue Document: Remove the goods from the stock of the store or warehouse.

Create the Invoice Document: Finalize the sale by generating the invoice.

Automation with `step` Parameter

ODV (Order Document Open): 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.

RDC (Request Delivery Confirmation): 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.

Sequence Diagram

INFO

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

Code Examples in Node.js

Sending the Order

Conclusion

This document outlines the process of sending a sales order from an e-commerce system to 4ws.trade, specifying stock commitment, handling callbacks, and managing warehouse operations. Following the best practices for integration will ensure a smooth and reliable order processing workflow.

Return sale

If the goods sold are returned by the customer, the e-commerce must send the return movement through a return order that will return the goods to the warehouse.
Refer to the use case e-commerce Return Order Processing with 4ws.trade

E-commerce Order sale Processing

E-Commerce Sale Order Processing#

Use Case Description#

Actors#

Preconditions#

APIs Used#

Document prices#

Main Success Scenario#

Alternate Flows#

JSON Structure for Sales Order Document#

Callback Response Structure#

Success Response#

Error Response#

Warehouse Operations#

Automation with step Parameter#

Sequence Diagram#

Code Examples in Node.js#

Sending the Order#

Conclusion#

Return sale#

E-Commerce Sale Order Processing

Use Case Description

Actors

Preconditions

APIs Used

Document prices

Main Success Scenario

Alternate Flows

JSON Structure for Sales Order Document

Callback Response Structure

Success Response

Error Response

Warehouse Operations

Automation with `step` Parameter

Sequence Diagram

Code Examples in Node.js

Sending the Order

Conclusion

Return sale