Winston POS API
Introduction
Welcome to the Winston POS API. This API provides a robust interface for third-party integrations to interact with our platform, including ordering, reservations, and data synchronization.
Definitions
- Tenant: An organization/venue/location/establishment which makes use of our platform. It contains the Menu, Modules, Integrations and all associated Settings. A tenant may have (multiple) sub-tenants.
- User: An employee with access to (parts of) the platform for a specific tenant. Users are only active in one tenant at a time.
- Consumer: A guest/customer of one or more tenants. Consumers are not directly associated with tenants, (most of) their interactions are, however.
Applications
The Winston API allows you to access and configure (almost) anything inside Winston.
Winston consists of Point-of-Sale, backoffice, API and consumer apps, with each their own task:
- Consumer: The consumer-facing part of Winston. It allows consumers to place home-orders, self-orders, reservations & receive loyalty points. It also hosts a dedicated website page for every tenant.
- Point-of-Sale: The frontoffice Winston application. It's mostly used as a cash register, but the app also hosts the order screens and allows managing reservations.
- Backoffice: Allows tenants to configure the entire Winston system (incl. all of our modules and integrations).
- API: Responsible for handling calls from and to all integrations in Winston. As the name suggests, this hosts our API.
Getting started 🧑💻
To get started developing for the the Winston API you can sign up for a development environment in the test environment. The test environment is ideal for testing your integration since it hosts a separate instance of all Winston applications. This way you don't have to worry about messing around with live data from our/your users.
After registering you will receive an e-mail with a password link for our Backoffice. The dashboard of the Backoffice provides easy access to the Point-of-Sale application (web-based) and the Consumer app (web-based). The same user account for the Backoffice can also be used for the Point-of-Sale application.
To enable API requests, you need to activate the development integration. If you open the settings for the 'API development' integration you should see your personal API key. You can use this API key to authenticate every request. For more information see the authentication section.
Please keep in mind that the test environment runs the latest 'alpha channel' code. This means that it is possible that some parts, or maybe even the whole system, may not work as intended.
Happy hacking!
Overview
Request structure
Every API call in Winston is a POST request containing the request details in JSON form in the body. For example:
POST /api/v2/bills HTTP/1.1
Content-Type: application/json
{
"sort": { "createdAt": 1 },
"limit": 5
}
Authentication
Every API request is authenticated with an app name and API key. The app name is specific to your integration and identifies the integration (globally) as seen in the backoffice. The API key is directly linked to a specific tenant.
In the development environment you will receive the API key from the 'API development' integration. The corresponding app name for this integration is api_test.
In production we create a separate integration entry specific to you in our backoffice application. The corresponding app name will be communicated with you.
HTTP authentication works by sending the Authorization HTTP header as follows: Authorization: Token <app name>@<api key>.
For example, for the 'API development' integration it would look like Authorization: Token api_test@a6oheq92sBKq5q3jK (not a functioning API key).
For miscellaneous integrators authentication works a bit differently. You can read more about the differences here.
All requests should be done over HTTPS. Requests over HTTP will be redirected to the HTTPS version instead.
Error responses
When an error occurs, the API will respond with the appropriate HTTP error code. The body of the document will explain the error in more detail. For example:
HTTP/1.1 401 Unauthorized
Unauthorized: invalid bearer token value
Going live 🚀
Before anyone can use your integration in our live environment, you need to request the validation of your integration. This is done by sending an email to [email protected]. This email should contain a description of your integration, as much documentation about your integration as possible and instructions on how to test/validate the integration. Please also make sure that the integration runs on the test environment as intended.
Once your integration is validated and approved, we will add the integration to our system, which will be rolled into the next release of our API.
Authentication
- Token Auth
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | token |
Contact Winston POS Support: [email protected]