The Doshii Ordering API can be used by your App to retrieve a venue's sales history.
Introduction
The Doshii Partner API provides read-only services for Apps to consume order sales data from locations. Depending on requirements this can be achieved using Doshii's Bulk Data API services, or our data retrieval endpoints for Orders and Tables
Pre-requisites
Before implementing a Read-Only Data Retrieval Service ensure to familiarise with:
- Our Onboarding and Subscription policies
- Doshii Environments. Ensure to use Doshii's read-only endpoints.
This document assumes Subscription and Onboarding has been implemented as per requirements.
Getting started
- Obtain credentials from the Doshii Dashboard.
- Authenticate the App
- Subscribe to Doshii Locations.
Using real time order retrieval
Real time order retrieval is facilitated by the use of Doshii's orders endpoint.
Any order created in a location's POS is made available in Doshii, and can be retrieved by periodically polling the orders endpoint using specified parameters, depending on the requirements.
- Use the Accept-Encoding: gzip header always to ensure improved response times, and to allow for greater payloads to be retrieved in one go. By using gzip compression, the Doshii orders endpoint can retrieve up to 1000 records at a time, as opposed to 100.
- Doshii recommends polling at a minimum of once per 60 seconds, to minimise load on the API and your App. As ordering is submitted by the POS in near realtime after interaction by users, it would not be realistic to expect order updates for a location occurring every few seconds.
- Use the location operating hours (can be retrieved as part of the Onboarding and Subscription implementation) to know when to expect orders to occur.
Order retrieval parameters
- When polling, using the from and to parameters will retrieve the appropriate order sets, based on the order's creation time (UTC) in Doshii. Also make note of the offset parameter when the count exceeds the limit.
Example:
GET https://sandbox.doshii.co/partner/v3/orders?from=1564022760&to=1564022820{ "count": 1, "rows": [ { "items": [ { "name": "Cappuccino", "tags": [ "Coffee" ], "type": "single", "uuid": "12036aed-11f3-43f0-aebc-a3d4b62e6037", "posId": "001", "options": [ { "name": "Selected modifiers", "variants": [ { "name": "1 sugar", "posId": "0011", "price": "0" } ] } ], "quantity": "2", "surcounts": [ { "name": "Hand ground", "type": "absolute", "posId": "0012", "value": "50", "amount": "50" } ], "unitPrice": "500", "lastAction": { "audit": "", "logId": "6ee4d60d-fff1-44ef-87ed-aaf29a05edec", "action": [ "order_created" ], "performedAt": "2019-07-25T03:09:23.677Z" }, "description": "Cappuccino", "totalAfterSurcounts": "1050", "totalBeforeSurcounts": "1000" }, { "name": "Omelette", "tags": [ "Benedict modifiers" ], "type": "single", "uuid": "afd1bb3f-b531-41d7-b764-57284713f373", "posId": "002", "options": [], "quantity": "1", "surcounts": [], "unitPrice": "1700", "lastAction": { "audit": "", "logId": "6ee4d60d-fff1-44ef-87ed-aaf29a05edec", "action": [ "order_created" ], "performedAt": "2019-07-25T03:09:23.677Z" }, "description": "Omelette", "totalAfterSurcounts": "1700", "totalBeforeSurcounts": "1700" } ], "notes": null, "log": "https://sandbox.doshii.co/partner/v3/orders/6/logs", "posCreatedAt": "2019-07-25T03:09:23.677Z", "checkinId": "2", "availableEta": null, "uri": "https://sandbox.doshii.co/partner/v3/orders/6", "checkin": { "uri": "https://sandbox.doshii.co/partner/v3/checkins/2", "updatedAt": "2019-07-25T03:09:23.664Z", "status": "pending", "ref": null, "tableNames": [ "table881" ], "id": "2", "createdAt": "2019-07-25T03:09:23.664Z", "covers": null, "completedAt": null }, "updatedAt": "2019-07-25T03:09:23.678Z", "unapprovedItems": [], "locationId": "9YwAdZJD", "requiredAt": null, "status": "complete", "surcounts": [], "transactions": [ { "acceptLess": false, "partnerInitiated": false, "log": "https://sandbox.doshii.co/partner/v3/transactions/6/logs", "orderId": "6", "reference": null, "uri": "https://sandbox.doshii.co/partner/v3/transactions/6", "invoice": null, "updatedAt": "2019-07-25T03:09:23.713Z", "prepaid": false, "status": "complete", "surcounts": [], "amount": "2750", "version": "okw70qbMq8SjkRGyKx7WT6Ay6VNqQls3W46KD6KA", "tip": "0", "id": "6", "createdAt": "2019-07-25T03:09:23.713Z" } ], "memberId": null, "consumer": { "name": "John Doe", "email": "testEmail@test.com.au", "phone": "0404040404", "address": { "city": "Melbourne", "line1": "520 Bourke St", "line2": "Level 2", "state": "Victoria", "country": "AU", "postalCode": "3000" } }, "version": "MQgLbmROmqhZ8j2BoJkNUoLwoq4ykWcKqQg40Dn1", "type": "pickup", "manuallyProcessed": false, "id": "6", "createdAt": "2019-07-25T03:09:23.678Z", "phase": null, "posRef": "pos-1564024109080" } ], "offset": "0", "limit": "100" } - Orders can be retrieved additionally by their order status. Typically, an App may only be interested in orders that are accepted (to be cashed off by the POS) or complete.
Simulating in the Sandbox Environment
- To assist with development use the Sandbox Dashboard to create some orders against the pre-created Test Venue. Follow the How to Simulate Submitting an Order instructions.
- After creating these orders, use the Partner API Swagger to try out GET ~/orders with different parameters.
Bulk Data API
Doshii also provides an API for bulk data retrieval against many locations using a single request. The Bulk Data API will perform data extracts against the Partner's subscribed locations and using the parameters requested . The data extracts are streamed to an AWS S3 service location, and upon completion the API will notify the App via the registered Web hook. It is expected the Partner is able to access the AWS S3 service using their own credentials, therefore the Partner will need to be registered with AWS in order to use this API.
Reference for the Bulk Data API can be located within our API support material. It is recommended to contact Doshii Support if the Partner App intends to use this service.
After Implementation
- Contact Doshii support via support@doshii.io if you require any help.
- Certify your App with Doshii