Save Entry from supplier

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.

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

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).

Create Goods Arrival Document: The external system sends the prepared JSON request to this API, referencing the purchase order and line items.

Callback Confirmation: 4ws.trade responds via the specified callback URL to confirm successful document creation.

Main Success Scenario

The API Client sends a POST request containing the document header, rows, and callback URL.

The 4ws.trade validates and acknowledges the request by returning a confirmation response:

success: Indicates successful receipt.

id: A unique identifier for tracking the request.

After processing, the platform calls the specified callback URL with the final document details:

id: The document ID.

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

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

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Save Entry from supplier

Create Goods Receipt Document#

Actors#

Preconditions#

Example Use Case Flow#

Main Success Scenario#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#