The purpose of this document is to assist web developers in creating a seamless integration into the Touchretail system and is based on our experience with numerous web integrations
1 – Product updates
There are 3 ways to get product updates. Use a combination of the 3 to achieve the best results.
- All products since the last query to the Touchretail API.
Should be used periodically, say every 5 minutes to update changes to the product details
- All products from a specified date.
Should be used overnight, specifying a date of 1 or 2 days prior, to ensure no product updates have been missed (eg system failure or internet issues)
- All products.
Should be used for initial data load and in cases of long term system failures to ensure all products are in line. This process can take some time to return the data dependant on the size of the Customers data, so should only be used occasionally when required
Your Integration should take into account that Attributes can be added and edited by the customer and would appear as additional or changed Categories, Variants or Tags, dependent on how the TRIMS user has configured them. It may be that these new attributes will need to be mapped to new fields on the website, so a mapping table is always a preferred method of handling this. It is advised to use the 'code' JSON field reference when mapping these as the 'code' remains the same over the lifetime of the attribute, whereas the name may change.
2 - Stock Updates
There are 3 ways to get Stock updates
- All stock since the last query to the Touchretail API.
Should be used periodically say every 30 seconds to ensure any sales on the epos system adjust the stock on the website
- All stock from a specified date.
Should be used overnight specifying a date of 1 or 2 days prior to ensure no stock updates have been missed
- All stock.
Should be used for the initial data load but can also be used every night if required (instead as the from date option). The process of returning all stock is fairly quick.
3 – Sales
To ensure sales amend the stock as quickly as possible on the epos this method should be called every time a Sale is completed on the web site. The web developer can do it one of 2 ways:
Send all orders as soon as they are placed and if the order is subsequently cancelled send a return for that order or items on the order.
The advantages of this are that the stock is deducted quickly from the inventory and therefore less likelihood of it being sold twice. The disadvantages are that if there are a lot of orders being placed which subsequently are cancelled, stock is being reserved and therefore not available for Sale.
Often a side effect of fraudulent orders, it is advised that the web developer puts procedures in place to handle this aforementioned scenario. One way to achieve this is to cap the maximum basket quantity of any single item to a realistic value, this way a single fraudulent order couldn’t reserve all stock.
Intervention (Not recommended)
Only send orders once they are verified and accepted as an order.
The advantages of this method is that stock is not reserved for Fraudulent orders, the disadvantage is that if the process of confirming an order requires user intervention, the stock is available to sell until the order is confirmed which could be an issue if there is a delay in processing the orders.
*Order numbers must be unique, duplicates will be ignored. If you are refunding an order you should generate a new unique order number.
4 – Sales processing by the Web developer on the WEB site
From experience of things which may go wrong, we strongly recommend that there is an Interim file on the web site which all orders get placed into and then a cron job which runs say every 30 seconds and sends all orders which have not be sent previously. The reason for doing this is 2 fold, the API responds with a success flag which, when set to false means the order has failed and therefore the cron job should re-send that order next time, it also returns a reason description which can be stored in the file and can be used for debug purposes if the order fails to complete after numerous retries.
The Touchretail API should be available 24/7 however in practice this cannot be relied on due to all sorts of circumstances, Internet failures, Touchretail Servers downtime for patching etc, so by adhering to the above processes the system should be resilient enough to cope with these outages.