4WS Suite
Home
API Reference
API Reference
  • Data mangement API
  • Documents API
Home
API Reference
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
      • Orchestrated Sale Order: Cancel Purchased Quantities
    • 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 Reference & Note
      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 Entry from supplier

POST
/api
Last modified:2026-10-16 13:10:16

Create Goods Receipt Document#

This API allows external systems to create an "Arrival to Supplier" document in 4ws.trade, with references to the purchase order document, the following specification includes details of the request structure and field mappings for linking with a purchase order.
This API enables external systems to record goods received from a supplier and ties them to the original purchase order to streamline tracking.
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
The request body must include details about the goods arrival document (type ENTRY) with references to the related purchase order in documentHeader.lstConnectedHeader and in each line item’s refDocumentRow attribute in documentRows.
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 details please refers to Supplier Goods Entry From Purchase Order.

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.
A purchase order document for the supplier must have been registered via Save Purchase or through the Manager application.
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

Example Use Case Flow#

1.
Get Purchase Order ID and Line Item IDs: The external system calls Get Document to retrieve the unique identifiers for the purchase order (lstConnectedHeader) and its line items (refDocumentRow).
2.
Create Goods Arrival Document: The external system sends the prepared JSON request to this API, referencing the purchase order and line items.
3.
Callback Confirmation: 4ws.trade responds via the specified callback URL to confirm successful document creation.

Main Success Scenario#

1.
The API Client sends a POST request containing the document header, rows, and callback URL.
2.
The 4ws.trade validates and acknowledges the request by returning a confirmation response:
success: Indicates successful receipt.
id: A unique UUID identifier for tracking the request.
3.
After processing, the platform calls the specified callback URL with the final document details:
id: The document unique UUID.
barcode: The document's barcode.
documentNumber: The generated document number.
documentStatus: The document's status
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 & row id must be a valid UUID
If the id field is not provided or does not contain a valid UUID, the value will be automatically generated by the suite and will overwrite the value received in the request payload.
The processed document, including the generated id, will then be returned in the service response.
Sample Request Payload
Sample Immediate Response
Sample Callback Response

Alternate Flows#

Invalid Data: If the request payload contains errors or missing fields, an error response is returned.
Callback Failure: If the callback URL is unreachable, the document details must be retrieved manually using the 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 Document Creation Request:

Request

Query Params

Header Params

Body Params application/json

Example
{
    "documentHeader": {
        "branchCode": "9999",
        "supplierCode": "1",
        "documentType": "ENTRY",
        "cause": "REASSORTMENT",
        "currency": "EUR",
        "currencySymbol": "€",
        "documentDate": "2024-10-10 00:00:00",
        "documentStatus": "OPEN",
        "lstConnectedHeader": "a310f914-37fe-4284-b040-36ab048632fc"
    },
    "documentRows": [
        {
            "quantity": "1",
            "refDocumentRow": "e0ed4739-bde8-46a2-aa9a-e38fdf8076b0"
        },
        {
            "quantity": "1",
            "refDocumentRow": "447d8f6e-0b4d-4695-924a-35d0a810cc5f"
        }
    ]
}

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 --globoff '/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 '{
    "documentHeader": {
        "branchCode": "9999",
        "supplierCode": "1",
        "documentType": "ENTRY",
        "cause": "REASSORTMENT",
        "currency": "EUR",
        "currencySymbol": "€",
        "documentDate": "2024-10-10 00:00:00",
        "documentStatus": "OPEN",
        "lstConnectedHeader": "a310f914-37fe-4284-b040-36ab048632fc"
    },
    "documentRows": [
        {
            "quantity": "1",
            "refDocumentRow": "e0ed4739-bde8-46a2-aa9a-e38fdf8076b0"
        },
        {
            "quantity": "1",
            "refDocumentRow": "447d8f6e-0b4d-4695-924a-35d0a810cc5f"
        }
    ]
}'

Responses

🟢200Save Entry from supplier - success
application/json
Bodyapplication/json

Example
{
    "success": true,
    "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aca"
}
🟢200Save Entry from supplier - failed
Modified at 2026-10-16 13:10:16
Previous
Get last digital order
Next
Save Transfer document
Built with