Designs API

Summary

1. Overview

In the context of the Zakeke API, "designs" refer to the entirety of artwork or graphical elements created by the customer during the personalization process using the Visual Product Customizer.

The Designs API is a collection of endpoints meticulously crafted to access information related to customer-generated artwork and manage them.

2. List of endpoints

The following are the enpoints available for the Designs API.

Please Note

All the endpoints have the following base url: https://api.zakeke.com/

warning

All API calls need to be authenticated and authorized via an S2S-type oAuth token. For all the details see the Authentication and Authorization section.

Method	Endpoint	Description
GET	`/v3/designs/{designID}/{quantity}`	Retrieves information about a design given its ID.
POST	`/v2/designs/{designID}`	Duplicate a design.
GET	`/v1/designs/{designID}/items`	Retrieve information about the design items.
GET	`/v1/designs/{designID}/outputfiles/zip`	Retrieve the zip file containing all the print-ready files generated for a given design.
GET	`/v1/designs/{designID}/outputfiles/{fileFormat}`	Retrieve the print-ready generated for the design in a specified format.
GET	`/v3/designs/seller`	Returns all the designs created by your customers.
GET	`/v1/designs/seller/occurrences`	Returns the total number of designs created by your customers.
GET	`/v1/designs/seller/customers`	Returns a list of customer codes who have created designs.

In the following sections we will provide details of each endpoint with a description of the information they provide and the operations they follow.

3. Error codes

In RESTful API calls, such as those made to Zakeke, HTTP status codes are crucial for indicating the outcome of API requests. Codes in the 2xx range signify successful operations, 4xx errors denote client-side issues, and 5xx errors indicate server-side problems. This system allows developers to quickly identify and address issues with API interactions, enhancing the efficiency of integrating with Zakeke's services.

For certain status codes, Zakeke includes an error message in the response body to elucidate the cause of the error. This is particularly useful when a single status code, like 404 Not Found or 400 Bad Request, could indicate various issues. These messages help developers pinpoint the specific problem, facilitating a more efficient troubleshooting process when integrating with Zakeke's APIs. In these cases, the body of the response will provide a JSON object like the following:

{
    "message": "Design id: 000-pLheeWxP125a8axD07QthB not found",
    "errorCode": null
}

or like the following:

{
    "message": "Design Files have ModificationID: need to specify ModificationID.",
    "errorCode": null
}

The errorCode property is not used for now but in the future it could be useful to identify specific errors, coded in a documented way.

4. Retrieve a design by ID

With this endpoint you can retrieve relevant data about a design, including pricing information that depends on the quantity specified in the call.

Request

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

The designID is the unique design identifier. Zakeke generates this identifier when a customizaed product is added to the cart. The quantity parameter is optional (by default it is 1) and is used to compute the mark-up price.

In the case of a design created with the Names and numbers tool or a purchase made in Bulk variations mode with the option of a single print-ready file per variant, you can specify the modificationID identifier to indicate which combination of fields you are referring to (Names and numbers) or to which particular variant (Bulk variations purchase). In this case the request endpoint becomes the following:

GET https://api.zakeke.com/v3/designs/{designID}/{quantity}?modificationID={modificationID}

Response

The API call returns a JSON with the following structure:

{
  "designID": "string",
  "compositionID": "string",
  "name": "string",
  "modelCode": "string",
  "modelID": 0,
  "previewimageurl": "string",
  "designUnitPercentagePrice": 0,
  "designUnitPrice": 0,
  "customerCode": "string",
  "visitorCode": "string",
  "previewFiles": [
    {
      "url": "string",
      "sideName": "string"
    }
  ]
}

where:

Property	Data type	Description
designID	`string`	Unique design identifier generated by Zakeke.
compositionID	`string`	Unique configuration identifier, in the case of combined use of the configurator and customizer.
name	`string`	Name assigned to the design if it was previously saved as a draft.
modelCode	`string`	Product unique identifier in the ecommerce. Corresponds to the MasterProductID of the product uploaded with the CSV file.
previewimageurl	`string`	Preview image of the first side of the customized product.
designUnitPercentagePrice	`money`	Percentage to be applied to the product base unit price to obtain the mark-up price.
designUnitPrice	`money`	Unit mark-up price to apply (value depends on back office pricing rules settings.Remember, the price is unit.)
customerCode	`string`	Registered customer identifier of your store, owner of this design.
visitorCode	`string`	Visitor identifier of your store, owner of this design.
previewFiles	`array object`	List of the preview images generated for all the sides of the customized product.

The previewFiles contains an array of objects of the following type:

{
   "url": "string",
   "sideName": "string"
}

where:

Property	Data type	Description
url	`string`	URL of the preview image generated for the specific side of the customized product.
sideName	`string`	Name of product side.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the searched design.
400	Bad Request	Invalid request format. Check parameters used in the request.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	The design with the specified ID was not found.

5. Duplicate a design

This endpoint allows you to duplicate a design to reuse it in a new purchase.

Request

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

Response

The API call returns a JSON with the following structure:

{
  "id": "string"
}

where:

the propriety id is the designID of the new generated design.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the searched design.
400	Bad Request	Invalid request format. Check parameters used in the request.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	The design with the specified ID was not found.

6. Retrieve design items

This endpoint provides detailed information about all the graphical items contained in a design. When we talk about items we are therefore talking about all the graphic elements (images, texts, shapes, etc.) that the user can insert or that are included in a design template. The various items are inserted into a hierarchical structure that indicates the variant, the side and the area that contains them.

Request

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

The designID is the unique design identifier.

Response

The API call returns a JSON with the following structure:

{
  "variant": {
    "name": "string",
    "code": "string",
    "sides": [
      {
        "name": "string",
        "ppcm": 0,
        "areas": [
          {
            "name": "string",
            "items": [
              {
                "json": "string",
                "name": "string",
                "urlDesignItem": "string",
                "previewImageUrl": "string",
                "sourceImageUrl": "string",
                "code": "string",
                "imageName": "string",
                "text": "string",
                "fontFamily": "string",
                "coordinates": {
                  "x": 0,
                  "y": 0,
                  "unit": "string"
                },
                "dimensions": {
                  "width": 0,
                  "height": 0
                },
                "itemColors": [
                  {
                    "rgbCode": "string",
                    "pantoneCode": "string"
                  }
                ],
                "colorMappings": {
                  "additionalProp1": "string",
                  "additionalProp2": "string",
                  "additionalProp3": "string"
                },
                "customOptions": "string"
              }
            ],
            "gridName": "string"
          }
        ],
        "sidePrintTypeName": "string"
      }
    ]
  }
}

For the product variant for which the design has been created, the structure reports the following properties:

Property	Data type	Description
name	`string`	Variant name.
code	`string`	Coding of the e-commerce variant. For products imported with CSV, the field reports the sequence of key-value pairs of the attributes that identify the variant.
sides	`array`	List of information for product sides for the variant.

For each side of the sides property, the structure contains an object with the following properties:

Property	Data type	Description
name	`string`	Side name.
ppcm	`integer`	The number of pixels per cm in the side image. The PPCM (pixels per centimeter) represent a way to specify the physical dimensions of what is depicted in the image, as well as the printing areas that is defined for this side of the product. It can be calculated using both the distance in pixels and centimeters between any two points in the image. If the distance in cm that separates two points in the image is known, the PPCMs can be obtained by dividing the number of pixels that separates these points by this known distance in cm.
sidePrintTypeName	`string`	The name of the printing method associated to the side, if any.
areas	`array`	The list of all print area in the side.

For each area in the areas array, the structure contains on object with the following properties:

Property	Data type	Description
name	`string`	Print area name.
gridName	`integer`	The name of the grid structure containing an image collage, if any.
items	`array`	The list of all items contained in the print area.

For each item in the items array, the structure contain an object with the following properties:

Property	Data type	Description
json	`string`	A JSON representation of the element's graphics properties.
name	`string`	The name of item, if any.
urlDesignItem	`string`	[Deprecated] In the case of an image item, the URL of the item's preview image.
previewImageUrl	`string`	In the case of an image item, the URL of the item's preview image.
sourceImageUrl	`string`	In the case of an image item, the URL of the original image, the one uploaded by the user.
code	`string`	In the case of an image item, the code assigned to the image, if any.
imageName	`string`	In the case of an image item, the name assigned to the image, if any.
text	`string`	In the case of a text item, the text content of the item.
fontFamily	`string`	In the case of a text item, the font family name used for the text.
coordinates	`object`	The position of the element relative to the top-left corner of the print area. The object also reports the unit of measurement in which the coordinates are expressed. For now only millimeters (mm) are used.
dimensions	`object`	The width and height of the item in millimeters (mm)
itemColors	`array`	In the case of a text or SVG image element, it reports the list of colors of the element in RGB format and with the relative Pantone color (if any), as per the mapping defined in the Zakeke back-office. If the user has changed one or more colors of the SVG, the color reported will be the new color specified by the user.
colorMappings	`object`	For some types of printing methods, in the Zakeke back-office it is possible to establish a maximum number of colors that can be used for images and possibly a reference palette to use for an automatic color reduction process. The end user can intervene in the recoloring process by indicating different color substitutions than those performed by the automatic process. The property reports the color substitutions that occurred in the process.
customOptions	`string`	Custom options specified for the item, if any

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the searched design.
400	Bad Request	Invalid request format. Check parameters used in the request.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	The design with the specified ID was not found.

7. Retrieve the ZIP with all print-ready files

Using this endpoint you will get the URL to download a ZIP file that contains all the print-ready files generated for the specified design.

warning

The generation of print files is an asynchronous process that is launched in the background by Zakeke when receives notification of an order via the Order Registration API call. This means that from the moment a new order arrives until the print-ready files become ready the API call will return an HTTP 404 Not Found error. It will be necessary to try again after a few seconds and in any case until the call returns the status 200 - OK.

Request

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

The designID is the unique design identifier.

In case of use of the Names and number or the Bulk variations purchase, it is possibile specify the

In the case of a design created with the Names and numbers tool or a purchase made in Bulk variations mode with the option of a single print-ready file per variant, it is possible to specify the modificationID identifier to indicate which combination of fields you are referring to (Names and numbers) or to which particular variant (Bulk variations purchase). In this case the request endpoint becomes the following:

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

Response

The API call returns a JSON with the following structure:

{
  "url": "https://...."
}

where the url property is the URL of the requested ZIP file.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the requested URL.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	The specified design was not found in any order or the print files are not ready yet.

8. Retrieve print-ready file with a given file format

This endpoint allows you to obtain the URL of the print-ready file produced for the specified design and format.

warning

Request

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

where designID is the unique design identifier fileFormat is the required file format. For the file format we can specify one of the following "PNG", "JPG", "PDF", "SVG", and "DXF".

GET https://api.zakeke.com/v1/designs/{designID}/outputfiles/{fileFormat}?modificationID={modificationID}

Response

The API call returns the string representing the URL of the requested file in the specified foramt.

"https://...."

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the requested URL.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	The specified design was not found in any order or the print files are not ready yet.

9. Retrieve all the designs

This endpoint returns all the designs created by your customers.

Request

GET https://api.zakeke.com/v3/designs/seller

For the endpoint it is possible to specify a series of parameters in query string that allow you to obtain a filtered result and to perform pagination of the result. Pagination of the result is particularly important to obtain optimal performance in the presence of a large number of designs.

warning

Use pagination parameters and an optimal page size (maximum 100 items per page) to maintain good performance when running the API.

The following are the parameters you can use in query string for filtering and pagination:

Parameter	Data type	Description
designID	`string`	To get a single design.
draft	`boolean`	To get the designs saved as draft by the end users.
customerCode	`string`	To get the designs created by a specific customer.
onlyForCustomers	`boolean`	To get only the designs created by customers and not even those of simple visitors.
queryText	`string`	To get only the designs that has the specified text in the name or in the tags.
pageSize	`integer`	The page size of the result. Used for pagination in combination with the `x-ms-continuation` custom header

Response

The API call returns a JSON with the following structure:

{
  "continuationToken": "string",
  "designs": [
    {
      "designID": "string",
      "compositionID": "string",
      "name": "string",
      "modelCode": "string",
      "modelID": 0,
      "previewimageurl": "string",
      "customerCode": "string",
      "visitorCode": "string",
      "previewFiles": [
        {
          "url": "string",
          "sideName": "string"
        }
      ],
      "tags": [""]
    }
  ]
}

The designs property contains the list of designs that make up the current result page. Each design is an object that has the same structure as the object returned by the endpoint to obtain a single design.

When the pagination is used (the highly recommended mode), continuationToken property contains a string to use in the next call to get the next page of results. To send the continuationToken in the next request you can use the x-ms-continuation custom header. Let us suppose we choose a page size of 20 items per page. The first request will be as follows:

curl -X GET https://api.zakeke.com/v3/designs/seller?pageSize=20 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

In the response we will get a JSON object of the type:

{
  "continuationToken": "{\"tokens\":[{\"id\":\"designs\",\"token\":.......",
  "designs": [
    {
      "designID": "000-RE1olDzbT234viB6D11a10",
      // ...
    },
    {
      "designID": "000-ff2348ba123eecd1411234",
      // ...
    },
    {
      "designID": "000-ab981184331123498awfwe",
      // ...
    },
    // ...
    // ...
  ]
}

The request to get the second result page will be as follows:

curl -X GET https://api.zakeke.com/v3/designs/seller?pageSize=20 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"
     -H "x-ms-continuation: {\"tokens\":[{\"id\":\"designs\",\"token\":......."

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the requested design list.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No design was found that meets the conditions of the request.

Examples

Example 1 Get all the draft designs:

curl -X GET https://api.zakeke.com/v3/designs/seller?pageSize=20&draft=true \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

Example 2 Get the draft designs of a specific customer:

curl -X GET https://api.zakeke.com/v3/designs/seller?pageSize=20&draft=true&customerCode=wq23r9123 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

Example 3 Get customer designs that have the text "Christmas" in the name (or tags)

curl -X GET https://api.zakeke.com/v3/designs/seller?pageSize=20&onlyForCustomers=true&queryText=Christmas \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

10. Total number of designs

Using this Endpoint you will be able to get the total number of designs created in your account

Request

GET https://api.zakekec.com/v1/designs/seller/occurrences

The endpoint accepts the following parameters in query strings to filter the designs to count.

Parameter	Data type	Description
draft	`boolean`	To count the designs saved as draft by the end users.
customerCode	`string`	To count the designs created by a specific customer.
onlyForCustomers	`boolean`	To count only the designs created by customers and not even those of simple visitors.
queryText	`string`	To count only the designs that has the specified text in the name or in the tags.

Response

The API call will return a long integer representing the number of designs that satisfy the request.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains number of designs that satisfy the request.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No design was found that meets the conditions of the request.

Examples

Example 1 Count all the draft designs:

curl -X GET https://api.zakekec.com/v1/designs/seller/occurrences?draft=true \
     -H "Authorization: Bearer <Access-Token>"

Example 2 Count the draft designs of a specific customer:

curl -X GET https://api.zakekec.com/v1/designs/seller/occurrences?draft=true&customerCode=wq23r9123 \
     -H "Authorization: Bearer <Access-Token>"

Example 3 Count the customer designs that have the text "Christmas" in the name (or tags)

curl -X GET https://api.zakekec.com/v1/designs/seller/occurrences?onlyForCustomers=true&queryText=Christmas \
     -H "Authorization: Bearer <Access-Token>"

11. Customers who created designs

The endpoint allows you to get the list of customers who have created designs with Zakeke.

Request

GET https://api.zakekec.com/v1/designs/seller/customers

The endpoint accepts the following parameters in query strings to filter the designs.

Parameter	Data type	Description
onlyDraftDesigns	`boolean`	To get only customers who have saved draft designs.

Response

The API call returns a JSON array with the list of customer codes relating to the designs created.

[
  "1243rfwe29ioqwfwqi",
  "avf123sskppo2efef2",
  "wefiiu89234jncjjj2",
  "wefwergmfovom00981",
  // ...
  // ...
]

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The body contains the list of customer codes for the design created.
401	Unauthorized	Unauthorized user. Check the token used for the call.
403	Forbidden	Unauthenticated user. Check the token used for the call.
404	Not Found	No design was found that meets the conditions of the request.

Examples

Example 1 Codes of customers who created draft designs.

curl -X GET https://api.zakekec.com/v1/designs/seller/customers?onlyDraftDesigns=true \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <Access-Token>"

Designs API

Summary​

1. Overview​

2. List of endpoints​

3. Error codes​

4. Retrieve a design by ID​

Request​

Response​

HTTP Response Codes​

5. Duplicate a design​

Request​

Response​

HTTP Response Codes​

6. Retrieve design items​

Request​

Response​

HTTP Response Codes​

7. Retrieve the ZIP with all print-ready files​

Request​

Response​

HTTP Response Codes​

8. Retrieve print-ready file with a given file format​

Request​

Response​

HTTP Response Codes​

9. Retrieve all the designs​

Request​

Response​

HTTP Response Codes​

Examples​

10. Total number of designs​

Request​

Response​

HTTP Response Codes​

Examples​

11. Customers who created designs​

Request​

Response​

HTTP Response Codes​

Examples​

Summary

1. Overview

2. List of endpoints

3. Error codes

4. Retrieve a design by ID

Request

Response

HTTP Response Codes

5. Duplicate a design

Request

Response

HTTP Response Codes

6. Retrieve design items

Request

Response

HTTP Response Codes

7. Retrieve the ZIP with all print-ready files

Request

Response

HTTP Response Codes

8. Retrieve print-ready file with a given file format

Request

Response

HTTP Response Codes

9. Retrieve all the designs

Request

Response

HTTP Response Codes

Examples

10. Total number of designs

Request

Response

HTTP Response Codes

Examples

11. Customers who created designs

Request

Response

HTTP Response Codes

Examples