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

Access to Insplay API will be granted to persons, whose user account is used for queries. The number of queries is limited to 10 per minute and we will be able to limit particular IP addresses who overuse the recommended intensity. This is to avoid deliberate misuse and to maintain quality service for all our partners.

API will provide recommended retail price (RRP), wholesale price, and current stock level for every product. Stock level is updated every 20 minutes or less. You can query also language-specific product information for translated products.

Current API provides information in the following categories:

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 - esitleb toodetega seotud müügiargumendid

Best Practice: after downloading the initial products database we recommend updating product stock level and prices not more than every 10 min. We suggest updating the rest of the product data once per day preferably at night time. Product image links can be received through products method but we urge you to update images over links not more than once a day at night time. The recommended option for importing images is over product_images method with date_since parameter. This helps to reduce the load and allows you to import only new or updated images.

We are constantly updating our API and value your feedback. Please let us know if you have specific requests and we will try our best to accommodate them in future updates. You can find an overview of recent API updates from Changelog.

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 creating 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);

if (isset($API['result']) and isset($API['result']['data'])) {
	foreach ($API['result']['data'] as $product_id=>$val) {
		foreach ($val['additional_images'] as $k=>$v) {
			$fn = DATA_DIR.'product_'.$product_id.'_'.$k.'.jpg';
			$fp = fopen($fn, 'wb');
			fwrite($fp, base64_decode($val['image_base64']));
			fclose($fp);
			echo '<a href="'.$fn.'" target="_blank">'.$fn.'</a><br />';
		}
		$fn = DATA_DIR.'product_'.$product_id.'.jpg';
		$fp = fopen($fn, 'wb');
		fwrite($fp, base64_decode($val['main_image_base64']));
		fclose($fp);
		echo '<a href="'.$fn.'" target="_blank">'.$fn.'</a><br />';
	}
}
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"
    }
}

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"
    }
}

API Changelog

29.10.2020

Added code example for image request in php.

28.08.2020

Added product_id, product_image_ids, main_picture_url and additional_picture_urls to product request.