E-commerce Order Handling and Internal Stock Transfer

Use Case Description

This document describes the process of integrating an e-commerce platform with 4ws.trade for handling orders and managing internal stock transfers. Upon receiving an order, the e-commerce platform sends the order details to 4ws.trade using Save sale or Save Order service.
Based on the available stock in physical stores, e-commerce platform sends internal stock transfer documents to 4ws.trade where the sender is the store holding the stock and the recipient is the virtual e-commerce store to move stock to 4ws.trade e-commerce virtual store using Save Transfer document.

INFO

Properly managing stock on your ecommerce site is essential for smooth operations and maintaining customer satisfaction. To learn the best practices for effective stock management, please refer to the detailed paragraph Updating external stock.

Actors

External System: The external system (ERP,WMS ecc...) initiating the order processing and stock transfer.

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

Preconditions

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

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 Flow

Order Collection: The ecommerce system collects an order from a customer.

Send Order to 4ws.trade: The order is sent to 4ws.trade using the Save sale or Save Order service (Save an e-commerce sale in 4ws.suite receipt).

Stock Check: The ecommerce system checks the stock levels across the physical store network (Updating external stock).

Create Transfer Documents: For each product in the order, the system creates a stock transfer document if the product is available in a different store.

Send Transfer Document to 4ws.trade: The transfer document is sent to 4ws.trade for processing.

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

JSON Structure for Stock Transfer Document

For more detail about please refer to sends internal stock transfer documents to 4ws.trade please refer to Save Transfer document documentation.

This is a JSON example of an internal transfer document that the ecommerce site can send to transfer goods from one store to another.

{
  "documentHeader": {
    "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aca",
    "branchCode": 2,
    "branchCodeAddresse": 9,
    "branchCodeTransfer": 103,
    "cause": "EXIT",
    "currency": "EUR",
    "currencySymbol": "€",
    "documentDeliveryExternal": "TRANS-12345",
    "documentDate": "2022-04-19 00:00:00",
    "documentType": "SD_INT_TRASFER",
    "system": "ECOMMERCE",
    "createOpposingDocument": "Y",
    "closeOpposingDocument": "N"
  },
  "documentRows": [
    {
      "barcode": "010005600109",
      "dimension1": "9",
      "dimension2": "BLU",
      "dimension3": ".",
      "dimension4": ".",
      "itemCode": "BO00P794101",
      "quantity": 1,
      "rowNumber": 1,
      "taxRate": 22,
      "priceSale": 19.9,
      "pricePurchase": 19.9,
      "priceInvoice": 19.9
    }
  ],
  "callback":"https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

:::info createOpposingDocument & closeOpposingDocument
If the createOpposingDocument parameter is Y, in addition to the internal transfer document in the CLOSED state, the transfer load document will also be created in the OPEN state so that the store or warehouse can proceed with the verification of the goods. For details on document types, refer to paragraph Documents structure.
The closeOpposingDocument parameter is used when createOpposingDocument is Y. If closeOpposingDocument parameter is Y the transfer load document will be created in the CLOSED state. For details on document types, refer to paragraph Documents structure.
:::

The callback field must be populated with a service URL from the e-commerce platform that 4ws.trade will use to send the processing result.

Callback Response

The response from the callback service can be:

Success Response:

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

Failure Response:

{
  "success": false,
  "message": "Invalid barcode value: 87654321 at row: 1"
}

success: Indicates whether the processing was successful.

id: References the transfer document.

message: Describes the error if the processing failed.

e-commerce and transactionId

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

Sequence Diagram

INFO

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

Code Examples in Node.js

Creating Stock Transfer Document

Callback Service for Processing Transfer Document Result

Monitoring and Error Handling

Retry Failed Transfers Script (`retryFailedTransfers.js`)

Conclusion

The provided code examples illustrate how to integrate an e-commerce platform with 4ws.trade for handling orders and managing internal stock transfers. The examples include sending order details, creating stock transfer documents, and implementing a callback service with error handling and monitoring. By following these best practices and utilizing the provided code, you can ensure a robust and reliable integration with 4ws.trade.

E-commerce Order Handling and Internal Stock Transfer