Orchestrated Return order

Orchestrated Return Order

This service allows the creation of a return order and its corresponding administrative document starting from an existing sales document.

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

Depending on the type of the original sales document, the system automatically issues the proper return document:

If the original administrative document is a receipt, a return receipt will be created.

If the original administrative document is an invoice, a credit note will be generated.

Orchestrated Order

Orchestrated orders can create administrative invoice documentType: TAX_DOCUMENT, cause:INVOICE, or receipt documents documentType: TAX_DOCUMENT, cause:RECEIPT, to close the sale.

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Callback Endpoint (Webhook): The remote URL that receives the asynchronous notification (callback) confirming the creation result of the return order and document.

Preconditions

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

The original sales document must exist (INVOICE or RECEIPT) and be identified by its unique originalId.

Each referenced row refDocumentRow (INVOICE or RECEIPT) must belong to the same original document.

Callback Endpoint (External Client): The callback used by Four Way Shop to asynchronously notify the client of success/failure and to return the order ID must be handled (How Testing callback response).

Monitoring / Alerting System: Handling integration errors and retries logs and warnings, as reported inBest Practices for Error Handling in External System.

Main Success Scenario

API Client sends a Get Document to retireve Invoice or receipt document.

API Client sends a POST request to the Orchestrated Return order API, providing the necessary headers and JSON payload (utilizzando i riferimenti della risposta della precendete API).

Four Way Shop validates the input data:

It checks that the provided originalId corresponds to a valid administrative document.

It verifies that each refDocumentRow belongs to that same document.

If validation passes, the backend:

Order Return for original sale.

Goods Receipt Note returns the goods to the warehouse of the branch that issued the administrative document.

Credit Note or Return Receipt for original invoices o reciept.

Sends the operation result to the specified callback URL.

The POS receives a confirmation from the callback webhook, confirming that the return process was successfully completed.

📌

This returns the goods to the warehouse of the location that issued the administrative document.
The Four Way Shop (Manager) features allow you to check the goods moved.

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.

Mandatoy fields: If the required information is not provided, an error is returned with the missing information.

Mandatoy fields Errors

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

Mandatory documentNumber or barcode: If document Number or barcode are not set, an error is returned.

Invalid Original Document Error

Invalid Original Document: If the provided originalId does not match any known document, the service will return an error in the callback with a detailed message describing the problem.

Invalid Original Document Error

Mismatched Document Rows: If a refDocumentRow belongs to a different document than the one specified in originalId, the backend validation fails and the callback contains an error message.

Mismatched Document originalId Error

Returned Rows Refer To Different Invoices Error

Manually managed Document: If the sales order was orchestrated manually by operators this can only be made manually by the Four Way Shop (Manager) features.

Manually managed Document Error

Invalid Returned Quantity: If you request a return of a quantity greater than that sold, a message is returned containing the identifier of the row in error.

Invalid Returned Quantity Error

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 Example in Node.js

Request

Query Params

Header Params

Body Params application/json

Example

{
    "documentHeader": {
        "documentDate": "2025-10-02 12:50:29",
        "originalId": "a8cddd89-92e0-42ae-adbd-eb0bd14fb92c",
        "documentNumber": "144-2025",
        "barcode": "9004123"
    },
    "callback": "https://webhook.site/8141a677-df5e-4f39-864b-641c960464c8",
    "documentRows": [
        {
            "returnReasonDescription": "Reso cliente",
            "refDocumentRow": "01104e6c-4a0e-49ea-aab6-3e6cacf77c42",
            "quantity": 1
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Orchestrated Return order