Order Registration (Visual Customizer)

Summary

1. Overview

The Visual Product Customizer generates print-ready files in various formats, provided to the merchant in the "Orders" section of the back-office along with a summary containing purchase information crucial for order fulfillment (learn more here).

These files are generated only when an order, initially received on the e-commerce platform, is subsequently registered on Zakeke. This Zakeke order, sharing the same order number as its e-commerce counterpart, serves as an addition rather than a replacement. It specifically pertains to the customization aspect of the order.

To integrate this workflow effectively, leverage the following API calls:

API REST Call to Register an Order:
Initiate an API REST call to seamlessly register the order on Zakeke after its reception on the e-commerce platform. This step ensures that the Visual Product Customizer generates the necessary print-ready files.
API REST Call to Obtain Print-Ready Files:
Subsequently, utilize another API REST call to obtain a ZIP file containing the print material for each design created. This step is essential for successful order fulfillment.
API REST Call for Re-order the customized products:
Additionally, leverage an API REST call to retrieve information for a re-order. This functionality streamlines the process, providing access to details related to previous orders and enhancing the efficiency of reorder transactions.

By incorporating these API calls, you ensure that you have the necessary tools to efficiently manage and fulfill orders with personalized products through Zakeke.

2. Register an Order

After processing the order in your e-commerce website, if there are custom products you will need to make an S2S (Server to Server) request POST authenticated at the following endpoint:

POST https://api.zakeke.com/v2/order

For every detail related to the API call please refer to ORDER API documentation.

warning

To make the API call you need to authenticate in Zakeke and obtain an authorization token of S2S type. For all the details see the Authentication and Authorization section.

The API call expects a JSON with the following structure in the body:

{
  "orderCode": "string",
  "orderDate": "2024-02-12T16:48:14.169Z",
  "sessionID": "string",
  "total": 0,
  "details": [
    {
      "orderDetailCode": "string",
      "sku": "string",
      "designID": "string",
      "modelUnitPrice": 0,
      "designUnitPrice": 0,
      "quantity": 0,
      "designModificationID": "string"
    }
  ]
}

where:

Property	Data type	Description
orderCode	`string`	Unique identifier of the order on the e-commerce
orderDate	`string`	Order date in ISO 8601 format
sessionID	`string`	The e-commerce session identifier
total	`money`	The total order amount
details	`array`	List of customized product details

For each of the customized product ordered, the object in the details array has following structure:

{
    "orderDetailCode": "string",
    "sku": "string",
    "designID": "string",
    "modelUnitPrice": 0,
    "designUnitPrice": 0,
    "quantity": 0,
    "designModificationID": "string"
}

where:

Property	Data type	Description
orderDetailCode	`string`	Unique identifier that the order detail has in ecommerce
sku	`string`	Unique identifier that the ordered product has in ecommerce
designID	`string`	Unique design identifier provided by Zakeke
modelUnitPrice	`money`	Product unit price without the design price
designUnitPrice	`money`	Unit price applied to customization
quantity	`integer`	Quantity of products ordered
designModificationID	`string`	Identifier assigned by Zakeke for the particular instance of fields values in the case of an order with the Names and Numbers tool or for the bulk purchase with a different print file for each ordered variations

2.1 Example in ASP.NET MVC C#

In the example below, the ZakekeCheckoutOrder function should be called up in the Checkout controller (thankyoupage controller of the site):

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using RestSharp;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Configuration;

// order: order to ckeckout
// userCode: logged user identifier who is ordering on your e-commerce
// sessionID: session ID
public JObject ZakekeCheckoutOrder(OrderEntity order, string userCode,string sessionID)
{
    JObject responseJson = null;
    // Get Authorization Oauth Token S2S with userCode
    string token = getOauthToken(userCode);
    if (!string.IsNullOrEmpty(token))
    {
        // Build body request for ORDER endpoint
        var dataToSend = new
            {
                orderCode = order.ID,
                orderDate = order.date,
                sessionID = sessionID,
                total = order.totalAmount,
                details = order.details.Select(detail => new
                {
                    designID = detail.designID,
                    designUnitPrice = detail.designUnitaryPrice,
                    modelUnitPrice = detail.productUnitaryPrce,
                    quantity = detail.Quantita
                })
            };
            // Make request to Order Endpoint API
            var urlRequest = "https://api.zakeke.com/v1/order";
            var client = new RestClient(urlRequest);
            var request = new RestRequest() { Method = Method.POST };
            request.AddHeader("Authorization", "Bearer " + token);
            request.AddParameter("application/json; charset=utf-8",JsonConvert.SerializeObject(dataToSend), ParameterType.RequestBody);
            try
            {
                var response = client.Execute(request);
                if (response != null && response.StatusCode == System.Net.HttpStatusCode.OK)
                {
                    responseJson = JsonConvert.DeserializeObject<JObject>(response.Content);
                }
                else
                {
                    // Log error that caused request to fail ...
                }
            }
            catch (Exception ex)
            {
                // Log exception ...
            }
            return responseJson;
        }
    }

    private string getOauthToken(string usercode)
    {
        string tokenOauth = string.Empty;;
        var client = new RestClient("https://api.zakeke.com/token");
        var request = new RestRequest() { Method = Method.POST };
        request.AddHeader("Content-Type", "application/json");
        request.AddParameter("grant_type", "client_credentials");
        request.AddParameter("client_id", "your-api-client-id");
        request.AddParameter("client_secret", "your-api-secret-key"]);
        request.AddParameter("customercode", usercode);
        request.AddParameter("access_type", "S2S");
            
        try
        {
            var responseToken = client.Execute(request);
            if (responseToken != null && responseToken.StatusCode == System.Net.HttpStatusCode.OK)
            {
                JObject responseJson = JsonConvert.DeserializeObject<JObject>(responseToken.Content);
                tokenOauth = responseJson["access_token"].ToString();
            }
        }
        catch(Exception ex)
        {
            // Handle Exception
        }
        return tokenOauth;
    }

If the order has been successfully registered, you will be able to view the order in the "Orders" section of your back office and download the design printing material for the products ordered as soon as these become ready.

3. API REST Call to Obtain Print-Ready Files

You can download the print files in two ways:

go to "your orders" page of the back-office, select the reference order and click on "download files for printing". Read the guide on orders and print files for more details.
integrate this feature into your back-office via REST API.

In order to directly integrate the feature into your back-office via API, you will need to make a GET S2S request at this endpoint:

GET https://api.zakeke.com/v1/designs/{designID}/outputfiles/zip/{modificationID}

The designID that is part of the API URL is the unique design identifier that Zakeke passes as input to the calls at the various "AddToCart" and "EditProductInfo". Please refer to Customizer UI API for every detail about the integration endpoints.

The modificationID, also part of the URL of the API call, represents one of the combinations of field values in the case of use of the Names and Numbers tool or one of the product variants purchased in the case of bulk purchase with the option of a different print ready file for each variant.

warning

To make the API call you need to authenticate in Zakeke and obtain an authorization token of type S2S. For all the details see the Authentication and Authorization section.

The API call returns the URL of the ZIP archive that contains all the print-ready files produced for product customization.

For every detail related to the API call please refer to DESIGNS API documentation and, in particular, the Retrieve the ZIP with all print-ready files sub-section.

3.1 Example in ASP.NET MVC C#

Below is an example written in C# of using the API. The GetDesignFiles method returns the URL of the ZIP file after obtaining it by calling the aforementioned API.

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using RestSharp;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Configuration;

// designID: unique design ID generated by ZAKEKE
public string GetDesignZIPFile(string designID)
{
    string urlZIP = string.Empty;
    // Get Authorization Oauth Token S2S
    string token = getOauthToken();
    if (!string.IsNullOrEmpty(token))
    {
        // Make request to Design Files Endpoint API
        var urlRequest =  $"https://api.zakeke.com/v1/designs/{designID}/outputfiles/zip";
        var client = new RestClient(urlRequest);
        var request = new RestRequest() { Method = Method.GET };
        request.AddHeader("Authorization", "Bearer " + token);
        try
        {
            var response = client.Execute(request);
            if (response != null && response.StatusCode == System.Net.HttpStatusCode.OK)
            {
                var responseJson = JsonConvert.DeserializeObject<JObject>(response.Content);
                urlZIP = responseJson["url"];
            }
            else
            {
                // Log error that caused request to fail ...
            }
        }
        catch (Exception ex)
        {
            // Log exception ...
        }
    }
        
    return urlZIP;
}


private string getOauthToken()
{
    string tokenOauth = string.Empty;;
    var client = new RestClient("https://api.zakeke.com/token");
    var request = new RestRequest() { Method = Method.POST };
    request.AddHeader("Content-Type", "application/json");
    request.AddParameter("grant_type", "client_credentials");
    request.AddParameter("client_id", "your-api-client-id"); 
    request.AddParameter("client_secret", "your-api-secret-key"]);
    request.AddParameter("access_type", "S2S");
        
    try
    {
        var responseToken = client.Execute(request);
        if (responseToken != null && responseToken.StatusCode == System.Net.HttpStatusCode.OK)
        {
            JObject responseJson = JsonConvert.DeserializeObject<JObject>(responseToken.Content);
            tokenOauth = responseJson["access_token"].ToString();
        }
    }
    catch(Exception ex)
    {
        // Handle Exception
    }
    return tokenOauth;
}

4. Re-order

To re-order a design already purchased by a customer, it is necessary to place the customized product in the cart again with the same design. However, using the same designID will not be sufficient to obtain new print-ready files. Each time an order is generated for a designID, Zakeke processes that designID and will not do it again for a new order. It will then be necessary to ask Zakeke to duplicate the previous design and obtain a new designID to assign to the customized product to add to the cart.

To duplicate a design Zakeke provides the following API call:

GET https://api.zakeke.com/v2/designs/{designID}

where designID is the unique identifier that Zakeke assigns to a design (customization).

The previous API call returns a JSON object containing the id of the cloned design:

{
    "id": "<cloded-design-id>"
}

For every detail related to the API call please refer to DESIGNS API documentation and, in particular, the Duplicate a design sub-section.

Order Registration (Visual Customizer)

Summary​

1. Overview​

API REST Call to Register an Order:​

API REST Call to Obtain Print-Ready Files:​

API REST Call for Re-order the customized products:​

2. Register an Order​

2.1 Example in ASP.NET MVC C#​

3. API REST Call to Obtain Print-Ready Files​

3.1 Example in ASP.NET MVC C#​

4. Re-order​

Summary

1. Overview

API REST Call to Register an Order:

API REST Call to Obtain Print-Ready Files:

API REST Call for Re-order the customized products:

2. Register an Order

2.1 Example in ASP.NET MVC C#

3. API REST Call to Obtain Print-Ready Files

3.1 Example in ASP.NET MVC C#

4. Re-order