Save Free Entry

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

API Client sends a POST request containing document details and the callback URL.

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

4ws.trade acknowledges receipt with an immediate response containing:

success: Indicates receipt of the request.

id: A unique UUID identifier for tracking the document.

The platform processes the request asynchronously and sends the final document details to the callback URL.

The Callback Endpoint receives information, including:

id: The document unique UUID identifier.

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 & 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

SKU Management in Document Handling

The SKU of a product to be managed in the document can be specified in two different ways:

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.

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

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

application/json

Bodyapplication/json

Examples

Save free entry - successSave free entry - failed

{
    "success": true,
    "id": "7571b744-8e2d-4dde-99d8-b60c0dff1aca"
}

Create Free Goods Entry Document#

Actors#

Preconditions#

Main Success Scenario#

SKU Management in Document Handling#

Alternate Flows#

Error Response#

Example of Specific Error Response#

Sequence Diagram#

Code Examples in Node.js#