Explaining Live APIs and Async APIs

S&T offers two ways to communicate via API from your system: through Live APIs and Async APIs. Each API type has distinct characteristics that determine its behavior and suitability depending on the context. In this article, we will explore these differences using the creation of a Receive order in Open status as an example. This will allow us to better understand when and how to use each type of API based on its properties and your specific needs.

This article covers the following topics:

• API's Async
• API's Live

Other related articles:

• Explanation of transactions in Stock & Trace

API's Async

They are designed to handle processes that can be lengthy or that do not need an immediate response. Communication with this type of API generally involves sending a message that will be processed by S&T without requiring instant confirmation of success or failure to the external system. Below is an example of how requests and responses are structured.

Request Example

Endpoint: /api/v1/external_integrations/transaction

Method: POST

{
    "type": "ReceiveOrderCreation",
    "reference": "sunt et fugiat nostrud",
    "externalPayload": "Receive order external payload",
    "externalPayloadMimeType": "text/plain",
    "company": "SUPPLIER_SHORTNAME",
    "receiveOrders":
    [
       { 
         "warehouse": "WAREHOUSE_CODE",
         "account": "SUPPLIER_SHORTNAME",
         "lineItems": [
         {
            "partNumber": "PARTNUMBER_NAMEs",
            "quantity": 10
         } ]
       }
    ]
}

Response Example

{
   "transaction": {
      "id": 1883
   }
}

When S&T receives a new message, it will respond with the transaction ID generated for the request to create a new Receive order, and this transaction will be added to the queue of transactions pending processing.

If the transaction is not processed successfully, it will not be communicated to the external system. However, it will appear in the external integrations administration panel, where the warehouse team can review the details, make the necessary corrections, and retry the generation from the same panel.

API's Live

A Api Live, in contrast, is designed for operations that require an immediate, real-time response. These APIs are used to send requests that must be processed instantly by S&T, and the response is returned in real time. The following example shows how requests and responses are structured for a Live endpoint:

Request Example

Endpoint: /api/v2/receiveorders/create

Method: POST

{
    "receiveOrders":
    [
       { 
         "warehouse": "WAREHOUSE_CODE",
         "account": "SUPPLIER_SHORTNAME",
         "lineItems": [
         {
            "partNumber": "PARTNUMBER_NAMEs",
            "quantity": 10
         } ]
       }
    ]
}

Response Example

{
   "receiveOrders": [
    {
       "id": 1710
     }
  ]
}

When S&T processes the information successfully, it will respond by providing the ID of the generated Receive order.

If the transaction is not processed successfully, all detected errors will be returned to the external system, allowing the necessary corrections to be made. Once corrected, the external system can try to communicate the order again.