4WS Suite
Home
API Reference
  • Data mangement API
  • Documents API
Home
API Reference
  • Data mangement API
  • Documents API
Fourwayshop
  1. Orders
  • Document Manager
    • Orders
      • Save Sale Order
        POST
      • Save Return Order
        POST
    • Orchestrated Orders
      • Orchestrated Order
      • Orchestrated Return order
      • Orchestrated Update order
    • Cart
      • Cart Validation
      • Cart Full Validation
    • Sales
      • Save receipt
      • Salve only Order
      • Replace or update sale
      • Get last digital order
    • Warehouse
      • Save Entry from supplier
      • Save Transfer document
      • Save Free Entry
    • Purchase
      • Save Purchase
    • Get Document
      GET
    • Update Document external references
      POST
  • Customer
    • Get Customer
      GET
    • Set Customer Opt-in
      POST
  • Loyalty vouchers
    • Get customer loyalty vouchers
      GET
    • Get loyalty vouchers at a time interval
      GET
    • Get last loyalty vouchers
      GET
  • Giftcard
    • Get Giftcard
      GET
    • Update Giftcard
      POST
    • Generate Gift Card Barcode
      POST
    • Gift Card PDF Generation
      POST
  • Stock
    • Get Stock
      POST
    • Get last stock
      GET
    • Insert Stock
      POST
  1. Orders

Save Return Order

POST
/api
Last modified:2025-04-10 07:53:58

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#
1.
API Client sends a Get Document to retireve Invoice document.
2.
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.
3.
4ws.trade acknowledges the request by returning:
success: Confirms receipt of the request.
id: A unique identifier for tracking the return order document.
4.
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
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST '/api?cmd=saveDocument_v1&applicationId={{APPLICATION_ID}}&appId={{APPLICATION_ID}}' \
--header 'applicationId: {{APPLICATION_ID}}' \
--header 'appId: {{APPLICATION_ID}}' \
--header 'namespace: {{NAMESPACE}}' \
--header 'languageId: {{LANGUAGE}}' \
--header 'username: {{USERNAME}}' \
--header 'password: {{PASSWORD}}' \
--header 'companyId: {{COMPANY_ID}}' \
--header 'siteId: {{SITE_ID}}' \
--header 'loadRoles: Y' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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"
}'

Responses

🟢200Save Return - under development - success
application/json
Body

Example
{
    "success": true,
    "id": "bc408157-762e-4bc7-ba98-2b799c5d8ac0"
}
🟢200Save Return - under development - failed
🟠422Unique constraint error
Modified at 2025-04-10 07:53:58
Previous
Save Sale Order
Next
Orchestrated Order
Built with