Introduction

Welcome to the developer pages for Sitoo REST API.

Sitoo REST API provides programmatic access to the Sitoo Retail Platform. It makes it easy to integrate cloud services or other external systems to exchange data such as Products, Prices, Campaigns, Orders (transactions), Warehouse Stock, Financial Reporting and much more.

Rest API

Sitoo REST API makes it easy for developers to create, read, update and delete resources in Sitoo. The REST standard also makes it easy and intuitive to use the API. If you aren't familiar with REST, please check out the many tutorials available on the Internet. The REST API uses standard HTTP methods for different operations you can make on a resource:

GET to read
POST to add
PUT to update
DELETE to delete

All major programming languages have libraries for sending HTTP requests and handle the responses. Sending and receiving data is done using JSON. You can use cURL for testing.

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -u "{API ID}:{password}" \
  -H "Accept: application/json" \
  -d '{ "value": 25, "productgrouptype": 20, "productgroupname": "Shoes", "comment": "All shoes" }' \
  -s "https://api.mysitoo.com/v2/accounts/{accountid}/sites/{siteid}/productgroups.json"

API URLs

The Sitoo API is accessible via different URLs depending on the location of your Sitoo account. The base URL used for your account is available when generating a password for an API user in Settings / Sitoo REST API. To access the API you combine the base URL and the endpoint URL. Example for accessing the products endpoint:

https://api.mysitoo.com/v2/accounts/{accountid}/sites/{siteid}/products.json

The {siteid} parameter

The siteid(uniqueidentifier) has been deprecated in favor of eshopid(integer). For all requests to Sitoo API endpoint URLs, the {siteid} parameter should contain the eshopid value.

Warning!

Future endpoints added to the API will only implement the use of eshopid for the {siteid} parameter.

JSON-extension for endpoints

Please note! All endpoints are reached using the .json-extension as in the example above.

Authentication

Authentication is done with the HTTP basic authentication mechanism over a secure connection. The API ID and password can be found in the Backoffice under settings/Sitoo REST API (requires Administrator privileges and that the API extension has been added to the system).

Using the API ID and password, add an extra header to the request for authentication:

"Authorization: Basic " + base64_encode("{API ID}" + ":" + "{password}");

Example header (API ID "10020-140" and password "buNxoOx2o5kM2JMc3VhBX20k4Gik4qKXyKfg332A"):

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=)

The API key configuration in backoffice allows you to restrict incoming requests to specific IP addresses. By default, all IP addresses are permitted until restrictions are configured.

Specific Data Types

Mostly standard data types are used in Sitoo API, but there are some specific ones that need to be paid attention to:

Money

Money values are represented as string with two decimals ("." separates the fraction).

"123.50"

Decimal

Fixed decimal values are represented as string with three decimals ("." separates the fraction).

"123.456"

Decimal Degrees

Decimal degrees as string with 1-3 integer numbers and 6 fractional numbers ("." separates the fraction). Decimal degrees are primarily used to store coordinates.

"123.456789"

Additional Data

Additional Data is meta data that can be stored on certain which allow it. The structure is an object with all values being of string type.

{
  "pos-timezone": "Europe/Stockholm",
  "pos-staff-externalid": "12345"
}

API Updates

The API is constantly being updated to meet demands and new technology. All updates made should always be backwards compatible to avoid interfering with existing integrations. When you integrate with Sitoo API it is very important to ensure future compatibility by ignoring any unknown fields received from the API. The models should always accept to have new fields added to them.

JSON Format

Sitoo REST API uses JSON format for request and response body. The response mime-type is application/json.

Retrieving collections and envelopes

Collections are returned in an envelope. An envelope contains the property items which is the array of objects returned. An envelope also contains the property totalcount which indicates the number of items the query could return. This makes it easy to create a pagination when used with the start and num parameters. Example of a request returning an envelope:

GET https://api.mysitoo.com/v2/accounts/1500/sites/1/products.json?start=2&num=2&fields=productid,sku,title,moneyprice

{
  "totalcount": 15,
  "items": [
    {
      "productid": 12,
      "sku": "10038-1",
      "moneyprice": "10392.00",
      "title": "Sofa Grand III"
    },
    {
      "productid": 13,
      "sku": "10038-5",
      "moneyprice": "10392.00",
      "title": "Kitchen Table"
    }
  ]
}

The totalcount is 15 and the items array contains the two items from index 2 (zero based).

Naming Conventions

For various reasons, most variables in Sitoo API do not have multiple word identifiers but are instead joined. For example, the property Product ID is named productid. There are also objects in Sitoo API which have properties which are prefixed with the type, e.g. moneyprice or datemodified.

Rate limits

Sitoo applies rate limits to all API requests made to protect the system from overload. The limitations are done per time slot and currently resets every 10 minutes. The limit can be reached by either the number of requests or by the consumption of server resources. This fact makes it important to choose an efficient way of using the API. But the most important thing is to make sure that your implementation handles the API rate limits in a correct way.

When a rate limit has been exceeded, the 429 response code will be returned. Any time you get a 429 response code, you need to make sure that your integration waits until the next time slot starts to make new requests. The way to know when the next time slot starts, is by reading the X-Rate-Limit-Reset header value which indicates the number of seconds left until reset.

Example:

X-Rate-Limit-Reset: 57

API requests have to be synchronous

Sitoo API only allows for synchronous requests to the API. When making another API request before a previous one has been completed, the response code will be 429 with the errortext 429: Too many connections.

Errors

When receiving a response code that is not in the 200 range, most endpoints will return an error object. The object returned will look like this:

{
  "statuscode": 400,
  "errortext": "Invalid input, \"skue\" is not a valid field."
}

50x error codes

In the case of receiving a 50x error response from Sitoo API, the reason for it could be due to a very lenghty request (e.g. the process is taking longer then the timeout of the load balancer). A request like this will not unlock the API key for further requests until the process has finished (or the timeslot of 10 minutes has passed).

Best Practice

Only ask for data that you will use. This speeds up the transfer of data and makes the underlying database queries faster. Use the fields parameter to specify which fields to have returned. Specifying fields is key to speed things up.

Some endpoints also have batch operations enabled for POST/PUT/DELETE. Batch operations allows you to send multiple objects at once. In general, it is best practice to limit the size of batch operations, to avoid allocating an extensive amount of request time and resources. The generic best practice for batch size is somewhere between 1000-5000 entries depending on the use cases. In case of reciving 50x error while executing batch operations we recommend lowering the batch size until the service seems to respond in a timely manner.

The batch operation is a shortcut for sending many objects at a time (ie. it is not a transaction where all will fail or succeed). A batch envelope is returned and for every object in the request there, will be an individual result that needs to be checked.

PUT https://api.mysitoo.com/v2/accounts/1500/sites/1/products.json

[
    {
        "productid": 12,
        "moneyprice": "990.00"
    },
    {
        "productid": 13,
        "moneyprice": "1290.00"
    }
]

Response with a batch envelope

[
  {
    "statuscode": 200,
    "return": true
  },
  {
    "statuscode": 200,
    "return": true
  }
]

Errors in batch calls

NOTE! Make sure to verify all items in a response from a batch call. Even though a 200 response code was received in the HTTP request, there can still be partially failed items in the request. The response needs to be thoroughly examined for any statuscode that is not in the 200 range.

Other Response Headers

Sitoo-Request-ID

A unique UUID for the request (implemented for most v2 endpoints).

Example: Sitoo-Request-ID: 86aa994c-7832-47cf-bb4e-dc710411a3b1