User accounts: data providers & consumers

On Sophatar, each user account has a unique email address and user_id.

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.

Each 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_id, 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_ids. Each 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 location_id.

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 user_id, location_id and 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 user_id & location_id of the data provider whose data is requested, and use its own authentication (api_key or access_token) in the header of the API requests. The SuperReceipt API will only return data if the accessed user_id & location_id is within the access list of the API consumer, who is identified based on the authentication credentials.