Code of Conduct & Best Practice, Extend Commerce API

If you are integrating with Extend Commerce through Extend Commerce API we expect you to behave, use and consume the API according to this document.

Extend Commerce API are designed for external webshops, POS systems, warehouse management systems, procurement systems and other ERP systems to post or get data to and from Extend Commerce.

Some parts of this document are technical descriptions, but the first part, the general code of conduct. contains some business critical parts that are very important that you as business owner / responsible reads and understand.

• Don't rely on Extend Commerce's availability for your own processes / logic. This is an important approach we want you to have. 

  The Extend Commerce platform has a lot of business critical data, but we ask you to build your processes so that your core features can be run without access to Extend Commerce. Fetch the critical data, but store the data and use it locally in your own processes. 

• Webhooks. We send out webhooks on a lot of events. We want you to use them as a trigger for you to fetch data. This is a much better way then you polling us frequency to see what's happened. 

• Get list. In case you can't use a webhook, we want you to use get list methods, with use of change date. use the result of that to fetch record by record. 

• Pagination, in some methods the result can contain a large number of records. we use pagination, so it´s a good idea that you build your process with capability to use pagination. 

• Error messages, we assume that you will handle and act on our error messages. 3 types of error messages can occur and you need to act differently on the 3 different types. (more below)

• Changes, you need to be able to handle added data in the models. Extend Commerce guarantees that we will not remove anything from our data models, but we can add data. We will add new data at the end of the segments. If we change the structure or removing data we will publish a new version of the method.

• New versions of methods. 

  If we add a new version of the method we will advice you about that. We will have the old version and the new version working parallels during a period, (normally 6 months) and we expect you to upgrade to latest version during that period. 

• Warehouses. In Extend Commerce, it's common that there are more than one warehouse, please keep in mind that so that you on both POST and GET request use/handle warehouse id when needed. otherwise it´s easy to get balances and assortments etc. mixed up. 

• Do not share credentials between different systems. If you have several systems that want to use data from Extend Commerce, create several access credentials, one per system / part that should access Extend Commerce API.

• You are responsible that each API user that access data from Extend Commerce has the right to use / read the data we deliver. You must understand the detailed level of each endpoint and take your own decision if you can let an external system access the data. This includes both the detail level in each record and also which records.

• Extend Commerce has the right to remove access to Extend Commerce API for any user that violates any terms in Extend Commerce's general terms that all customers to Extend Commerce has signed. Extend Commerce also has right to remove access for a API user that violates, and don't change the behavior after being notified by Extend Commerce, the described behavior and code of conduct in this document.

• You are not allowed to perform, send request, save data into Extend Commerce or any other activity to Extend Commerce API that can't be motivated for you to perform your normal business. This includes, but not limited to, activities that interferes with, disrupts, harms, damages, or trying to access,  Extend Commerce API, Databases, Networks.

• Some special characters are not allowed as keys for an entity, ie ProductNumber is the key for products. These characters are not allowed in keys for security reasons.

  < > % : \ ? +

Extend Commerce use throttling to secure system resources to all vital processes within Extend Commerce platform. We classify the methods in 3 different rate limits groups, and we use different rate limits for the different groups.

• Standard

  The standard rate limit are set to 300 requests per minute (5 requests / second). This is applied on all methods if it´s not expressed otherwise.

• High

  Methods classified as high performance methods has a rate limit of 900 requests per minute (15 / second). 

• Low

  Methods classified as Low performance methods has a rate limit of 60 requests per minute (1 per second)

    

Rate limits can be adjusted by decision from Extend Commerce. It's possible to sign an agreement with Extend Commerce to get other rate limits.

When the rate limit has been reached, we will respond with Status code 429, too many request. In the response header there are three extra fields for rate limit information:

"x-ratelimit-limit": "300", (300 would be Standard limit)
"x-ratelimit-remaining": "299", (299 request remaining)
"x-ratelimit-reset": "1581499121" (unixtime when 300 new requests will be available)

Our webhooks will call on the endpoint that you have added in the Extend Commerce platform. You can use a Secret that we produce for each endpoint to verify that the call comes from Extend Commerce. We strongly advice that you use webhooks as a trigger for you to fetch data from Extend Commerce platform. 

The Events for webhooks are:

Currently these events triggers a post:

More info about webhooks and how to set up, please read here Webhooks - Manual & Kunskapscenter - Confluence (atlassian.net)

Most of our methods comes with this structure:

In the get list there are a lot of parameters to use to find records. The purpose is that you shall use get list to find records, and then use Get single record to get all details about the record. Example, if you shall get all order from one customer, you use the get list, with parameter customer number, then you get a list of orders, use those ID to fetch each orders details. 

An example of use of this that´s NOT acceptable is if you have 500 orders in your application that you don´t know if they have been shipped or not. you then can´t fetching all 500 orders in details on a tight schedule just to see if the status has changed. 

The get list is design so that you can add changedate, status etc. as parameter and get a list of the records that you should fetch one by one.

Sync product masterdata

When your system shall use / sync product masterdata from Extend Commerce. 

Use webhook.

Best practice for sync product master data from Extend Commerce to your applications is for you to listen to our webhook. If you act on a webhook event then your application will have as near real time updated product masterdata. We will fire webhook on these events:

• Product created
• Product changed

In the webhook you'll get the product number and you can use that to call on GET product details to fetch all master data on the product

Example URL for detailed product master data

https://INSTALLATIONURL/RESTAPI/v1_0/CLIENT/Products?Id=productnumber

GET list

If you don´t use webhook, use the product get list method. When filtering on date you must use a fully qualified utc format, eg 2019-11-20T22:00:00.00+01:00. That date must be url encoded.

Here is an example of a request with a parameter where we want to get a list of all products with change date after 17th of june. 

https://INSTALLATIONURL/RESTAPI/v1_0/CLIENT/Products?modifiedDateFrom=2019-06-17T00%3A00%3A00.00%2B01%3A00

Sync inventory balances.

Use webhook.

Best practice for having your application in sync, in realtime, about balances (physical and available) we strongly recommend you to consume the webhook. we have 2 different events:

• Product balance changed
• Product available balance changed

These events will fire the webhook. Within this webhook we will give you information about the product, the warehouse and the new balance. (see example below) This information is normally enough for you to update your application with new balance. We know that the balances are extremely important that it´s real time balance, and if you consume the data in this webhook, you don´t need to call Extend Commerce to check about any balances.

But there is one issue with using the balance within the webhook that you need to consider. If your service is down or not responding, Extend Commerce will store that webhook and try again after a period of time (we try in total 10 times, after that we don´t try again). In a situation where we have not been able to post to your endpoint and we store that message for 5 min before we try again, another webhook might have been send and received by you. In such case the hooks will not be in a correct order, and the balance within the hooks are not correct. So if you want to be 100% secure to avoid this potential error, you should use the hook as a trigger to call us to fetch live balances. 

Example of o webhook with balances

"Id": "67b20e3dd433470786e5ecced223478f",

"Attempt": 1,

"Properties": {

"NotificationId": "7bfd9089-b5d3-48b0-bc04-80e2d2b79d80"

},

"Notifications": [

{

"Action": "BalanceChanged",

"Details": {

"ProductNumber": "1138-00",

"Warehouse": "WarehouseShortName",

"Balance": 201

}}]

Get List

If you can´t use the hook, then you should use ProductAvailability method. this method will provide you with  to get a list of products with changed balances

if you can´t consume the webhook, then you should use the ProductAvailability method to get balances. in this method there is a changedate we expect you to use that to only get balances where the balance has changed since you last asked. here is an example of a call to get products with changed balances since. When filtering on date you must use a fully qualified utc format, eg 2019-11-20T22:00:00.00+01:00. That date must be url encoded.

https://INSTALLATION URL/RESTAPI/v1_0/CLIENT/ProductAvailability?modifiedDateFrom=2019-05-13T00%3A00%3A00.00%2B01%3A00

"productAvailabilityList": [
    {
      "warehouse": "WAREHOUSEID",

      "productNumber": "123456798",
      "physicalBalance": 56,
      "availableBalanceNow": 34,
      "nextReceivingDate": 2019-06-22T11:05:41.05,
      "avaiableOnNextReceiving": 250,
      "changeDate": "2019-05-13T12:44:22.64"
    },

If you work with a lot of items, this list is normally quite long, contains a lot of records. here it´s important that you can handle pagination. The response is paginated and in the bottom you´ll see this information. (this is an example of where the get list returned 344 records.

  "paginationInfo": {
    "currentPage": 1,
    "totalPages": 4,
    "pageSize": 100,
    "totalResources": 344,
    "message": "Returning resources 1 to 100"

{
  

Sync Order status.

Use webhook

Best practice for syncing status on a customer order is to listen to our webhooks. There are these events:

• Order created
• Order picked
• Order reserved
• Order cancelled
• Order delivery data changed

That will fire a webhook telling you that an update has been done on the order. Use the orderid (ordernumber) in the webhook and use the CustomerOrders method to get all details about the order and orderrows.  Here is an example of API call to get details about a order.

https://INSTALLATION URL/RESTAPI/v1_0/CLIENT/CustomerOrders/?id=ORDER-ID

Get List

And as for many other methods, if you can´t use the webhook as trigger, use the get list with parameter of change date. this will give you a list of orders that has changed. 

Sync prices

ProductPrices method

Best practice for getting prices from Extend Commerce is to call on method ProductPrices. This method requires a customer number as parameter. You will get best available prices for that customer, the list could be a combination of different pricelists, discounts, campaign priceslists etc. You will get only one price per product and quantity. (the best price). If you get several records (prices) for one product it´s either because it´s a bracket pricing, or unit pricing on the product.  

here is a example of a typical respons form ProductPrice method

    {
      "productNumber": "X1IA0900",
      "salesUnit": "pcs",
      "fromQuantity": 1,
      "price": 423.0000,
      "listPrice": 544.0000,
      "vatPercent": 25.000,
      "currency": "DKK"
    },

{
      "productNumber": "X1IA0900",
      "salesUnit": "pcs",
      "fromQuantity": 6,
      "price": 399.0000,
      "listPrice": 544.0000,
      "vatPercent": 25.000,
      "currency": "DKK"
    },

{
      "productNumber": "X1IA0900",
      "salesUnit": "BOX",
      "fromQuantity": 1,
      "price": 1599.0000,
      "listPrice": 2150.0000,
      "vatPercent": 25.000,
      "currency": "DKK"
    },

These three examples gives you an understanding of how you need to understand quantity and units in the price model. In the first example the price is 423 for one piece. In the second example the price is 399 per piece IF the quantity is 6 pieces or more. In the last example the price is 1599 for one box. 

We expect you NOT to call this to verify prices within your own order/check out process. If you need to validate an order in a checkout process, you should use a price validation method.