Creating a free entry

Use Case Description

This use case describes the process by which an external system creates a goods receipt document (type FREE_ENTRY with cause FREE) to update the stock of a store or warehouse identified by branchCode. The document creation service allows for stock adjustments based on incoming goods.

Actors

External System: The external system (ERP,WMS ecc...) initiating the order processing and stock transfer.

4ws.trade Service: The service handling the creation of sales and stock transfer documents.

Preconditions

The external system must have the necessary permissions and access to the document creation service, please refer to Authentication.

APIs Used

Save Free Entry

Purpose: create a free entry document to update stocks items.

Input: JSON containing the document with header information and product line items (items) being sold.

Output: JSON of the result operation.

Main Success Scenario

The external system sends a request to the document creation service with the specified JSON payload.

The document is created with the given details.

The 4ws.trade return a success message with a unique document ID.

Alternate Flows

If the document creation fails, an error message is returned, and the external system may retry the request.

JSON Structure for Free entry Document

{
  "documentHeader": {
    "branchCode":"2",
    "supplierCode":"1",
    "documentType":"FREE_ENTRY",
    "cause": "FREE",
    "currency": "EUR",
    "currencySymbol": "$",
    "documentDate":"2023-01-01 00:00:00",
    "movementDate":"2023-01-01 00:30:00",
    "system":"KEEPIT",
    "discountType": "P",
    "discount": "10",
    "documentStatus":"OPEN"
  },
  "documentRows": [
    {
      "itemCode":"AAA",
      "barcode":"XXX",
      "quantity":"1",
      "taxRate":"3",
      "priceSale":"12",
      "pricePurchase":"1",
      "priceInvoice":"12"
    }
  ]
}

documentStatus

Stock is updated if the document status is CLOSE.
If the document status is OPEN, stock is not adjusted until the document is closed by store or warehouse personnel.

Callback Response

The response from the callback service can be:

Success Response:

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

Failure Response:

{
  "success": false,
  "message": "Error message"
}

success: Indicates whether the processing was successful.

id: References the transfer document.

message: Describes the error if the processing failed.

Sequence Diagram

INFO

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Creating a free entry