Compositions API

1. Overview

In the context of the Zakeke API, a "composition" means the set of attributes and their selected options that identify the product configuration created by the customer through the 3D configurator.

For detailed insights into these terms, refer to the documentation here.

The Compositions API is a collection of endpoints designed to access composition information.

2. List of endpoints

The following are the enpoints available for the Compositions 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	`/v2/compositions/{compositionID}/{quantity}`	Retrieves information about a composition given its ID.
POST	`/v2/compositions/{id}/cartinfo`	Get data necessary to add a configured product to the shopping cart.
GET	`/v2/compositions/seller`	Returns all the designs created by your customers.
GET	`/v2/compositions/seller/customers`	Returns a list of customer codes who have created compositions.

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.

4. Retrieve a composition by ID

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

Request

GET https://api.zakeke.com/v2/compositions/{compositionID}/{quantity}

The compositionID is the unique composition identifier. Zakeke generates this identifier when a configured 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.

Response

The API call returns a JSON with the following structure:

{
  "compositionID": "string",
  "name": "string",
  "tempPreviewImageUrl": "string",
  "price": 0,
  "designID": "string",
  "items": [
    {
      "itemGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attributeGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attributeType": "string",
      "attributeCode": "string",
      "attributeName": "string",
      "selectedOptionGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "selectedOptionCode": "string",
      "selectedOptionName": "string",
      "selectedValue": "string"
    }
  ],
  "previewFiles": [
    {
      "url": "string",
      "cameraName": "string"
    }
  ]
}

where:

Property	Data type	Description
compositionID	`string`	Unique configuration identifier.
name	`string`	Name assigned to the composition, if any.
tempPreviewImageUrl	`string`	URL of the default preview image representing the 3D configuration.
price	`money`	Total mark-up price given by the unit price multiplied by the quantity.
designID	`string`	Unique identifier of the design applied to the configured product, if any.
items	`array`	List of configuration attributes with the respective option selected.
previewFiles	`array`	List of preview images taken at different angles.

The items property is an array of objects, each of which represents the selected value for an attribute and has the following structure:

{
  "itemGuid": "string",
  "attributeGuid": "string",
  "attributeType": "string",
  "attributeCode": "string",
  "attributeName": "string",
  "selectedOptionGuid": "string",
  "selectedOptionCode": "string",
  "selectedOptionName": "string",
  "selectedValue": "string"
}

where:

Property	Data type	Description
itemGuid	`string`	Unique item identifier within Zakeke.
attributeGuid	`string`	Unique attribute identifier within Zakeke.
attributeType	`string`	The attribute type. Zakeke currently only supports options list attributes, but in the future it may also support open-valued attributes.
attributeCode	`string`	The code of the attribute in the ecommerce system.
attributeName	`string`	The name of the attribute.
selectedOptionGuid	`string`	Unique option identifier within Zakeke.
selectedOptionCode	`string`	The code of the option in the ecommerce system.
selectedOptionName	`string`	The name of the option.
selectedValue	`string`	For an option list attribute (the only one currently supported), the selected value is the identifier of one of the options listed for the attribute. When open value attributes will be available, the `selectedValue` property will report the actual user-specified value.

The previewFiles property is an array of objects, each of which represents a preview image generated with a given camera and has the following structure:

{
  "url": "string",
  "cameraName": "string"
}

where the url property is the preview image url and camperaName is name of the camera within the 3D scene that captured the shooting scene.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the searched composition.
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 composition with the specified ID was not found.

5. Get the necessary data to add a configured product to the shopping cart

Using this endpoint it is possible to obtain the data necessary to add the product to the cart, such as the mark-up price due to the product configuration, the options chosen for the attributes and any design for customization.

Request

GET https://api.zakeke.com/v2/compositions/{id}/cartinfo

The id is the unique composition identifier.

Response

The API call returns a JSON with the following structure:

{
  "preview": "string",
  "price": 0,
  "designID": "string",
  "items": [
    {
      "itemGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attributeGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attributeType": "string",
      "attributeCode": "string",
      "attributeName": "string",
      "selectedOptionGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "selectedOptionCode": "string",
      "selectedOptionName": "string",
      "selectedValue": "string"
    }
  ]
}

For a description of the object properties see the section Retrieve a composition by ID.

HTTP Response Codes

Code	Name	Description
200	OK	API Call completed successfully. The response body contains the requested info.
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 composition was not found.

6. Retrieve all the compositions

This endpoint returns all the compositions created by your customers.

Request

GET https://api.zakeke.com/v2/compositions/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 compositions.

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
compositionID	`string`	To get a single composition.
draft	`boolean`	To get the compositions saved as draft by the end users.
customerCode	`string`	To get the compositions created by a specific customer.
onlyForCustomers	`boolean`	To get only the compositions created by customers and not even those of simple visitors.
queryText	`string`	To get only the compositions 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",
  "compositions": [
    {
      "compositionID": "string",
      "name": "string",
      "tempPreviewImageUrl": "string",
      "modelCode": "string",
      "modelID": 0
    }
  ]
}

where the compositions property is an array of objects each of which reports summary information about a composition. Specifically, the following properties are reported for each composition:

Property	Data type	Description
compositionID	`string`	Unique configuration identifier.
name	`string`	Name assigned to the composition, if any.
tempPreviewImageUrl	`string`	URL of the default preview image representing the 3D configuration.
modelCode	`string`	Identification code of the configured product in the ecommerce.
modelID	`integer`	Unique product identifier in Zakeke.

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/v2/compositions/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\":.......",
  "compositions": [
    {
      "compositionID": "000-RE1olDzbT234viB6D11a10",
      // ...
    },
    {
      "compositionID": "000-ff2348ba123eecd1411234",
      // ...
    },
    {
      "compositionID": "000-ab981184331123498awfwe",
      // ...
    },
    // ...
    // ...
  ]
}

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

curl -X GET https://api.zakeke.com/v2/compositions/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 composition 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 composition was found that meets the conditions of the request.

Examples

Example 1 Get all the draft compositions:

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

Example 2 Get the draft compositions of a specific customer:

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

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

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

7. Customers who created compositions

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

Request

GET https://api.zakekec.com/v2/compositions/seller/customers

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

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

Response

The API call returns a JSON array with the list of customer codes relating to the compositions 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 compositions 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 composition was found that meets the conditions of the request.

Examples

Example 1 Codes of customers who created draft compositions.

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

Compositions API

1. Overview​

2. List of endpoints​

3. Error codes​

4. Retrieve a composition by ID​

Request​

Response​

HTTP Response Codes​

5. Get the necessary data to add a configured product to the shopping cart​

Request​

Response​

HTTP Response Codes​

6. Retrieve all the compositions​

Request​

Response​

HTTP Response Codes​

Examples​

7. Customers who created compositions​

Request​

Response​

HTTP Response Codes​

Examples​

1. Overview

2. List of endpoints

3. Error codes

4. Retrieve a composition by ID

Request

Response

HTTP Response Codes

5. Get the necessary data to add a configured product to the shopping cart

Request

Response

HTTP Response Codes

6. Retrieve all the compositions

Request

Response

HTTP Response Codes

Examples

7. Customers who created compositions

Request

Response

HTTP Response Codes

Examples