Save Return Order

Create Return Order Document

This API allows external systems to create a return order document in the 4ws.trade suite, referencing a previously submitted sales order. The return order can be processed through the Manager application. This functionality is designed for scenarios where customers return purchased items.

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.

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.

The sales order to be referenced must exist in the 4ws.trade system.

Before to call save ODR for inserting a ORDER-RETURN document, it's necessary to retrive references of document relative (TAX_DOCUMENT-INVOICE). To do this you must use Get Document api. Later, the response can be used to send the ID referenced to this api.

The originalId field must contain the unique ID of the original sales order, and refDocumentRow field must reference a valid document row ID from the original sales order; Must be an INVOICE Row.

refDocumentRow

The document referenced by the line in refDocumentRow must be of the type TAX_DOCUMENT and cause INVOICE.
For more detail about document type Documents structure.

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

Main Success Scenario

Retrive document information for call

Before to call saveDocument_v1 for inserting a ORDER-RETURN document, it's necessary to retrive references of document relative (TAX_DOCUMENT-INVOICE). To do this you must use getDocument_v1 api. Later, the response can be used to send the ID referenced to saveDocument_v1.

Process Flow

API Client sends a Get Document to retireve Invoice document.

API Client sends a POST request containing:

Details of the return order.

A reference to the original invoice on originalId and specific row(s) being returned onrefDocumentRow.

A callback URL for receiving asynchronous processing updates.

4ws.trade acknowledges the request by returning:

success: Confirms receipt of the request.

id: A unique identifier for tracking the return order document.

The platform processes the return order asynchronously and sends a notification to the callback URL with the final document details, including:

id: Document identifier.

barcode: Barcode for the document.

documentNumber: The return order number.

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.

Document date

All Date information within the API is expressed in the GMT time zone.
API users are therefore responsible for converting dates to their desired time zone if needed.
Please refer to Date Handling

Sample Request Payload

Sample Immediate Response

Sample Callback Response

Alternate Flows

Invalid Reference: If the originalId or refDocumentRow does not match an existing document or row, the API returns an error.

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

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

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 Return Order Request:

Request

Query Params

Header Params

Body Params application/json

Example

{
  "documentHeader": {
    "documentType": "ORDER",
    "documentDate": "2023-06-05 00:00:00",
    "cause": "RETURN",
    "system" : "ECOMMERCE",
    "originalId": "05273ff9-cc23-4a7a-801d-fb334ee4b160"
  },
  "documentRows": [
    {
      "refDocumentRow": "f0651df1-d385-4c4d-90a0-e2f2f4c19838",
      "returnReasonDescription": "PROVA",
      "quantity": 1
    }
  ],
  "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 Return Order Document#

Actors#

Preconditions#

Main Success Scenario#

Retrive document information for call#

Process Flow#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#