Save Purchase

Create Purchase Order Document

This API allows users to create a purchase order 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.

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Preconditions

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

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

The client application prepares the JSON payload with the document details.

The client sends a POST request to the API endpoint with the required headers and JSON body.

The API processes the request asynchronously.

Upon successful creation, the API returns a response containing success: true and a unique id for the document.

The client application receives the response and can use the document ID for further processing or 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

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.

Example of Invalid Input Data

Example of Specific Error Response

Authentication Failure: If the credentials provided are invalid, the API will not process the request and will return an error indicating authentication failure.

Authentication Failure

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

Request

Query Params

Header Params

Body Params application/json

Example

{
  "documentHeader": {
    "id": "02931b8a-a6c8-4e47-b3f1-041ffb1e925l",
    "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": [
    {
      "itemCode": "ITEM_CODE",
      "barcode": "8000200017671",
      "itemSupplier": "032B622-2--19059",
      "quantity1": 2,
      "taxRate": 22,
      "priceSale": 320,
      "pricePurchase": 150,
      "priceInvoice": 135,
      "discount1": 10,
      "discount2": 20
    }
  ],
  "callback": "https://europe-west1-sinesy4wsplatform.cloudfunctions.net/fake-callback"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Create Purchase Order Document#

Actors#

Preconditions#

Main Success Scenario#

SKU Management in Document Handling#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Create Purchase Order Document

Actors

Preconditions

Main Success Scenario

SKU Management in Document Handling

Alternate Flows

Sequence Diagram

Code Examples in Node.js