POS Integration Handbook

Make sure you have gone through this handbook before starting the integration development to meet the expectations we have set..

Written By Ops UrbanPiper (Collaborator)

Updated at February 7th, 2020

Overview

This doc will help you understand the HUB integration you are going to have with UrbanPiper. At present, the UrbanPiper Hub platform provides seamless integration to manage orders across all the major aggregators — Swiggy, Zomato, Dunzo, and Scootsy. 

Once you have integrated with UrbanPiper, you can have the integration with all the major aggregators in the market.

Integrating with Hub will offer you many benefits—some of the important ones being:

  • Integrate with only one set of API endpoints, and your system will be able to communicate with all current and future major food aggregators.

  • Huge savings in time, effort and money, due to the reduced overhead of writing multiple integrations and QA verifications.

  • You’ll get fast-track access to new features released by aggregators.

  • UrbanPiper will assist you in resolving any discrepancies/concerns that arise at your end w.r.t the aggregators.

The scope of the integration can be divided into the following stages:

  • Management of stores (restaurants) on aggregators

  • Managing the catalogue of categories, items, etc – for each store.

  • Controlling the Catalogue(menu) and Store availability

  • Handling inbound orders from aggregators

  • Managing order status

  • Capturing webhook callback response for the store, catalogue configuration along with Item and store availability.


Webhook Based Ordering Integration

In webhook based ordering integration, UrbanPiper will relay the ordering data information coming from aggregators to POS systems service on a real-time basis. All POS system has to do is to expose the webhook endpoints/URLs to capture the data which we going to make a POST request. The data which we will send will be in JSON format.

UrbanPiper will only be pushing the data to the POS system's central repository(server). We will not be pushing the data to store-wise. This is what we call as HUB & SPOKE Model. Based on the store-code present in the JSON data, the POS system has to push the order data to remote stores.

For example, 

Brand - Pizza Hut

Store: 1 - Indiranagar, Bengaluru(POS Store code - INRPH)

Store: 2 - Whitefield, Bengaluru(POS Store code - WFDPH)

Store: 3 - Electronic City, Bengaluru(POS Store code - ETCPH)

POS system will be exposing one webhook endpoint for each event for the above brand and UrbanPiper will push the order data of all the above 3 stores to the common webhook endpoint. Based on the store code present in the JSON body, the POS system will identify the store and push those orders to the respective stores.

POS systems have to expose the different sets of webhook endpoints to consume different events. The different events as follows,

  1. Order Relay - Pushing the aggregator order to POS

  2. Order Status Change - Pushing the updated status of the order to POS that received from aggregators.

  3. Rider Status Change - Pushing the delivery rider information to POS.

Apart from the above-given events, there are 4 other callback events which we will be pushing the data to you when you make a request for Configuration APIs(This will be explained more in a later section).

In case, POS systems webhook endpoint is down while we pushing the orders, UrbanPiper will try to push the orders max of 3 times to make sure the orders are reached to the POS system. If we get to know the POS systems endpoints are still DOWN, we stop do the retry of orders. We expect the POS systems should maintain 98-99% uptime at least.

If we find the POS systems services throwing more than 15 errors(returning 4xx or 5xx error) within a minute, then the UrbanPiper system will automatically disable all the webhook endpoints configured for the business. This we call it as - Webhook Circuit Breaker Incident. After 15 mins, our system will re-enable the webhook endpoints. The orders which failed to push in that 15 mins will be re-pushed at once to your system once the webhook URLs are re-enabled. If this incident occurs, UrbanPiper will shoot the email to POS vendors informing the same.


Configuration APIs

We have a set of Configuration APIs to get the data pushed from POS to UrbanPiper. The data like Store, Menu - categories, items, variants, taxes, charges. Apart from this, we have APIs to enable/disable the store and enable/disable the items on aggregators platforms.

For each one of the above APIs, when the request gets processed in our system asynchronously, we do send the webhook callback response to the POS system informing them what all got updated, created. In order to capture these, you need to expose the webhook endpoints with us for each event.

We expect POS systems to maintain the Federated structure of the menu in their system. That is, an item should have the same POS item code across all the outlets.

Below are the Configuration APIs,

  • Adding/Updating Stores API - for creating/updating the store information.
  • Managing Catalogue API - creating/updating the menu data.
  • Items Actions API - enable/disabling the items and options.
  • Store Actions API - enable/disable the stores.


Updating Order Status to Aggregators via API

Once the order gets pushed to the POS system, we expect the POS system to act on that order by Accepting/Rejecting it. This information will be communicated to UrbanPiper by making the API call. Once we get the request, we will push it to aggregators.


Authorization

UrbanPiper will issue the API-keys brand-wise only. Different brands will have different API-keys. This API-keys should be used as a header while making the API calls to the UrbanPiper system.


Other Technical Aspects

  • Once the UrbanPiper Integration is enabled for a brand, the aggregators will stop pushing the orders to their dashboard. The merchant should use the POS system to monitor the orders.

  • UrbanPiper will also give a backup tool - Satellite to manage the orders in case the POS system is DOWN temporarily. Once the POS services are backup, then store operators can start using th POS system.

  • UrbanPiper Satellite can be opened on the browser or through APK available on Google Playstore. We will share the credentials to access the tool.

  • UrbanPiper will provide the API documentation, test environment, order simulator tool, postman collection, and other necessary details during the integration development cycle to help the POS vendors to complete the integration seamlessly.

  • POS vendors can download the Reports from our system for the merchants. We will share the Quint dashboard for the same.

  • Once the integration development is done, the Urbanpiper integration team will give a sign-off and later only the merchant onboarding and go-live will happen. All this has to be updated from the Gamma dashboard we share it with you.

  • During the merchant onboarding, ACM will be assigned to you who will share the production API-keys for the brand we are onboarding. Once you get the keys from us, you can go ahead and start pushing the store, menu data to our system.

  • Apart from this, from the POS vendor, we need only the aggregators URLs of the outlet of the brand for taking the outlet live.

  • We can only take the integration for an outlet that is already live on aggregators.

  • Differential pricing for an item is not supported by different platforms. The item price should be the same for all the aggregators


UrbanPiper Satellite Widget SDK

Apart from the webhook based approach, UrbanPiper also provides the feature - Satellite Widget SDK to POS vendors to embed it in their POS system to cut off the effort on UI development from POS systems. This approach works seamlessly and reduces the development time of POS vendors building the UI for the integration. Satellite SDK involves the below set of features,

  • Order Relay(Tracking)

  • Order Status Update

  • Rider Information

  • Enable/disable of items

  • Enable/disable of stores

  • Bill data dump for the bill print

  • Customizable UI(colors and fonts)

This Satellite SDK works for POS who is on a web-based approach. You can use this approach seamlessly to cover almost all the API for the integration mentioned in the RestAPI document except Adding/Updating stores and Managing Catalogue API. You can use still use the Webhooks approach if you want the data of the orders in your backend system. The Satellite SDK approach will not push the data to your backend.

UrbanPiper Integration team will help you assist in any sort of queries related to integration during the development phase and post-go-live as well. If you feel any information is missing or have queries, feel free to share it with us over email - integrations.team@urbanpiper.com

Looking forward to integrating with your system. 






Was this article helpful?