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 Free Entry

POST
/api
Last modified:2025-09-03 13:41:35

Create Free Goods Entry Document#

This API allows users to create a free goods entry document for a specific site. The document can include various details such as supplier information, item codes, quantities, pricing, and additional notes. Once submitted, the API processes the request asynchronously and returns a unique identifier for the created document, allowing users to track the status of their entries.
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.

Alternate Flows#

Invalid Input Data: If the input data fails validation (e.g., incorrect barcode), the API returns success: false with an appropriate error message.
Authentication Failure: If the credentials provided are invalid, the API will not process the request and will return an error indicating authentication failure.
Maximum Number Of Rows: If 1000 or more rows are passed the following error will be returned: Exceeded row limit for document.
Error Response#
{
  "success": false,
  "message": "Error message"
}
Example of Specific Error Response#
{
  "success": false,
  "id": "64ee5dda-d2b5-4fbc-ae6d-fbd2ff13352b",
  "message": "Invalid barcode value: 87654321 at row: 1"
}

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#

Here’s a basic example of how to use the API with Node.js:

Request

Query Params

Header Params

Body Params application/json

Example
{
    "documentHeader": {
        "branchCode": "2",
        "supplierCode": "1",
        "documentType": "FREE_ENTRY",
        "cause": "FREE",
        "currency": "USD",
        "currencySymbol": "$",
        "documentDate": "2023-01-01 00:00:00",
        "system": "KEEPIT",
        "documentStatus": "OPEN"
    },
    "documentRows": [
        {
            "itemCode": "QA7MDNRD1-M80701",
            "barcode": "8059517353712",
            "quantity": "1",
            "taxRate": "3",
            "priceSale": "12",
            "pricePurchase": "1",
            "priceInvoice": "12"
        }
    ]
}

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": {
        "branchCode": "2",
        "supplierCode": "1",
        "documentType": "FREE_ENTRY",
        "cause": "FREE",
        "currency": "USD",
        "currencySymbol": "$",
        "documentDate": "2023-01-01 00:00:00",
        "system": "KEEPIT",
        "documentStatus": "OPEN"
    },
    "documentRows": [
        {
            "itemCode": "QA7MDNRD1-M80701",
            "barcode": "8059517353712",
            "quantity": "1",
            "taxRate": "3",
            "priceSale": "12",
            "pricePurchase": "1",
            "priceInvoice": "12"
        }
    ]
}'

Responses

🟢200Save free entry - success
application/json
Body

Example
{
    "success": true,
    "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aca"
}
🟢200Save free entry - failed
🟠422Unique constraint error
Modified at 2025-09-03 13:41:35
Previous
Save Transfer document
Next
Save Purchase
Built with