Technical Considerations

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

Written By Ops UrbanPiper (Collaborator)

Updated at October 7th, 2020

A. Data Format, services, methods:

  1. Web-services — All our APIs built on RESTful resources with the HTTP protocol.
  2. Content-type — The data pushed to third-party systems will be 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 — A throttle limit applies to each endpoint of Configuration and Ordering APIs.  A throttle limit of each API mentioned in the API doc under the block Constraints and Expectations.
  2. HTTP Response Status Codes —  The data pushed to third party systems via webhook endpoints is expected to return the HTTP status code along with the response. If the system receives any status code apart from 2xx (200, 201), our system makes an auto-retry attempt for next three times to push the data.
  3. API data request Rule — If APIs are defined to send the data as request body, then you need to send it as a request body and NOT as a query param.
  4. Request Protocol — All the API requests to UrbanPiper are must be made with the https scheme.
  5. Objects in one Request — The constraints for payload size for all APIs mentioned in the API documentation under the block Constraints and Expectations.
  6. Expected Retry Mechanism — You can set a maximum of 3 retry attempts for hitting our APIs in case the requests don’t go through. You can reach out to our support team after three retry attempts got failed.
  7. Our Retry Approach — If our system receives 4xx, 5xx, etc other than 2xx response status code, our system tries to post the data three times in the interval 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. Read more...
  9. Connection Timeout and Read Timeout — Its expected any third party system consuming the webhook data must send the response considering the below time constraint put to our system. 
    • Connection Timeout - 3 seconds.
    • Read Timeout - 5 seconds.

C. Approaches, Suggestions

  1. Parsing data — If your system doesn't support JSON, 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 menu IDs created by the POS system must be in a federated structure. The menu IDs must have maintained at the master level of the brand. All the outlets of the brand must have maintained with same menu codes.
  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 is allowed.
  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 syncing the stores, menu, stock request to our system, you need to make the API request in a bulk approach. Sending individual data per API request is not entertained.
  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 sent to POS by UrbanPiper. Any modifications or changes in the data which aggregators are not sending are strictly not supported by UrbanPiper. 
  10. Requests interval  — We suggest you keep a buffer time of 10seconds for a successive request you make to our system.

Was this article helpful?