Return Order Creation#
Use Case Description#
This use case allows an external system to create a return order and the corresponding administrative document, based on the administrative document issued for the original sales order.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 If the sales administrative document is a receipt, a return receipt will be created.
If the sales administrative document is an invoice, a credit note will be generated.
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 and be identified by its unique originalId retrievable through the API Get Document. Each referenced row (refDocumentRow) 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). APIs Used#
Retrieve Original Sales Document#
The external system must first invoke the API Get Document to retrieve the administrative document related to the original order.The response will include the documentHeader.id and the list of document rows (documentRows.id), required for the next step.Create Return Order#
Once the original document is retrieved, the system invokes the API Orchestrated Return order to create the corresponding return order and fiscal document.The return order document must include the documentHeader.id reference in its originalId. Similarly, the rows to be returned must have the refDocumentRow field set to the documentRows.id of the previously sold 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#
1.
The external system retrieves the original sales administrative document using the Get Document API. 2.
The Four Way Shop validates the request and returns the document’s details, including the originalId and row identifiers.
3.
The external system uses this data to build and send the return order creation request to returnOrder_v1.
4.
The Four Way Shop validates:The existence of the originalId.
The consistency of all refDocumentRow values with the original document.
5.
The backend automatically issues the appropriate return document: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.
6.
The callback endpoint receives an asynchronous response confirming the result.
7.
The external system logs the callback response and updates its records accordingly.
Return All Products#
If the customer intends to return all items from the original invoice or receipt:
Include one element in documentRows for each row in the original document, using the corresponding refDocumentRow.This ensures that the entire sales document content is returned, and all products are restocked.✅ Result: All items are returned, and stock is fully restored to inventory.Return Partial Products#
If the customer returns only part of the order, pay attention to the field quantityReturned of each document row.You can return more items only if:quantity - quantityReturnedInvoice > 0✅ Result: Only the specified row (row-002) is returned, and the system verifies that the remaining available quantity allows the operation.Alternate Flows#
Invalid Reference: If the originalId or refDocumentRow does not match an existing document or row, the API returns an error.
Invalid Original Document: Error in callback (DOCUMENT_NOT_FOUND).
Invalid Rows: Error in callback (INVALID_REF_ROW).
Inconsistent Document Rows: If one or more refDocumentRow values do not belong to the document specified by originalId, the backend rejects the operation.
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#
Code Example in Node.js#
