4WS Suite
Home
API Reference
  • Data mangement API
  • Documents API
Home
API Reference
  • Data mangement API
  • Documents API
Fourwayshop
  1. Warehouse
  • Document Manager
    • Orders
      • Save Sale Order
      • Save Return Order
    • 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
        POST
      • Save Transfer document
        POST
      • Save Free Entry
        POST
    • 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. Warehouse

Save Transfer document

POST
/api
Last modified:2025-09-03 13:39:50

Create Internal goods transfer document#

This API allows the creation of an internal goods transfer document from one branch to another within the same company or between different companies. It enables businesses to manage inventory efficiently during transfers between different locations.
The process involves sending document details and receiving an acknowledgment immediately. Once the document is processed, the final details are sent asynchronously to the specified callback URL.
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.

Actors#

API Client: The system or user initiating the request.
4ws.trade: The backend system that processes the request.
Wharehouse assistant: The individual initiating the document creation (e.g., warehouse manager, inventory controller).

Preconditions#

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.
Mandatory fields in documentHeader and documentRows must be included in the payload.
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#

1.
API Client sends a POST request containing document details and the callback URL.
2.
4ws.trade acknowledges receipt with an immediate response containing:
success: Indicates receipt of the request.
id: A unique identifier for tracking the document.
3.
The platform processes the request asynchronously and sends the final document details to the callback URL.
4.
The Callback Endpoint receives information, including:
id: The document ID.
barcode: The document's barcode.
documentNumber: The unique document number.
documentStatus: The final status of the document
OPEN: the document can be updated or modified with new products, discounts, quantities etc... .
CLOSE: the document 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
SKU Management in Document Handling#
The SKU of a product to be managed in the document can be specified in two different ways:
1.
Using Product Code and Barcode
"itemCode": "010223_PANTA_ROSSO",
"barcode": "2000013787231"
In this case, the suite automatically retrieves the dimensions associated with the product's barcode.
2.
Using Product Code and Dimensions
"itemCode": "010223_PANTA_ROSSO",
"dimension1": "..",
"dimension2": "..",
"dimension3": ".."
In this scenario, the suite retrieves the barcode associated with the specified SKU. If multiple barcodes are linked to the same SKU, one will be selected at random.
Use Case Description: Goods Transfer Between Branches#
This use case involves the transfer of goods between different branches or warehouses within the same company or between branches of different companies. The purpose of this transfer is to manage inventory effectively and ensure that goods are available where they are needed.
Transfer Between Branches of Same Companies
Transfer Between Branches of Different Companies
Description: In this scenario, goods are transferred from one branch to another within the same company. The branches share the same company ID but have different branch codes (unique identifiers).
Example:
Source Branch: Warehouse A (branchCode: 6667)
Destination Branch: Warehouse B (branchCodeAddresse: 9999)
Transfer Branch: Temporary warehouse (branchCodeTransfer: 103)
Sample Request Payload
branchCode: The code of the source branch from which goods are being transferred.
branchCodeAddresse: The code of the destination branch where goods are being sent.
branchCodeTransfer: The code of the temporary transfer warehouse that may be used during the transfer.
createOpposingDocument: If the createOpposingDocument parameter is Y, in addition to the internal transfer document in the CLOSED state, the transfer load document will also be created in the OPEN state so that the store or warehouse can proceed with the verification of the goods. For details on document types, refer to paragraph Documents structure.
closeOpposingDocument: The closeOpposingDocument parameter is used when createOpposingDocument is Y. If closeOpposingDocument parameter is Y the transfer load document will be created in the CLOSED state. For details on document types, refer to paragraph Documents structure.
For Intra-Company Transfers:
When createOpposingDocument is set to "Y":
The transfer document is created in the state "CLOSED."
A corresponding receipt document is created at the destination in the state "OPEN."

Alternate Flows#

Invalid Request: If the payload contains errors or missing data, the platform responds with an error.
Sample Error Response
Callback Failure: If the callback URL is unreachable, the document details can be retrieved manually using the id.
Sample Error Response
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 Goods Transfer Request:

Request

Query Params

Header Params

Body Params application/json

Example
{
    "documentHeader": {
        "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aea",
        "branchCode": 2,
        "branchCodeAddresse": 9,
        "branchCodeTransfer": 103,
        "cause": "EXIT",
        "currency": "EUR",
        "currencySymbol": "€",
        "documentDate": "2022-05-30 00:00:00",
        "documentType": "SD_INT_TRASFER",
        "createOpposingDocument": "Y"
    },
    "documentRows": [
        {
            "barcode": "87654321",
            "quantity": 1,
            "taxRate": 22,
            "priceSale": 19.9,
            "pricePurchase": 19.9,
            "priceInvoice": 19.9
        }
    ],
    "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": {
        "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aea",
        "branchCode": 2,
        "branchCodeAddresse": 9,
        "branchCodeTransfer": 103,
        "cause": "EXIT",
        "currency": "EUR",
        "currencySymbol": "€",
        "documentDate": "2022-05-30 00:00:00",
        "documentType": "SD_INT_TRASFER",
        "createOpposingDocument": "Y"
    },
    "documentRows": [
        {
            "barcode": "87654321",
            "quantity": 1,
            "taxRate": 22,
            "priceSale": 19.9,
            "pricePurchase": 19.9,
            "priceInvoice": 19.9
        }
    ],
    "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}'

Responses

🟢200Save transfer - success
application/json
Body

Examples
{
    "success": true,
    "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aca"
}
🟠422Unique constraint error
🟢200Error
Modified at 2025-09-03 13:39:50
Previous
Save Entry from supplier
Next
Save Free Entry
Built with