User accounts: data providers & consumers
On Sophatar, each user account has a unique email address and
For SuperReceipt, user accounts can be 'providers' and/or 'consumers' of API data. Receipt printers are placed under a provider account to generate data.
User accounts can be given access to their own data (if they're a provider) and/or data from one or more other accounts which are data providers.
user_id identifies a unique Sophatar user account, which can have access to one more APIs (eg SuperReceipt is one of our APIs) and/or different parts of the web app (eg receipt viewer, wallet passes, signage etc). Some user accounts only have access to the API, others only to the web app, other have access to both.
To access the API, each user account has a separate
api_key (that remains fixed and unique to the user account) and/or OAuth credentials (with fixed
client_secret and dynamically changing
access_token obtained via an OAuth2 flow).
To access the web app, each
user_id uses a password which can be changed after login, or reset by sending a password reset email to the registered email address of the user account.
Assigning printers to locations, and transferring them
Each user account with access to SuperReceipt has one or more assigned
location_id identifies a 'retail rooftop' location. Accounts which are providers of sales receipt data will have one more printers (
device_ids) assigned to each
Cloud-connected Star printers are also assigned to a retailer on the Star Cloud website itself via a
retailer_id assigned by Star.
Given that Sophatar has its own assignments of printers to
location_ids, you can have multiple printers assigned to the same
retailer_id on Star Cloud but to different
location_ids on Sophatar, or vice versa. This allows flexibility for an ISV to purchase printers and place them under his own Star account, and later on transfer them to different retail sites with data separated on the API by retailer. Transferring printers between different
location_ids is done by Sophatar and does not require any change on Star Cloud.
However, due to access rules of Sophatar to the Star API for receipt image access, for larger quantities of printers it is advantageous to place printers assigned to the same Sophatar user account also under a single
retailer_id on Star Cloud. This allows an ISV also to transfer printers out of their Star Cloud account and into the retailer's own account on Star Cloud.
When a receipt is processed, its parsed data is stored in the receipt database under the
device_id valid at the time the receipt is processed. An API consumer can query for the receipt using these parameters. Thus when a printer is transferred to a new location/account, only newer receipts will show under the new location/account, older receipts will remain accessible under the old location/account.
Querying sales receipt data from the SuperReceipt API
An API consumer user account is given access to data from one or more API provider accounts during account setup by Sophatar. API providers may be setup to have access to their own data, thus a single user account can be both a provider and consumer, but this does not necessarily have to be the case (an account can only be a provider).
- Furthermore there can be overlap between the API provider data that can be accessed by different API consumer accounts, for instance:
- API consumer #1 has access to data from API providers #1 & #2
- API consumer #2 has access to data from API providers #1 & #3
To pull data from a provider, the API consumer shall use the
location_id of the data provider whose data is requested, and use its own authentication (
access_token) in the header of the API requests. The SuperReceipt API will only return data if the accessed
location_id is within the access list of the API consumer, who is identified based on the authentication credentials.