Purchase Order Registration

Purchase Order Registration Use Case Documentation

Use Case Description

This use case describes the process of an ERP system registering a purchase order in the 4ws.trade suite. The external system will invoke the Save Purchase API with a JSON payload containing the document header and the product rows to be purchased.

Actors

ERP System: Initiates the purchase order creation by sending data to 4ws.trade.

4ws.trade Suite: Processes the purchase order data and creates the corresponding document.

Preconditions

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

APIs Used

Save Purchase: API used to create a purchase order document in 4ws.trade.

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.

Main Success Scenario

Purchase Order Creation:

The ERP system sends a POST request to the Save Purchase API with a JSON payload containing the document header and product rows.

The JSON structure includes details such as the branch code, buyer code, currency, supplier code, document type, and product details like barcode, quantity, tax rate, and prices.

Document Processing:

4ws.trade processes the request and attempts to create the purchase order.

If the prices (purchase, invoice, sale) are provided in the request, they are used directly. Otherwise, 4ws.trade retrieves them from the price lists.

item prices

Please refer to Product pricing for details.

Callback Response:

Upon successful creation of the purchase order, 4ws.trade sends a callback with the document ID to the specified callback URL.

If an error occurs, a callback is sent with an error message detailing the issue.

Alternate Flows

Missing or Invalid Data:

If required fields are missing or data is invalid, 4ws.trade will send a callback with a success status of false and an error message.

Document Status Handling:

If documentStatus is set to OPEN, the purchase order is created in an open state.

If documentStatus is set to CONFIRMED, the purchase order is created in a confirmed state, and the purchase movements are tracked, but the final stock is not updated.

JSON Structure for Purchase Order Document

Case 1: Reservation for a Single Branch Location

All items SKU are reserved to the brack location that create the purchase documents.

{
  "documentHeader": {
    "id": "02931b8a-a6c8-4e47-b3f1-041ffb1e412t",
    "branchCode": 2,
    "buyerCode": 2,
    "currency": "EUR",
    "currencySymbol": "€",
    "discountType": "P",
    "discount1": 10,
    "documentDate": "2022-05-30 00:00:00",
    "movementDate": "2022-05-30 00:00:00",
    "confirmationDateOrder": "2022-05-30 00:00:00",
    "deliveryDate": "2022-06-02 00:00:00",
    "supplierCode": "1",
    "documentType": "PURCHASE",
    "cause": "PLANNED",
    "system": "ECOMMERCE",
    "paymentCode": "4",
    "seasonCode": "22AI"
  },
  "documentRows": [
    {
      "barcode": "8000200017671",
      "itemCode": "032B622-2--19059",
      "dimension1": "4",
      "dimension2": "01",
      "dimension3": "4",
      "dimension4": "K",
      "quantity1": 2,
      "taxRate": 22,
      "priceSale": 320,
      "pricePurchase": 150,
      "priceInvoice": 135,
      "discount1": 10,
      "discount2": 20
    }
  ],
  "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

Case 2: Reservation for Multiple Branch Locations

In this case one branch location create the purchase order, but reserve the SKU quantity for other locations.

{
  "documentHeader": {
    "id": "02931b8a-a6c8-4e47-b3f1-041ffb1e412t",
    "branchCode": 2,
    "buyerCode": 2,
    "currency": "EUR",
    "currencySymbol": "€",
    "discountType": "P",
    "discount1": 10,
    "documentDate": "2022-05-30 00:00:00",
    "movementDate": "2022-05-30 00:00:00",
    "confirmationDateOrder": "2022-05-30 00:00:00",
    "deliveryDate": "2022-06-02 00:00:00",
    "supplierCode": "1",
    "documentType": "PURCHASE",
    "cause": "PLANNED",
    "system": "ECOMMERCE",
    "paymentCode": "4",
    "seasonCode": "22AI",
    "reserved": [
      {"type": "SHOP", "code": "2"},
      {"type": "WRH", "code": "1001"}
    ]
  },
  "documentRows": [
    {
      "barcode": "8000200017671",
      "itemCode": "032B622-2--19059",
      "dimension1": "4",
      "dimension2": "01",
      "dimension3": "4",
      "dimension4": "K",
      "quantity1": 2,
      "quantity2": 10,
      "taxRate": 22,
      "priceSale": 320,
      "pricePurchase": 150,
      "priceInvoice": 135,
      "discount1": 10,
      "discount2": 20
    }
  ],
  "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

On this sample

The branch with code 2 (first in reserved) has 2 units reserved, as specified by quantity1.

The warehouse with code 1001 (second in reserved) has 10 units reserved, as specified by quantity2.

The reserved array and quantity fields (ranging from quantity1 to quantity10) allow precise management of reserved quantities per SKU for multiple branch locations. This is useful when an order needs to reserve goods for different branches, with each branch receiving a specific quantity of the item.

Reserved Field: The reserved array in the documentHeader specifies the locations (branches or warehouses) where the goods are reserved. Each entry in the array represents a specific location with two key properties:

type: Type of location (e.g., "SHOP" for a retail branch, "WRH" for a warehouse).

code: The unique code identifying the branch or warehouse.

Quantity Fields (quantity1 to quantity10): Each quantity field corresponds to a reserved location in the reserved array. The sequence of reserved entries determines which quantity applies to each location:

quantity1 corresponds to the first entry in reserved,

quantity2 corresponds to the second entry in reserved,

This pattern continues up to quantity10.

If there are more than two reserved locations, you can specify additional quantities using quantity3 to quantity10, ensuring each location in reserved has an associated quantity. This structure allows you to reserve different quantities for each branch location or warehouse, optimizing inventory allocation directly within the purchase order.

Success Callback Response

{
  "success": true,
  "id": "02931b8a-a6c8-4e47-b3f1-041ffb1e412t"
}

Error Callback 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.

ERP and transactionId

It is strongly recommended that the e-commerce site stores the unique receipt ID 02931b8a-a6c8-4e47-b3f1-041ffb1e432q and links it uniquely to the collected order.

Sequence Diagram

INFO

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

Purchase Order Registration