How to implement the "OrderChecker" API

The Order Checker integration will allow all Business and Enterprise plan users to see an error message every time they add or edit items in their cart that are out of stock.

In practice, this will be done through a hook that will be sent to an external API with each change made to the order, which will carry out a validation and confirm whether the cart is still (or not) valid for creating the order.

The structure that will be sent to the remote API is described below:

Note: It is important to point out that the remote API will receive the current order information, that is, if the order has just been created, it will only contain the ID and Status of the order. With each edition, the remote API receives the new status of the order.

{
   "objectId":"ORDER_ID",
   "eventType":"ORDER_UPDATE",
   "retailerOrderId":"SEQUENCE_ORDER_ID",
   "isInternational":false,
   "canAcceptBoleto":true,
   "canAcceptCreditCard":true,
   "canAcceptDebitCard":true,
   "canAcceptPix":true,
   "coupon":"CUPOM",
   "salesChannel":"Instagram",
   "campaign":"Campaign",
   "team":{
      "objectId":"RTE2587",
      "name":"Team"
   },
   "giftCard":"GiftGift",
   "discount":10,
   "discountMode":"ABSOLUTE",
   "deliveryTime":"1 dia útil",
   "shippingMethod":"SEDEX",
   "freightCost":10,
   "freeShipping":false,
   "paymentAccountSelected":"ID_CONTA_SELECIONADA",
   "orderAccountSelected":"ID_CONTA_SELECIONADA",
   "customer":{
      "objectId":"ID_CUSTOMER",
      "name":"João",
      "lastName":"Medeiros",
      "gender":"Male",
      "businessAccount":false,
      "taxDocumentnumber":"00055544465",
      "email":"[email protected]",
      "phoneNumber":"999999999",
      "phoneAreaCode":"41",
      "phoneCountryCode":"55",
      "birthDate":"2023-10-09",
      "businessStateTaxId":"PASS",
      "businessTaxId":"TRED98E",
      "businessName":"MyBussines"
   },
   "shippingAddress":{
      "addressLine1":"STREET",
      "addressLine2":"COMPLEMENT",
      "number":"213",
      "suburb":"SUBURB",
      "zip":"CEP",
      "recipient":"RECIPIENT_NAME",
      "addressState":"STATE",
      "city":"CITY",
      "country":"COUNTRY"
   },
   "items":[
      {
         "objectId":"ID_ITEM",
         "quantity":5,
         "price":10,
         "externalId":"987941TRE",
         "sellerId":"SELLER888",
         "isGift":true,
         "shippingMethod":"PAC",
         "productReference":"654987321",
         "weight":5,
         "height":5,
         "length":5,
         "width":5,
         "variantId":"ID_VARIANTE"
      }
   ]
}

And here, the structure that should be returned by the remote API.

[
  {
    "action": "ERROR",
    "component": "ITEM",
    "componentId": "ID_ITEM",
    "message": "Item não disponível"
  }
]

Error codes and actions:
For each shipment the following http codes will be accepted and their behavior with their payloads will be described below.

http code	payload	behaviour
200	empty array	will pass the information without problems.
200	array with error actions	it will mark the errors, if it is finalization of the order, it will let the request pass.
403	array with error actions	will mark the errors and will prevent proceeding with the finalization of the order

Actions serve to discriminate which action we should take in order in response to remote processing.

field	value	description
action	ERROR	it means there was an error
component	ITEM	specifies that the error refers to an item within the order
componentId	FgkrtE50fGr5	specifies which of the items failed
message	Out of stock	explains what happened to the affected component

Step by step to integration.

Access the Omnichat platform.
In the Settings menu, select Integration >> Others >> Order Checker.
Enter the EndPoint API.
To add authentication tokens, enter the information in the Header followed by Value fields. Use the "+" button for as many as necessary.
If you want to allow the sale even with an error in the integration, enable the field "Allow sales even if there are errors in the API" .
If you want to allow a sale even if you don't have a product in stock, enable the "Allow sales even if there are errors in the items" field.
Click Save and you're done.

Examples of notifications

It is possible to send several notifications, such as changing the shipping value on the order, delivery methods on the items, discount on the order, adding gifts, among others.

Changing the shipping value in the order

[
  {
    "action": "INFO",
    "component": "FREIGHT",
    "message": "Valor do frete alterado",
    "freightCost": 10 // valor do frete
  }
]

Changing the order discount amount

[
  {
    "action": "INFO",
    "component": "ORDER",
    "message": "Valor do desconto alterado",
    "discount": 10, // valor do desconto
    "discountMode": "ABSOLUTE"
  }
]

Displaying delivery methods on items

[
  {
    "action": "INFO",
    "component": "ITEM",
    "componentId": "ID_DO_ITEM",
    "shippingMethod": "PAC" // método de entrega selecionado,
    "shippingOptions": [
     {
      "id": "PAC",
      "name": "PAC",
      "price": 5,
      "listPrice": 5,
      "tax": 0,
      "deliveryChannel": "delivery",
      "shippingEstimate": "3bd",
      "productLockedTime": null
     },
     {
      "id": "Expresso",
      "name": "Expresso",
      "price": 10,
      "listPrice": 10,
      "tax": 0,
      "deliveryChannel": "delivery",
      "shippingEstimate": "0bd",
      "productLockedTime": null
     }
    ]
  }
]

Adding gift on order

[
  {
    "action": "INFO",
    "component": "ORDER",
    "isGift": true,
    "item": {
      "name": "Kit Brinde Teste",
      "externalId": "123", // Id do item da plataforma de origem
      "sellerId": "", // Id do seller do item caso possua
      "sellerName": "", // Nome do seller caso possua,
      "externalImageURL": "", // URL de imagem do item
      "unitMultiplier": 1,
      "salePrice": 0,
      "price": 0
    },
    "shippingMethod": "PAC",
    "shippingOptions": [
     {
      "id": "PAC",
      "name": "PAC",
      "price": 5,
      "listPrice": 5,
      "tax": 0,
      "deliveryChannel": "delivery",
      "shippingEstimate": "3bd",
      "productLockedTime": null
     },
     {
      "id": "Expresso",
      "name": "Expresso",
      "price": 10,
      "listPrice": 10,
      "tax": 0,
      "deliveryChannel": "delivery",
      "shippingEstimate": "0bd",
      "productLockedTime": null
     }
    ]
  }
]

Displaying order errors

[
  {
    "action": "ERROR",
    "component": "ORDER",
    "message": "O pedido está inválido"
  }
]

Displaying info notification on order

[
  {
    "action": "INFO",
    "component": "ORDER",
    "message": "Este pedido tem um brinde"
  }
]