Skip to main content
Skip table of contents

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

Stage

Developer

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 
{
    "documents":  [...],
    "continuationToken":  null
}

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.

Catalog API

Catalog API is for handling products, ingredients, discounts and pricelists related to products. 

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 
{
	"id": "1141",
	"type": "StockProduct",
	"version": "1",
	"name": "Battery 0,33 l",
	"description": "Battery Energy Drink on vitaminoitu energiajuoma, jonka teho perustuu kahvi- ja guarana-uutteisiin sekä tauriiniin.",
	"price": 3.2,
	"taxpercent": 14,
	"categories": [
 		{
 			"categoryId": "126",
 			"categoryName": "Juomat",
 			"type": "group"
 		}
 	],
	"identifiers": [
		{
			"type": "SKU",
			"identifier": "6415600502054"
		}
	],
 	"imagePath": ""
}

Customership API

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.

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. 

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

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 

Additional Path: /users

Accounting API

This API is used for Accounting integrations. 

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.

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.

Additional Path: gift-cards

Examples from basic giftcard template:

POST https://sq-test.azure-api.net/gift-cards/v1-ext/GiftcardTemplates

CODE 
{
    "Name": "Lahjakortti",
    "Type": "Value",
    "Prefix": "LAHJK",
    "UseTime": "1",
    "UseType": "Balance",
    "ValueMax": "10000",
    "ValueMin": "20",
    "VatLimit": "",
    "SoldOnPOS": "true",
    "NumSeqStop": "15000",
    "AllowRefund": "false",
    "NumSeqStart": "10000",
    "ReceiptText": "Lahjakorttia voi käyttää maksuvälineenä kaikissa palvelupisteissä. Lahjakortti on voimassa kaksi vuotta sen ostohetkestä lukien.",
    "SellProduct": {
        "Id": "52910941-434e-44e0-af88-dc0291914ab4",
        "Name": "Lahjakortti"
    },
    "VATSpecific": "false",
    "ValidMonths": "24",
    "NumSeqFormat": "PREXXXXX",
    "ProductLimit": [],
    "ValueDefault": "50",
    "CategoryLimit": [],
    "CustomerSpecific": "false"
}

Example for LunchVoucher:

CODE 
{
    "Name": "Ateriaseteli 3,5€",
    "Type": "Value",
    "Prefix": "350ATER",
    "UseTime": "1",
    "UseType": "Onetime",
    "ValueMax": 3.5,
    "ValueMin": 3.5,
    "VatLimit": "14",
    "ProductId": "",
    "SoldOnPOS": "false",
    "NumSeqStop": "15000",
    "AllowRefund": "false",
    "NumSeqStart": "10001",
    "ReceiptText": "Ateriasetelillä voit ostaa ruoka- ja juomatuotteita. Ateriasetelit käyvät maksuvälineenä kaikissa pisteissämme.",
    "VATSpecific": "false",
    "ValidMonths": "12",
    "NumSeqFormat": "PREXXXXX",
    "ProductLimit": [],
    "ValueDefault": 3.5,
    "CategoryLimit": [
        {
            "Type": "Pääryhmä",
            "CategoryId": "1",
            "CategoryName": "Ruoka- ja elintarvikkeet"
        },
        {
            "Type": "Pääryhmä",
            "CategoryId": "8",
            "CategoryName": "Jäätelöt"
        },
        {
            "Type": "Pääryhmä",
            "CategoryId": "7",
            "CategoryName": "Snacksit"
        }
    ],
    "CustomerSpecific": "false"
}

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 
curl --location --request POST 'https://api-dev.solteqpos.com/gift-cards/v1-ext/Giftcard' \
--header 'Content-Type: application/json' \
--data-raw '{
 "giftcardProductTemplate": "Lahjakortti-testi",
    "customer": "ei mitaan",
    "quantity": 1,
    "amount": 200,
    "workstation": "API",
    "orderId": null,
    "receiptId": null,
    "username": "API",
    "deliveryType": 2,
    "deliveryAddress": "aki.korpua@solteq.com"
 }'

Response:

CODE 
{
    "status": "Ok",
    "message": "",
    "createdCards": [
        {
            "giftcardId": "LAHJKTEST10003",
            "leftAmount": 200.0,
            "leftQuantity": 1,
            "status": "Active",
            "validFrom": "0001-01-01T00:00:00",
            "validTo": "2022-11-25T09:24:57.2460627Z",
            "receiptText": "Lahjakorttia voi käyttää maksuvälineenä kaikissa palvelupisteissä. Lahjakortti on voimassa kaksi vuotta sen ostohetkestä lukien.",
            "deliveryId": 790
        }
    ]
}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close