Insplay API

The Insplay API (hereinafter referred to simply as API) is a secure plug-in between your e-store and the Insplay warehouse and systems that allows you to personally access and manage Insplay products, product information, and processes.

The API provides access to product catalogues – manufacturers and brands, product categories, products and services. It also provides labels, images, information materials, descriptions and related products to the selected item.
The API is linked directly to the systems - uses an API key for secure connection and personalization; lists and handles products with a unique identification number in your e-shop.
The API allows you to make filtered queries -  provides language choice and language content, allows to set query limits and restrictions; data and date ranges, stock levels, etc.

The description of the API

Ligipääs Insplay API'le (edaspidi lihtsalt API) antakse kindlatele isikutele, kelle kasutajainfo seotakse iga päringuga. Päringute arv on piiratud 10'le päringule minutis ja võimalusega eristada need IP aadressid, mis on kõrgema intensiivsusega, kui seatud limiidid. See võimaldab vältida pahatahtlikku kasutust ja tagada kvaliteetse teeninduse kõikidele soovijatele. 

API tagastab iga valitud toote kohta jae- ja hulgihinna ning selle laoseisu. Laoseisu vanus on maksimaalselt 20min. Päringutega kaasneb ka keelevalik, kui tootel on.

Praegune API versioon võimaldab infot vahetada nendes kategooriates
        brands - Lists Product Brands
        categories - Lists Product Categories
        products - Lists available Products
        tags - Lists additional Product Tags with links to Products
        product_images - Gets images of specified Product
        product_attachments - Gets attachments (PDFs, etc.) for specified Products
        product_sale_arguments - Lists Sale Arguments with links to Products

We are constantly updating the API, and your wishes and feedback are important to us. Please let us know what you need and let's see what we can do.

Connecting to the API

Connecting the API to your e-store is easy! Your development partner, as well as the readiness of most modern systems, allows you to set it up in hours.

Contact us and we will create an account for you with our system and generate a unique API key for you, which will allow to create specific queries to our database.

The further description of the API is addressed to your development partner.

Example of an API query in Python

import requests
import json

API_URL = "https://api.insplay.eu"
API_METHOD = "products"
API_ENDPOINT = "{}/{}".format(API_URL, API_METHOD)
API_KEY5 = "Your API Key",
data = {
"api_key": "Your API Key",
"language": "et_EE",
}
headers = {"content-type": "application/json"}
payload = {"params": data}
response = requests.post(API_ENDPOINT, data=json.dumps(payload), headers=headers)
print(response.json())

Example of an API query in PHP

<?php //PHP cURL extension is needed define('API_URL', 'https://api.insplay.eu/'); define('API_METHOD', 'products'); define('API_KEY', 'Your API key here'); define('API_LANGUAGE', 'et_EE'); function getCURL($url, $fields = array(), $headers = array()) { $ch = curl_init(); $options[CURLOPT_URL] = $url; $options[CURLOPT_POST] = count($fields); $options[CURLOPT_POSTFIELDS] = json_encode($fields); $options[CURLOPT_RETURNTRANSFER] = true; if (is_array($headers) and count($headers)) { foreach ($headers as $k => $v) { $options[$k] = $v; } } curl_setopt_array($ch, $options); $result = curl_exec($ch); curl_close($ch); return $result; } $url = API_URL.API_METHOD; $fields = array( 'params' => array( 'api_key' => API_KEY, 'language' => API_LANGUAGE ) ); $headers = array( CURLOPT_HTTPHEADER => array('Content-Type: application/json') ); $APIResult = json_decode(getCURL($url, $fields, $headers)); print_r($APIResult); exit; ?>

Example of an API query in Curl

curl --location --request POST 'https://api.insplay.eu/products

--header 'Content-Type: application/json' --data-raw '{"params":{

    "api_key": "Your API Key",

    "language": "et_EE"

}}'

API details 

Methods

The possible API methods are as follows: 
  • brands - Lists Product Brands
  • categories - Lists Product Categories
  • products - Lists available Products
  • tags - Lists additional Product Tags with links to Products
  • product_images - Gets images of specified Products
  • product_attachments - Gets attachments (PDFs, etc.) for specified Products
  • product_sale_arguments - Lists Sale Arguments with links to Products


Requests are to be made over POST, payloads and responses are in JSON format. Payload data needs to be encapsulated inside a “params” key in the JSON payload.
Requests include these parameters: 
  • api_key - the assigned API key (required)
  • language - locale with territory code, default is et_EE, examples include en_GB, en_US - if a translation does not exist, en_US will be used instead
  • offset, limit - limit the request to specific number of entries, use offset for paging, default is no limit and offset = 0
  • date_since - this field is used to limit results to only such results, that have been updated since this date, the correct format is “YYYY-MM-DD” (some requests may not include this parameter)


Response base object has two parameters: 
  • status - either ‘success’ or ‘error’ 
  • data - data object of the response if the request is successful 
  • error_message - error message of the response if the request is unsuccessful 


Result data follows a set standard of parameter naming conventions. 
  • id, name - every object returned has its own ID and name associated with it 
  • *_id and *_ids - either a single object or a list of objects, where every item is a pair of ID and Name 
  • *_ids_m2m - list of ID and Name pairs, more information should be queried separately with the appropriate method using the IDs returned 
  • The other end of the many2many will also include the inverse ID and Name pairs 
  • create_date - the date of the creation of this object (except for images and attachments) 
  • last_change_date - the date of the last update for this object (except for images and attachments)

Brands

https://api.insplay.eu/brands
Lists available Product Brands.

Request params:
  • api_key (required)
  • language
  • ids - list of brand IDs, limit query to requesting a specific set of brands
  • search_name - specify a name to search brands by, ids parameter takes precedence
  • offset
  • limit


Response data:
  • name
  • description - Brand’s description
  • logo_base64 - Brand logo
  • create_date
  • last_change_date

 {
"api_key": "...",
"language": "et_EE",
"limit": 1,
"search_name": "TTS",
}
{
"id": null,
"jsonrpc": "2.0",
"result": {
"data": [
{
"create_date": "2019-08-26 08:18:06",
"description": false,
"id": 35,
"last_change_date": "2019-12-06 08:26:03",
"logo_base64": "/9j/4AAQSkZJRgABAQAAA...",
"name": "TTS"
}
],
"status": "success"
}
}

Categories

https://api.insplay.eu/categories
Lists available Product Categories. Categories follow a tree structure.

Request params:
  • api_key (required)
  • language
  • ids - list of category IDs, limit query to requesting a specific set of categories
  • search_name - specify a name to search categories by, ids parameter takes precedence
  • brands_ids - specify a brand IDs to search categories by, parameters above take precedence
  • public_categ_ids - specify a category IDs to search categories by, parameters above take precedence
  • date_since
  • offset
  • limit


Response data:
  • name
  • parent_category_id - parent category or False
  • priority - priority of the category, used for sorting
  • code - category code
  • is_published - is category active
  • create_date
  • last_change_date

{
"api_key": "...",
"language": "et_EE",
"limit": 1,
}
{
"id": null,
"jsonrpc": "2.0",
"result": {
"data": [
{
"code": false,
"create_date": "2019-10-29 15:01:52",
"id": 2950,
"is_published": false,
"last_change_date": "2020-01-03 10:00:17",
"name": "Robootika ja elektroonika",
"parent_category_id": false,
"priority": 10000
}
],
"status": "success"
}
}

Products

https://api.insplay.eu/products
Lists Products.

Request params:
  • api_key (required)
  • language
  • ids - list of product IDs, limit query to requesting a specific set of products
  • brand_ids - list of brand ids requesting specific set of brand products
  • search_name - specify a name to search products by, ids parameter takes precedence
  • date_since - specify a date to find all products that have been updated after it, ids and search_name parameters take precedence
  • offset
  • limit


Response data:
  • name
  • description_sale - short description of the product
  • description_sale_long - long description of the product
  • product_code - product code
  • ean13 - EAN13 barcode
  • brand_id - associated brand ID
  • dimensions - dimensions of the products, descriptive text field
  • wholesale_price - wholesale price of the product without VAT
  • under_3_forbidden - is the product forbidden for children under the age of 3
  • create_date
  • last_change_date
  • age_from - appropriate for ages from
  • age_to - appropriate for ages to
  • more_info_url - manufacturer URL for more product info
  • quantity_available - current available quantity
  • keywords - descriptive keywords for the product
  • category_ids - product category IDs and Names
  • sale_argument_ids_m2m - product sale arguments, many2many, IDs and names
  • tariff_no - tariff number for this product
  • origin_country - country this product originates from
  • old_nav_category - category name from the previous ERP system
  • main_picture_url - product main picture url
  • additional_picture_urls - list of additional product pictures
  • recommended_retail_price - recommended retail price (RRP) of the product including Estonian VAT 20%
  • net_weight - net weight of this product in KG
  • height - product height
    length - product length
    width - product width
  • related_products_ids_m2m - related products with many2many relation, pairs of IDs and names

 {
"api_key": "...",
"language": "et_EE",
"limit": 1,
"brand_ids": [35],
}
{
"id": null,
"jsonrpc": "2.0",
"result": {
"status": "success",
"data": [{
"width": 0.0,
"video": false,
"origin_country": "CN",
"last_change_date": "2020-01-03 10:00:10",
"age_from": 3.0,
"quantity_available": 1.0,
"age_to": 0.0,
"keywords": false,
"dimensions": false,
"height": 0.0,
"wholesale_price": 47.94,
"length": 0.0,
"recommended_retail_price": 69.9,
"name": "Õuepintslid (tekstuuripintslid)",
"description_sale": "Nende uuenduslike pintslitega saab luua suurele pinnale mitmekesiseid mustreid, tekstuure ja märke tõmbamise, vajutamise, kaapimise ja keerutamise teel. Neljast varrest ja eri otstest koosnev komplekt sobib kasutamiseks värvi, vee (lombid) ja liivaga. Valmistatud plastist. Komplektis 4 tk. L 22 x P 55 cm.\n ",
"create_date": "2019-07-04",
"category_ids": [],
"description_sale_long": false,
            "additional_picture_urls": ["https://www.insplay.eu/web/image/product.image/43195/image_raw"]
            "main_picture_url": "https://www.insplay.eu/web/image/product.product/35/image_raw"
"net_weight": 1.24,
"more_info_url": "www.tts-international.com",
"id": 4022,
"brand_id": [
35,
"TTS"
],
"tariff_no": "95030095",
"under_3_forbidden": true,
"product_code": "AR00797B",
"ean13": false,
"related_products_ids_m2m": [],
"old_nav_category": "DE2F3A4E-877B-4C14-93C1-FB9F957F2748"
}]
},
}

Product Tags

https://api.insplay.eu/tags
List available Product Tags with their associations to Products.

Request params:
  • api_key (required)
  • language
  • ids - list of category IDs, limit query to requesting a specific set of categories
  • offset
  • limit


Response data:
  • name
  • code - Tag code
  • associated_category - Associated product category
  • product_ids_m2m - associated product IDs, many2many, pairs of IDs and names
  • create_date
  • last_change_date

{
"api_key": "...",
"ids": [1],
"language": "et_EE"
}
{
"id": null,
"jsonrpc": "2.0",
"result": {
"data": [
{
"associated_category": false,
"code": false,
"create_date": "2019-10-09 08:52:25",
"id": 1,
"last_change_date": "2019-10-09 08:52:25",
"name": "Arduino",
"product_ids_m2m": []
}
],
"status": "success"
}
}

Product Images

https://api.insplay.eu/product_images
Returns Product Images (main image and other images) for the specified products.

Request params:
  • api_key (required)
  • language
  • product_ids (required or date_since) - list of product IDs, limit query to images of the specified products
  • date_since (required or product_ids)- specify a date to find all products that have been updated after it, product_ids parameter takes precedence
  • offset
  • limit (max 100)


Response data:
  • dictionary of images for each product, where key is Product ID and value is:
    • main_image_base64 - base64 encoded main image
    • additional_images - list of additional images with following dictionary data for each object:
      • name - descriptive name of the associated image
      • image_base64 - base64 encoded image

{
"api_key": "...",
"language": "et_EE",
"product_ids": [1],
}
{
"id": null,
"jsonrpc": "2.0",
"result": {
"status": "success",
"data": {
"1": {
"main_image_base64": "/9j/4AAQSkZJRgABAQAAA...",
"additional_images": []
}
},
},
}

Product Attachments

https://api.insplay.eu/product_attachments
Returns all associated documents and attachments for the specified products.

Request params:
  • api_key (required)
  • language
  • product_ids (required or date_since) - list of product IDs, limit query to requesting attachments for the specified products
  • date_since (required or product_ids) - specify a date to find all products that have been updated after it, product_ids parameter takes precedence
  • offset
  • limit (max 100)


Response data:
  • dictionary of images for each product, where key is Product ID and value is a list, where each object’s is a dictionary of:
    • descriptive_name - name of the attachment
    • filename - full filename of the attachment
    • mimetype - mimetype of the attachment
    • content_base64 - base64 encoded file data
    • Product Sale Arguments
    • https://api.insplay.eu/product_sale_arguments

{
"api_key": "...",
"language": "et_EE",
"product_ids": [1],
}
{
"id": null,
"jsonrpc": "2.0",
"result": {
"data": {
"1": []
},
"status": "success"
}
}

Product Sale Arguments

https://api.insplay.eu/product_sale_arguments
List available Product Sale Arguments with their associations to Products.

Request params:
  • api_key (required)
  • language
  • ids - list of argument IDs, limit query to requesting a specific set of sale arguments
  • offset
  • limit


Response data:  

  • name
  • priority - priority of the sale argument, used for sorting
  • description - description of the sale argument
  • product_ids_m2m - associated product IDs, many2many, pairs of IDs and names
  • create_date
  • last_change_date


{
"api_key": "...",
"language": "et_EE",
"limit": 1
}
{
"id": null,
"jsonrpc": "2.0",
"result": {
"data": [
{
"create_date": "2019-10-10 14:16:52",
"description": "Komplektis on ~40 osa ja konstruktori kokkupanek on lihtne tänu samm-sammult järgitavale juhendile",
"id": 1,
"last_change_date": "2019-10-10 14:18:11",
"name": "Komplektis on ~40 osa ja konstruktori kokkupanek on lihtne tänu samm-sammult järgitavale juhendile",
"priority": 1,
"product_ids_m2m": []
}
],
"status": "success"
}
}