Sitoo Product Search SPI

Sitoo Product Search SPI is a well defined interface which let's a client integrate external products from a data source (service).

SPI (Service Provider Interface)

The SPI is the definition of the API required to use the service. Therefore, the service needs to fully implement the API definition.

Adaptive Filters

When doing a product search it is usually not enough to only have a text to search for. Often there need to be filters involved to narrow the search. Compare to an e-commerce site where you usually can add filters for category, price ranges, brand, color etc. Usually the filters depend on what you search for. They are adaptive to the current search.

Filter Types

There are different types of filters

  • Single enumerated value. One value is allowed from a list of options. (eg. Size)
  • Multiple enumerated values. Multiple values are allowed from a list of options. (eg. Brands)
  • Boolean value. (eg. In Stock)

Product Search Query Parameters

The product search query consists of the following parameters. See Search Products API endpoint specification for more details.

return_only_filtersThis is use to query the endpoint for a base filter set to present to the end user when no search has yet been done. If a value of true is sent for this parameter, then the endpoint will return an empty list of products and the default set of filters to display for a new search.
search_textThe search text is the core of the search, ie. the text to search for. Filters can then also be applied to narrow the search results.
filterThis is the parameter for sending filters to the query.
langThe client will send the language to be used for presenting language specific attributes of the products and filters.
currencyThe client will send the currency to be used for product prices.
store_id, customer_idIf sent, the IDs can be used for having differences in products and prices returned.
start, numUsed for pagination of large result sets.

Product Search Result

The query will return a result object including the following attributes.


This is list of products returned together with the total number of products available, including products that have not been returned.


This is an ordered list of filters that can be applied to the returned products.

Search Text Used

In cases of having logic in the search where if no hits were found by the original search text, but by changing the search text to a similar one a list of products could be found. This field will contain the altered text and can be used to display a better UI in the client.

Sitoo POS implementation

Search services can be implemented in many different ways, all with their own set of features. In Sitoo POS there is a user interface for doing a product search which relies solely on the data provided by the product search service.

There are two product search providers in Sitoo POS; internal and external. A configuration for the POS will decide which one that is enabled or both. If both are selected, then the Product Search UI in the POS will present a possibility to select the data source in the client.

Internal Service

Sitoo POS has built-in support for searching the products that have been synched from the backend. Since it's using local storage for the search, no Internet connectivity is required.

External Service

Any external system that implements the SPI Product Search can be used as a source of products.


Authentication of the calls is optional for the server implementing it, but highly recommended. The authentication should be done using the HTTP basic authentication mechanism. Requests to the endpoint will add an Authorization header to the request. Example:

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=
Do not use the Sitoo API credentials for authenticating the call. The server implementing the SPI needs to have it's own implementation for authentication.

Public Server

The URL used for the service should have public access with a valid SSL certificate.