Insplay API

Insplay API is built as a RESTful service over the endpoint: https://api.insplay.eu/<method>

Access to the Insplay API (hereinafter simply API) is granted to specific individuals whose user information is linked to each query. The number of queries is limited to 10 per minute, with the ability to distinguish those IP addresses that exceed the set limits. This helps prevent malicious use and ensures quality service for all users.

The API returns retail and wholesale prices, as well as stock levels, for each selected product. The stock level information is updated every 20 minutes. Queries can also include language selection if the product information is translated.

Best Practices:

After the initial import of the product database, we recommend continuously updating stock levels and price information every 10 minutes. The rest of the product information should be updated once a day, preferably at night. Image links can be retrieved using the products method, but we ask that images be updated via the link no more than once a day and preferably at night. It is even better to use the product_images method with the date_since parameter to avoid unnecessary load. This allows you to identify only changed or new images.

We are continuously updating the API, and feedback are important to us. Please let us know what you need, and we will see what can be done. The Changelog provides an overview of API updates.

API Integration

Integrating the API with your online store is simple! Your development partner and most modern systems are ready to set it up within hours. Contact us, and we will create an account for you in our system along with a unique API key, which the developer can use to create specific queries to our database.

Further API description is primarily directed at your development partner.

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

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

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
• out_of_production - End of Life (EOL) or Out of Production product, that is no longer produced. We recommend to deactivate it once the stock is depleted.
  
• 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

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

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:

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:

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