API-dokumentaatio
Environments
Solteq Commerce Cloud has three separate environments: production, developer and stage. This page contains information about our APIs and request examples. API definitions can be found from service specific swaggers. Note that the actual base URL to use for your requests is different than what is provided in the swaggers. The actual base URLs for each environment are provided below.
Production
Backoffice: www.solteqpos.com
Production API base URL: https://sq-prod.azure-api.net or https://api.solteqpos.com
Production Identity Server: https://login.smartretail.cloud/
Stage
Backoffice: https://integration.solteqpos.com
Stage API base URL: https://sq-stage.azure-api.net or https://api-stage.solteqpos.com
Stage/Integration Identity Server: https://login-integration.smartretail.cloud
Developer
Backoffice: https://dev.solteqpos.com
Test API base URL: https://sq-test.azure-api.net or https://api-dev.solteqpos.com
Test Identity Server: https://solteqidentity-test.azurewebsites.net/
Actual endpoints are created by the rule:
<API-base-url>/<service-name>/v1-ext/<rest-path>
Common
The APIs use the OAuth2 protocol for authentication: Autentikointi
In case of using an invalid bearer token, response code 401 Unauthorized will be returned.
Continuation Token
Some requests may return a continuation token in the response object. This means that there are more results to be returned, but due to technical limitations, all of them could not be returned in a single call to the service. The token comes from cosmos db. When the token is returned, the caller should repeat the invocation with the same parameters and the token to get the remaining results. The operation can be repeated until the token value is empty. Token should be encoded if value is provided in query string. For more on this, see: https://medium.com/@gary.strange/understanding-cosmosdb-continuation-tokens-hasmoreresults-and-connectionpolicy-requesttimeouts-3ed1fadfa81d
CODE
|
Timezone
Some endpoints require that the caller provides a timezone. The value is optional and can be any valid timezone (check supported timezones from https://en.wikipedia.org/wiki/List_of_tz_database_time_zones from field TZ database name). If not provided, Europe/Helsinki is used. This value enables the service to calculate the current local time in the caller’s timezone and adjust the returned data accordingly.
For example: Regular prices and discounts defined in the system are valid only for a given period. That period should be always applied to the local timezone, meaning: there is no conversion between timezones. To check whether the regular price or discount is valid for the caller in the moment of invocation, the service needs to know caller's timezone, calculate its current DateTime, and compare these with the validity period of each regular price and discount.
Webhooks
Webbooks are useful for handling real-time sales. They are the recommended way to sync sales and get feedback on different states for external orders.
Full swagger DEV: https://sq-webhooks-api-test.azurewebsites.net/swagger/index.html
Full swagger STAGE: https://sq-webhooks-api-stage.azurewebsites.net/swagger/index.html
Full swagger PROD: https://sq-webhooks-api-prod.azurewebsites.net/swagger/index.html
Catalog API
Catalog API is for handling products, ingredients, discounts and pricelists related to products.
Full swagger DEV: https://sq-catalog-api-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-catalog-api-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-catalog-api-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
additional path: /catalog
Products, ingredient and pricelists all share same Id - pool. When external system is pushing documents to Catalog with id, they need to make sure not to use same id’s eq. on products and pricelist. One way to avoid problems, is to use prefix on Pricelist id’s like “pricelist_<id>”.
Get products changed after [timestamp]
You can get Products or Ingredients by exact ID or query delta on changed products after a certain time. It is on integrator’s responsibility to keep track when they last queried those products.
CODE
|
Customership API
Full swagger DEV: https://sq-customership-api-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-customership-api-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-customership-api-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
additional path: /customership
There is possibility to create two types of customers:
Company
Private
On API for company customers create/update rules:
If ExternalID then
Search existing customership with externalId
If found then update
else create
else
if no taxCode do not allow creating customer return 400
Search existing customership with clientTaxCode
if found then update
else create
Private customer main fields:
"identifiers" - identifier type can be set on (ExternalID, SSO-hash , CustomerCard )
"customerGroup" - there is possibility to assign customer for particular customer group (used in Pricelists)
"person" - actual person for private customer (check on example body)
Person is created only once in Solteq Cloud POS database, so it's shared
For private customers, id is always the person's e-mail. Private customer without e-mail is not currently supported.
Orders API
Orders API is used for taking in sales from external systems such as Webshop. Orders can be already paid or to be paid on POS.
Full swagger DEV: https://sq-orders-api-3-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-orders-api-3-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-orders-api-3-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
additional path: /orders
Reporting API
All sales and statistics are fetched from this API.
Note on getting Orders, that save last successful fetched timestamp. Solteq Cloud POS does not have flags if order is transferred to external system. Also use our OrderId and events for checking that order is not duplicated. Order can be presented on API before it's fully completed.
Full swagger DEV: https://sq-reporting-api-3-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-reporting-api-3-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-reporting-api-3-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
additional path: /reporting
Get Orders Delta way
If you are not using Solteq’s Webhooks, syncing sales should be done using the getAllPaidAfter endpoint.
GET: /reporting/v1-ext/Orders/getAllPaidAfter/{fromEpoch}[?pageSize][&pageIndex]
Last section 1526898063 is unix timestamp expressed as int64 epoch value.
For ,ore details about converting to unix timestamp from epoch value, see https://www.epochconverter.com/
It is possible to get also single orders with either OrderId (unique ID) or ReceipId that is unique, printed to receipt, and more user-friendly.
Administration API
This API is important for getting stores and settings
Full swagger DEV: https://sq-administration-api-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-administration-api-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-administration-api-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Additional Path: /administration
Users API
Not yet on external use, but has potentially possibility to add POS users and get Personnel ledger working hours via API
Full swagger DEV: https://sq-users-api-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-users-api-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-users-api-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Additional Path: /users
Accounting API
This API is used for Accounting integrations.
Full swagger DEV: https://sq-accounting-api-2-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-accounting-api-2-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-accounting-api-2-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Additional Path: accounting
StockHandling API
This API is used for StockHandling integrations. Currently we support getting Stock Quantities, creating purchase orders (transaction order of type "in") and getting/upserting GKU entities.
Full swagger DEV: https://sq-stock-handling-api-2-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-stock-handling-api-2-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-stock-handling-api-2-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Additional Path: stock-handling
GiftCard API
This API is used for external POS’s, Web Shops and Applications for using Solteq Cloud POS Gift Card module. Additional APIs will be introduced later; currently only creating templates is possible.
Full swagger DEV: https://sq-giftcards-api-2-test.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger STAGE: https://sq-giftcards-api-2-stage.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Full swagger PROD: https://sq-giftcards-api-2-prod.azurewebsites.net/swagger/index.html?urls.primaryName=V1-EXT
Additional Path: gift-cards
Examples from basic giftcard template:
POST https://sq-test.azure-api.net/gift-cards/v1-ext/GiftcardTemplates
CODE
|
Example for LunchVoucher:
CODE
|
Example of Product Gift Card.
Examples from creating new Gift Cards using External API. Not that template Name is they key here, not id.
DeliveryType 2 is send via e-mail.
CODE
|
Response:
CODE
|