Zakeke uses cookies to provide necessary site functionality and improve your experience. By using our website, you agree to our privacy policy and our cookie policy.   

API Integration

Customizer page

The customizer page is the fundamental part of Zakeke integration into your e-commerce website.
It will allow your customers to create or modify their customizations based on your models imported through the CSV catalogue, and then to add them to the shopping cart.

It will be shown in these case:

The integration of the customizer into your e-commerce website requires the following steps:

1. Create the customizer page

In your e-commerce website you have to create a new page (in the example a HTML page) whose layout will be that of your website and the content will have a div so defined (highlighted):

<!-- header html layout... -->
<div class="container">
<div id="zakeke-container"></div>
</div>
<!-- footer html layout... -->

2. Configuration Javascript

Before closing the <body> tag of the previously created page, add the following Javascript references:

<script src="https://www.zakeke.com/scripts/config.js"></script>
<script src="https://www.zakeke.com/scripts/integration/api/customizer.js"></script>

Then add the following Javascript block that will start the customizer on the page:

<script>
    var config = {config};
    var productJson = {"id":"[productid]", "name":"[productname]"};
    var customizer = new zakekeDesigner(config, productJson);
</script>

productJson

productJson is a JSON object formed by:

productid (string) Unique product ID
productname (string) Name of the customizable product

config

config is a javascript object structured as follows:

{
  "tokenoauth": "Token Oauth",
  "mobileversion": false,
  "cartbuttontext": "Add to cart",
  "shoppingcarturl": "[url-endpoint-add-to-cart]",
  "shoppingcarturlcallback": {javascript function object},
  "editshoppingcarturl": "[url-endpoint-edit-product-into-cart]",
  "editshoppingcartcallback": {javascript function object},
  "savedesigncallback": {javascript function object},
  "productinfourl": "[url-endpoint-info-product]",
  "additionaldata":  {},
  "canSaveDesign": false,
  "culture": "en-US",
  "currency": "USD",
  "designid": "",
  "pricetaxincluded": true,
  "labeltax": "hidden",
  "quantity": 1,
  "sides": ['codeSide1',...,'codeSiden'],
  "selectedattributes": {
      "attributekey1": "selectedattributevalue1",
      //...//
      "attributekeyn": "selectedattributevaluen"
  }
}

whose properties are defined in the table below:

Property Description Default value
tokenoauth
mandatory
type: string
Authentication Token Oauth with additional information about visitor and/or authenticated user (for more details go to how to obtain an authentication token with customer and/or visitor code")

mobileversion
optional
type: boolean
  • true: customizer IFRAME will be adapted for the mobile version
  • false: customizer IFRAME will be adapted for the desktop version
false
cartbuttontext
optional
type: string
Label of the "Add to cart" button inside the IFRAME Add to cart
shoppingcarturl
Optional (mandatory if shoppingcartcallback has not been defined)
type: string
Endpoint URL to add the custom product to the shopping cart
For more details go to how to configure the "AddToCart" endpoint
shoppingcartcallback
Optional (mandatory if shoppingcarturl has not been defined)
type: object
Javascript function on Merchant web site to handle adding of customized product to shopping cart.
For more details go to how to configure the "EditProductIntoCart" endpoint.
editshoppingcarturl
optional (mandatory if editshoppingcartcallback has not been defined)
type: string
Endpoint URL to manage custom product editing from shopping cart. For more details go to how to configure the "EditProductIntoCart" endpoint.
editshoppingcartcallback
optional (mandatory if editshoppingcarturl has not been defined)
type: object
Javascript function on Merchant web site to handle editing of customized product into shopping cart.
For more details go to how to configure the "EditProductIntoCart" endpoint.
canSaveDesign
optional
type: boolean
  • true: enable feature to save or change existing design for a customized product previously added into cart
  • false: disable feature explained above
false
savedesigncallback
optional (mandatory if canSaveDesign is set to true)
type: object
Javascript function on Merchant web site to handle change design event of customized product into shopping cart.
For more details go to how to configure the "SaveDesign" endpoint.
productinfourl
mandatory
type: string
Endpoint URL to obtain product information based on the selection of attributes.
For more details go to how to configure the "ProductInfo" endpoint.
additionaldata
optional
type: json object
Additional data to send to merchant endpoints
culture
mandatory
type: string
Example: en-US
IFRAME interface language based on Microsoft encoding table.
For details on encoding go to this link.
currency
mandatory
type: string
Example: USD
Currency selected by your the customer on your store, with ISO 4217 encoding.
designid
mandatory for editing a customized product
type: string
Zakeke generated ID design of the customized product to be modified.
labeltax
Optional
type: string
Indicates how tax label will be presented in the IFRAME interface.
Possible values:
  • hidden: the label is hidden
  • including: label "taxes included" is displayed
  • excluding: label "taxes excluded" is displayed
hidden
quantity
mandatory
type: integer
Customizable product quantity to be added/edited
imagepreviewheight
optional
type: integer
Height in pixel of the preview generated by Zakeke 200
imagepreviewwidth
optional
type: integer
Width in pixel of the preview generated by Zakeke 200
sides
optional
type: array of string
Example:
['side1','side2']
Codes of product sides (defined in the sides CSV) on which customization is allowed
selectedattributes
mandatory if the product has variants
type: JSON object
Example:
{'color':0,'size':1}
Selected product attributes sent to the customizer page.
They are formed by a key-value pair consisting respectively of the attribute name (used in forms) and the coded value.
N.B.The key value pairs must match the attributes imported in the CSV feed. (For more details go to how importing products through CSV)

3. Server Side Endpoints

3.1. Endpoint ProductInfo

Zakeke IFRAME will need to call an endpoint(or callback) implemented in your e-commerce in order to get information such as the updated price inclusive of design.

The endpoint will be requested in POST, where the following JSON object will be sent into body request:

{
    "productid": "productid",
    "quantity": 1,
    "selectedattributes": [{"attrKey1":"attrValue1"},...,{"attrKeyn":"attrValuen"}], /* (e.g. [{"color":"0","size":"1"}]) */
    "zakekeprice": 10.5,
    "zakekepercentageprice": 10,
    "additionaldata": {}
}

Where:

productid (string) Unique product ID
quantity (integer) selected quantity of product to be customized
selectedattributes key-value pair of selected product attributes
N.B. the attribute keys match those imported from CSV
zakekeprice (money) unit price (in the currency of your e-commerce) of the created design to be added to the one of the product
zakekepercentageprice (money) Percentage of the created design to be added to the one of the product, to be applied to the unit price of the product
additionaldata (json object) (optional) Additional data to send to endpoint

Endpoint Response in JSON format, must be structured as follows:

{   
    "finalprice": money,
    "isoutofstock": boolean
}

Where:

finalprice Final price calculated depending on the added design and unit price of the model product
isoutofstock
  • false: if product is in stock
  • true: if product is not available (out of stock, ect.)

Below is an example in ASP. NET MVC C# of the ProductInfo Endpoint:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
public class EndpointZakekeController : Controller
{
    [HttpPost]
    [Route("zakeke/getproductinfo")]
    public JsonResult GetInfoProduct(string jsonInput)
    {
        // Deserialize JSON and get relative properties
        JObject jsonObj = JObject.Parse(jsonInput);
        decimal finalPrice = 0m;
        string productid = (string)jsonObj["productid"];
        int quantity = (int)jsonObj["quantity"];
        Dictionary<string,string> selectedattributes = ((IDictionary<string, string>)jsonObj["selectedAttributes"]).ToDictionary(p => p.Key, p => p.Value);
        decimal zakekePrice = (decimal)jsonObj["zakekePrice"];
        decimal zakekePercentagePrice = (decimal)jsonObj["zakekePercentagePrice"];
        ProductEntity product = null;
        // ProductEntity has these properties:
        // 1. unitPrice : unitary product price
        // 2. stockquantity: quantity stock
           
        // Code to get product object from id and selected attributes (depending by ORM used)
        // ....
        finalPrice = (product.unitPrice * quantity) + zakekePrice;
        if (zakekePercentagePrice > 0m)
        {
            finalPrice += (product.unitPrice * zakekePercentagePrice * quantity) / 100;
        }
        return Json(new
        {
            finalprice = finalPrice,
            isoutofstock = product.stockquantity < quantity
        });
    }
}

3.2 Endpoint AddToCart

Clicking "Add to cart" button inside IFRAME interface, will perform a POST request to the endpoint "AddToCart" with aim of adding customized product to shopping cart.

Endpoint Response in JSON format, must be structured as follows:

{
    "productid": "productid",
    "designid": "designid",
    "quantity": 1,
    "selectedattributes": [{"attrKey1":"attrValue1"},...,{"attrKeyn":"attrValuen"}], /* (e.g. [{"color":"0","size":"1"}]) */
    "additionaldata": {}
}

Where:

productid (string) Unique product ID
designid (string) Unique design ID applied to the customized product
quantity (integer) Quantity of customized product to add to shopping cart
selectedattributes key-value pair of selected attributes
N.B. attribute keys match those imported by CSV products
additionaldata (json object) (optional) Additional data to send to endpoint

Note that designid is present in the request, which is needed to obtain design information to send to shopping cart, created using the REST API. (Go to DESIGN API for more information.) In response, the endpoint must provide a JSON object that will contain the URL of the shopping cart page

{   
    "returnurl": string (shopping cart URL)
}

Below is an example in ASP. NET MVC C# of the AddToCart endpoint:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using RestSharp;
public class EndpointZakekeController : Controller
{
    [HttpPost]
    [Route("zakeke/addtocart")]
    public JsonResult AddProductToCart(string jsonInput)
    {
        // Deserialize JSON and get relative properties
        JObject jsonObj = JObject.Parse(jsonInput);
        string productid = (string)jsonObj["productid"];
        string designid = (int)jsonObj["designid"];
        int quantity = (int)jsonObj["quantity"];
        Dictionary<string,string> selectedattributes = ((IDictionary<string, string>)jsonObj["selectedAttributes"]).ToDictionary(p => p.Key, p => p.Value);
        
        // Get User shopping cart
        ShoppingCartEntity cart = null;
        // Code to get user shopping cart ....
        // Get Design information via Zakeke API Rest using RestSharp (see API reference for details)
        Design designinfo = null;
        var client = new RestClient("https://api.zakeke.com/v1/designs/" + designid);
        var request = new RestRequest() { Method = Method.GET };
        request.AddHeader("Authorization", "Bearer " + "Your OAuth Token S2S");
        try
        {
            var response = client.Execute(request);
            if (response != null && response.StatusCode == System.Net.HttpStatusCode.OK)
            {
                design = new ZakekeDesign();
                JObject responseJson = JsonConvert.DeserializeObject<JObject>(response.Content);
                string urlPreviewImage = responseJson["tempPreviewImageUrl"].ToString();
                decimal designUnitPrice = decimal.Parse(responseJson["designUnitPrice"].ToString());
                decimal designUnitPercentagePrice = decimal.Parse(responseJson["designUnitPercentagePrice"].ToString());
                decimal priceToAdd = ((design.designUnitPercentagePrice / 100) * prodotto.PrezzoUnitarioScontato) + design.designUnitPrice;
                cart.Add(productid, designid, pricetoadd, quantity, urlPreviewImage);
    
                return Json(new { returnurl = "http://your.store.com/shopping-cart" });
            }
        }
        catch (Exception ex)
        {
            // Handle exception ...
        }
    }
}
3.2.1 Callback javascript

Alternatively, if the shoppingcartcallback property is defined in the configuration javascript, you can use a javascript functions to manage the adding of the customized product to the cart. The callback will receive the json object defined above as input.

<script>
// Callback edit product into shopping cart
function callback(jsonInput)
{
    // callback code to handle adding customized product to shopping cart event
}
    
// Customizer config
var config = 
{
    ...
shoppingcartcallback : callback,
    ...
}
// Product config
var productJson  = 
{
    ...
}
var customizer = new zakekeDesigner(config, productJson);
</script>

3.3 Endpoint EditProductIntoCart

When a customized product into cart is modified, the button add to the shopping cart will be replaced with the "edit" button, whose callback will be managed by the "EditProductIntoCart" endpoint.

The endpoint must update the custom product previously added into the shopping cart, with the one with the new design.

N.B.The design ID will remain unchanged even after the editing.

The following JSON object will be sent in the body of the request:

{
    "productid": "productid",
    "designid": "designid",
    "quantity": 1,
    "selectedattributes": [{"attrKey1":"attrValue1"},...,{"attrKeyn":"attrValuen"}], /* (e.g. [{"color":"0","size":"1"}]) */
    "additionaldata": {object}
}

Where:

productid (string) Unique product ID
designid (string) Unique design ID applied to the customized product
quantity (integer) Quantity of customized product to add to shopping cart
selectedattributes key-value pair of selected attributes
N.B. attribute keys match those imported by CSV products
additionaldata (json object) (optional) Additional data to send to endpoint

Note that the designid is present in the request, which is needed to obtain design information created using the REST API. (Go to DESIGN API for more information.) In response, the endpoint must provide a JSON object that will contain the URL of the shopping cart page

{   
    "returnurl": string (shopping cart url)
}

Below is an example in ASP. NET MVC C# of the EditProductIntoCart endpoint:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using RestSharp;
public class EndpointZakekeController : Controller
{
    [HttpPost]
    [Route("zakeke/editproduct")]
    public JsonResult EditProductIntoCart(string jsonInput)
    {
        // Deserialize JSON and get relative properties
        JObject jsonObj = JObject.Parse(jsonInput);
        string productid = (string)jsonObj["productid"];
        string designid = (int)jsonObj["designid"];
        int quantity = (int)jsonObj["quantity"];
        Dictionary<string,string> selectedattributes = ((IDictionary<string, string>)jsonObj["selectedAttributes"]).ToDictionary(p => p.Key, p => p.Value);
        
        // Get User shopping cart
        ShoppingCartEntity cart = null;
        // Code to get user shopping cart ....
        // Get Design information via Zakeke API Rest using RestSharp (see API reference for details)
        Design designinfo = null;
        var client = new RestClient("https://api.zakeke.com/v1/designs/" + designid);
        var request = new RestRequest() { Method = Method.GET };
        request.AddHeader("Authorization", "Bearer " + "Your OAuth Token S2S");
        try
        {
            var response = client.Execute(request);
            if (response != null && response.StatusCode == System.Net.HttpStatusCode.OK)
            {
                design = new ZakekeDesign();
                JObject responseJson = JsonConvert.DeserializeObject<JObject>(response.Content);
                string urlPreviewImage = responseJson["tempPreviewImageUrl"].ToString();
                decimal designUnitPrice = decimal.Parse(responseJson["designUnitPrice"].ToString());
                decimal designUnitPercentagePrice = decimal.Parse(responseJson["designUnitPercentagePrice"].ToString());
                decimal priceToAdd = ((design.designUnitPercentagePrice / 100) * prodotto.PrezzoUnitarioScontato) + design.designUnitPrice;
                // Remove from cart, customized product with the old design
                cart.Remove(productid, quantity, designid);
                // Add to cart, customized product with the new design
                cart.Add(productid, designid, pricetoadd, quantity, urlPreviewImage);
    
                return Json(new { returnurl = "http://your.store.com/shopping-cart" });
            }
        }
        catch (Exception ex)
        {
            // Handle exception ...
        }
    }
}
3.3.1 Callback javascript

Alternatively, if the editshoppingcartcallback property is defined in the configuration javascript, you can use a javascript functions to manage the editing of the customizer product into the cart. The callback will receive the json object defined above as input.

<script>
// Callback edit product into shopping cart
function callback(jsonInput)
{
    // callback code to handle edit customized product event
}
    
// Customizer config
var config = 
{
    ...
editshoppingcartcallback : callback,
    ...
}
// Product config
var productJson  = 
{
    ...
}
var customizer = new zakekeDesigner(config, productJson);
</script>

3.4 Save design javascript callback

Javascript functions to handle change design event for a customized product previously added to cart. The callback will receive the json object defined below as input.

{
    "designid": string
}

Where:

designid Unique design ID