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.
| Parameter | Description |
|---|---|
| return_only_filters | This 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_text | The 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. |
| filter | This is the parameter for sending filters to the query. |
| lang | The client will send the language to be used for presenting language specific attributes of the products and filters. |
| currency | The client will send the currency to be used for product prices. |
| store_id, customer_id | If sent, the IDs can be used for having differences in products and prices returned. |
| start, num | Used for pagination of large result sets. |
Product Search Result
The query will return a result object including the following attributes.
Products
This is list of products returned together with the total number of products available, including products that have not been returned.
Filters
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
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=Public Server
The URL used for the service should have public access with a valid SSL certificate.