A. Data Format, services, methods:
- Web-services — All our APIs built on RESTful resources with the HTTP protocol.
- Content-type — We communicate with the POS in JSON format.
- 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.
- HTTP Methods used in API — POST, PUT, GET
B. APIs, Rules, and Protocols:
- Throttle limit — All the APIs will have its own throttle limit. The throttle limit of the APIs has mentioned in the API doc.
- 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 for 3 times.
- 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.
- Request Protocol — All requests should be made with the https scheme.
- Objects in one Request — The constraints for payload size for all APIs are mentioned in the API documentation.
- Expected Retry Mechanism — You can set a maximum of 3 retry attempts for hitting our API in case the requests doesn’t go through. You can reach out to our support team after 3 retry attempts got failed.
- 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).
C. Approaches, Suggestions
- Parsing data — You can parse the data we send from JSON to your programming language.
- Headers — You can set the headers for your API endpoints for authentication.
- POS unique ref id for products — The POS ref ids should be created in a federal structure. That means, for a brand, all the product codes should be unique and the same product codes are maintained across all the stores/outlets.
- POS unique code for stores — All the stores under a brand should have a unique identifier id.
- POS ref id — Max of 32 characters can be sent.
- 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.
- Bulk Data Request approach — Every data request has to be sent to our system in a bulk approach. You cannot send one individual data per request and it should always send it in bulk.
- 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.
- 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.
- Requests interval — We request you to keep a buffer time of 10seconds for every request you make to our system.