E-commerce Return Order Processing

e-commerce Return Order Processing

Use Case Description

Registered the sales receipt (e-commerce Order sale Processing with 4ws.trade) of an e-commerce that collected the order, this use case describe an e-commerce system that, upon collecting a return order from a customer, sends it to 4ws.trade using the Save Return service for the virtual e-commerce store.

Actors

e-commerce System: The external system initiating the return order processing.

4ws.trade Service: The service handling the creation of return orders and subsequent stock processing documents.

Warehouse Operators: Personnel responsible for verifying and processing the returned items.

Preconditions

An existing sale order must be present in 4ws.trade.

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

APIs Used

Save Return: API endpoint to create a return order in 4ws.trade.

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

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

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

Callback Handling: The e-commerce system receives and processes the callback from 4ws.trade, confirming the processing result.

Warehouse Operations:

Close the return order and create the goods receipt document upon verification of the returned products.

Create the credit note document to finalize the return process.

Alternate Flows

If the return order contains invalid data (e.g., invalid barcode), 4ws.trade returns an error message, and the e-commerce system must handle the error appropriately and possibly retry the operation.

JSON Structure for Return Order Document

{
  "documentHeader": {
    "documentType": "ORDER",
    "documentDate": "2023-06-05 00:00:00",
    "cause": "RETURN",
    "system" : "ECOMMERCE",
    "originalId": "05273ff9-cc23-4a7a-801d-fb334ee4b160",
    "step": 50
  },
  "documentRows": [
    {
      "refDocumentRow": "f0651df1-d385-4c4d-90a0-e2f2f4c19838",
      "returnReasonDescription": "PROVA",
      "quantity": 1
    }
  ],
  "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

Callback Response

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 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

Sending the Return Order

Conclusion

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

E-commerce Return Order Processing