Technical Considerations

Make sure you have read this article before starting the integration development at POS side.

Written By Ops UrbanPiper (Collaborator)

Updated at April 8th, 2020

A. Data Format, services, methods:

  1. Web-services — All our APIs built on RESTful resources with the HTTP protocol.
  2. Content-type — We communicate with the POS in JSON format.
  3. Webhook based integration — A webhook is a way for a web service to provide other services with near real-time information using HTTP POST method.
  4. HTTP Methods used in API — POST, PUT

B. APIs, Rules, and Protocols:

  1. Throttle limit — All the APIs will have its own throttle limit. The throttle limit of the APIs has mentioned in the API doc under Constraints and Expectations block.
  2. HTTP Response Status Codes — When we are posting the data to your webhook endpoint, we consider HTTP response status code from your end to check whether the request successfully went through or not. If we receive any status code apart from 200, we do retry attempt to push the data 3 times.
  3. API data request Rule — If APIs are defined to pass the data as request body then you need to pass it as a request body and not as a query param.
  4. Request Protocol — All requests should be made with the https scheme.
  5. Objects in one Request — The constraints for payload size for all APIs are mentioned in the API documentation under Constraints and Expectations block.
  6. Expected Retry Mechanism — You can set a maximum of 3 retry attempts for hitting our API in case the requests don’t go through. You can reach out to our support team after 3 retry attempts got failed.
  7. Our Retry Approach — If we get 4xx, 5xx, etc other than 200 response status code, we do try to post the data 3 times in the interval of 23 seconds/minutes(next 8 secs/minutes).
  8. Webhook Circuit Breaker  — When our system receives more than 15 errors response within a minute while pushing the data to third-party webhook endpoints, our system will disable all the webhooks configured for that business.

C. Approaches, Suggestions

  1. Parsing data — You can parse the data we send from JSON to your programming language.
  2. Headers — You can set the headers for your API endpoints for authentication.
  3. POS unique ref id for products — The POS ref ids should be created in a federated structure manner. That means, for a brand, each catalogue entry created should have unique codes and maintained the same codes across all the stores/outlets.
  4. POS unique code for stores — All the stores under a brand should have a unique identifier id.
  5. POS ref id — Max of 32 characters can be sent.
  6. Payload structure and data consistency — The payload structure will be the same for all the orders of different aggregators but depending upon the data available for an order, the attributes and objects might not have the consistency in the payload.
  7. Bulk Data Request approach — While doing the menu sync and adding the stores in our system, you need to send the request in a bulk approach. You cannot send one individual data per request and it should always send it in bulk.
  8. Events Type — Outbound request associated with every webhook has a header value — X-UPR-Event-Type — that can be used to identify the associated event type. You can check the event codes in the API documentation.
  9. Data restriction and changes — All the data related to order from aggregators will be passed to POS. Any modifications or changes in the data which aggregators are not sending are strictly not supported by UrbanPiper. 
  10. Requests interval  — We request you to keep a buffer time of 10seconds for every request you make to our system.

Was this article helpful?