E-commerce Return Receipt Processing

Use Case Description

Registered the sales receipt (E-commerce Recipt Processing with 4ws.trade) of an e-commerce that collected the order, this use case describes the process by which an e-commerce platform handles customer returns through the 4ws.trade service.
When a customer initiates a return, the e-commerce system generates a return receipt and sends it to 4ws.trade.
The service processes the return receipt and sends a callback with the processing result. Store clerks then handle the physical return of the merchandise, print the return receipt, and issue a refund to the customer.

WARNING

By using the API as specified in this documentation, the document will be recorded as unfiscalized (not printed).
The salesperson will still have the option to print the document later using the MobileShop application.
This functionality allows for efficient handling of document processing and printing.

Actors

E-commerce System: The external system initiating the return receipt processing.

4ws.trade Service: The service Save sale handling the creation of return receipts and subsequent processing documents.

Store Clerks: The clerks or warehouse workers for verifying the returned items, printing the return receipt, and refunding the customer.

Preconditions

An existing sale order must be present in the system.

The customer initiates a return request through the ecommerce platform.

The return receipt request is correctly formatted and sent to 4ws.trade.

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

APIs Used

Save sale: API endpoint to create a return receipt 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 Receipt Collection: The ecommerce system collects a return request from a customer.

Send Return Receipt to 4ws.trade: The return receipt is sent to 4ws.trade using the saveSale service.

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

Store Operations:

Store clerks receive the return receipt.

Verify the returned items match the receipt.

Print the return receipt.

Proceed with the customer refund.

Alternate Flows

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

JSON Structure for Return Receipt Document

{
    "barcodeInfo": "10012220071500002",
    "branchCode": "1001",
    "currency": "EUR",
    "currencySymbol": "€",
    "deviceId": "945d8af21d80556a",
    "discountsManualCumulative": "Y",
    "docNumber": 2,
    "endDate": "2020-07-15 09:39:30",
    "entityCode": "210",
    "filling": "LAST",
    "movementType": "R",
    "pointsCode": "CUSTOMER_NOT_FOUND",
    "pointsMessage": "Customer NOT found",
    "printerSerial": "XXXXX-XXXXX-XXXXX",
    "registerCode": 22,
    "seller": "Marco Bianchi",
    "sellerId": 1001,
    "startDate": "2020-07-15 09:39:26",
    "startDateRef": "2020-07-15 09:33:35",
    "ticket": 2,
    "ticketRT": "XXXX",
    "ticketRTRef": "XXXXXX",
    "transactionId": "257ba40c-59e2-43d2-a6f4-47c2b98662fc",
    "zReportNumber": "#####",
    "zReportNumberRef": "####",
    "goodsVoucher":
    [
        {
            "barcode": "8015948279786",
            "amount": 19.9,
            "description": "Buono merce",
            "itemType": "FINANCIAL",
            "itemSubType": "GOOD_PURCHASE",
            "itemCode": "GOOD210_001",
            "validityDays": 30,
            "taxRate": 22,
            "vatCode": 20,
            "endDate": "2020-08-14 11:39:30",
            "zReportNumber": "0474",
            "ticketRT": "XXXXXX",
            "printerSerial": "XXXXXXXX",
            "docNumber": 3
        }
    ],
    "items":
    [
        {
            "barcode": "010005600108",
            "barcodeType": "BARCODE_ARTICOLO",
            "currency": "EUR",
            "currencySymbol": "€",
            "description": "POLO IN COTONE PIQUET",
            "dimension1": "8",
            "dimension2": "BIANCO",
            "dimensionDescription1": "S",
            "dimensionDescription2": "BIANCO",
            "dimensionType1": "TAGLIA",
            "dimensionType1Desc": "Taglia",
            "dimensionType2": "COLORE",
            "dimensionType2Desc": "Colore",
            "dimensionType3": "DROP",
            "dimensionType3Desc": "Drop",
            "dimensionType4": "STATURA",
            "dimensionType4Desc": "Statura",
            "itemCode": "BO00P794101",
            "itemType": "PRODUCT",
            "movementType": "R",
            "note": "CAUSALE: Non piace , NOTE: Non piace perchè:",
            "oldTaxRate": 22,
            "oldUnitPrice": 19.9,
            "priceList": "1001",
            "printerDepartmentCode": 2,
            "qty": 1,
            "qtyType": "N",
            "returnNote": "Non piace perchè:",
            "returnReason": "Non piace",
            "rounding": 2,
            "rowId": "2fe567cf-b59a-42bb-9713-053b4539a0c1",
            "rowIdRef": "dc3eee75-097b-4424-bd60-bba859ed05c4",
            "rowOrder": 1,
            "rowTaxableIncome": 16.31,
            "rowTotal": 19.9,
            "rowType": "ITEM",
            "rowVat": 3.59,
            "seller": "Marco Bianchi",
            "sellerId": 1001,
            "shopDescription": "POLO IN COTONE",
            "taxRate": 22,
            "unitPrice": 19.9,
            "vatCode": 20
        }
    ],
    "payments":
    [
        {
            "paymentCash": 19.9,
            "paymentAmount": 19.9,
            "paymentType": "B",
            "paymentCode": 52
        }
    ],
    "totals":
    {
        "total": 16.31,
        "allowance": 0,
        "alreadyPayed": 0,
        "taxableIncome": 16.31,
        "vat": 3.59,
        "grandTotal": 19.9
    },"callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

Documentation for Handling `rowIdRef` in Return Documents

Overview

When processing a return in the e-commerce system, it is essential to establish a clear reference between the return document and the original sales document. The rowIdRef field plays a crucial role in this process by linking each line item in the return document to the corresponding line item in the original sales document.

`rowIdRef` Field

Purpose: The **rowIdRef** field is used to uniquely identify and reference the specific line item from the original sales document that is being returned. This ensures that the system can accurately track which products are being returned and apply the appropriate processing, such as inventory adjustments, refunds, or exchanges.

Value: The **rowIdRef** must be populated with the UUID of the line item in the original sales document. This UUID serves as a unique identifier, allowing the system to directly link the return to the exact line item in the original transaction.

Implementation Guidelines

Retrieving the UUID:

When a return is initiated, the system should retrieve the UUID for each line item from the original sales document.

This UUID should be stored in the rowIdRef field of the corresponding line item in the return document.

Populating the rowIdRef:

During the creation of a return document, each line item must have its rowIdRef field populated with the UUID of the original sales line item.

This step is mandatory to ensure accurate processing of the return.

Example:

Suppose a customer returns an item that was originally purchased with a UUID of 123e4567-e89b-12d3-a456-426614174000.

The return document for this item should have its rowIdRef field set as follows:

Validation:

Before finalizing the return document, the system should validate that every rowIdRef corresponds to an existing UUID in the original sales document.

Any discrepancies or missing references should trigger an error, preventing the return from being processed until the issue is resolved.

Benefits of Proper `rowIdRef` Usage

Accuracy: By correctly linking returns to original sales, the system ensures precise inventory management, financial reporting, and customer service.

Traceability: Maintaining this reference allows for detailed tracking of products throughout the sales and return cycle, which is crucial for auditing and customer support.

Efficiency: Automated processing based on rowIdRef reduces the potential for manual errors and accelerates the return handling process.

This documentation should be followed to ensure that all return transactions are handled consistently and accurately within the e-commerce system.

Goods Voucher Creation

In the goodsVoucher section of the return receipt, it is possible to request the creation of a goods voucher. This voucher can be issued to the customer as a refund for the value of the returned merchandise. The goods voucher serves as a store credit, allowing the customer to use it for future purchases within the ecommerce platform or at physical store locations. This approach provides a flexible and customer-friendly alternative to direct monetary refunds, encouraging repeat business and enhancing customer satisfaction. The specific details and value of the goods voucher can be specified in the goodsVoucher section when generating the return receipt document sent to 4ws.trade.

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

This description clarifies how the e-commerce site integrates with the 4ws.suite APIs to manage the sales process and receipt registration.

INFO

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

Clecks operation

Upon receiving the return receipt, store clerks must perform the following operations to ensure the proper processing of the returned merchandise:

Await Package Arrival

Wait for the customer's return package to arrive.

Verify Contents:

Check that the contents of the package match the items listed in the return receipt. This includes verifying quantities, item conditions, and matching barcodes.

Print Return Receipt

Once verification is complete, print the return receipt document.

Process Refund

Proceed with refunding the customer. This can be done through the issuance of a goods voucher, direct monetary refund, or other methods as appropriate.

These steps ensure that the returned merchandise is accurately processed, and the customer receives their refund in a timely manner.

Code Examples in Node.js

Sending the Return Receipt

Conclusion

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

E-commerce Return Receipt Processing