Managing templates

The template endpoints allow you to create, update and delete templates in Colorlab.

These endpoint help you to automatically synchronize externally managed template data, such as a Product Information Management system or a custom database. This integration eliminates the need without the need to manually create and update templates in the Colorlab Console.

Integrating these endpoints in your software or service guarantee that new templates and updates are immediately available in Colorlab.

Uploading media

Media objects

Templates use media objects (e.g. a JPG or PNG file) to display the product or reference default media objects when opening the app (e.g. a default picture shown).

To create an template, use the POST http method to send a JSON payload to the following endpoint:

1
POST https://api.colorlab.io/v1/media?type={mediaType}

The endpoint requires a query parameter type which is equal to templates or pictures. This parameter is used to indicate where the media object will be used.

The POST endpoint accepts a multipart/form-data body that accepts following keys:

Example response payload

1
2
3
4
5
6
7
8
9
10
11
{
"_id": "media-id-here",
"meta": {
"width": 1000,
"height": 1000
},
"mimetype": "image/jpeg",
"name": "media-id-here",
"originalname": "my-image.jpg",
"size": 12345
}

The _id property can be used to reference media objects in templates.

Generating the signature

Create a verification string containing this data:
shopId

Now use your API secret to compute a sha256 HMAC signature. You can test the output using online generators like https://www.freeformatter.com/hmac-generator.html.

Use the resulting value in the X-Colorlab-Api-Signature header when sending requests to the above API endpoints.

Creating a template

To create an template, use the POST http method to send a JSON payload to the following endpoint:

1
POST https://api.colorlab.io/v1/template

Example payload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
{
"name": "iPhone XS case",
"productId": "SKU_456",
"views": [
{
"name": {
"en": "Front"
},
"active": true,
"weight": 0,
"template": "media-id-here",
"areas": [
{
"id":"area-1",
"name": "Area 1",
"x": 0,
"y": 0,
"width": 100,
"height": 100
},
{
"id":"area-2",
"name": "Area 2",
"x": 100,
"y": 100,
"width": 100,
"height": 100
}
],
"fields": [
{
"name": {
"en": "Your picture"
},
"type": "picture",
"value": "default-media-id-here",
"draggable": true,
"resizable": true,
"rotatable": true,
"scale": 1,
"positionX": 950,
"positionY": 949,
"rotation": 0,
"selectable": true,
"required": false,
"active": false,
"weight": 3,
"export": true,
"scaleArea": "area-1",
"area": "area-1",
"autoResize": "fill"
},
{
"name": {
"en": "Your text"
},
"type": "text",
"value": {
"en": "Initial text shown"
},
"multiline": true,
"align": "center",
"maxCharacters": 0,
"draggable": true,
"resizable": true,
"rotatable": true,
"readOnly": false,
"fontsize": 171,
"minFontsize": 171,
"maxFontsize": 713,
"bold": false,
"italic": false,
"allColors": true,
"positionX": 950,
"positionY": 949,
"rotation": 0,
"selectable": true,
"required": false,
"active": false,
"weight": 2,
"export": true,
"colors": [
{
"default": true,
"color": "#000000",
"name": {
"en": "Black"
}
},
{
"default": false,
"color": "#ffffff",
"name": {
"en": "White"
}
},
{
"default": false,
"color": "#fe5a49",
"name": {
"en": "Tomato Red"
}
},
{
"default": false,
"color": "#40bdff",
"name": {
"en": "Sky Blue"
}
},
{
"default": false,
"color": "#ffe459",
"name": {
"en": "Lemon Yellow"
}
},
{
"default": false,
"color": "#81cc82",
"name": {
"en": "Avocado Green"
}
}
],
"area": "area-2"
},
{
"name": {
"en": "Select artwork"
},
"type": "illustration",
"draggable": true,
"resizable": true,
"rotatable": true,
"scale": 1,
"positionX": 950,
"positionY": 949,
"rotation": 0,
"selectable": true,
"required": false,
"active": false,
"weight": 1,
"export": true
},
{
"name": {
"en": "Background color"
},
"type": "background",
"allColors": true,
"allowTransparent": true,
"selectable": true,
"required": false,
"active": true,
"weight": 0,
"export": true,
"colors": [
{
"default": false,
"color": "#000000",
"name": {
"en": "Black"
}
},
{
"default": false,
"color": "#ffffff",
"name": {
"en": "White"
}
}
]
}
],
"export": {
"type": "pdf",
"dpi": 300,
"filename": "[id]-[title]",
"areaType": "template",
"exportTemplate": true
}
}
]
}

Template properties

Property Description
name Name of the template which will be displayed in the Console.
productId Your reference to the template. This will be used to update the template later on. Must be unique per shop.
views Array of views in the template (e.g. Front and Back). See View properties for each object in this array.

View properties

Property Description
name An object with the name of the view which will be displayed in the app. Provide a translation for each language activated in your account.
active Defines which view will be active by default in the app. Only 1 view in the array of views can be active.
weight The order of the views as displayed in the app. Ascending number, starting from 0. The lowest number will be displayed first.
template The ID of the media object to display in the app
width The width of the template in pixels
height The height of the template in pixels
fields Array of elements to be displayed in the app for this view. See Element properties for each object in this array.
export See view export properties below.
areas See view areas properties below.

View export properties

Sets the default export properties for the view.

Property Description
type Could be pdf, png or pdf-simple (PNG-based PDF).
dpi The export dpi.
filename Default filename is [id]-[title]. You can use following tokens: [id] configuration id, [date] date in yyyy-mm-dd format, [title] configuration name, [product] template id`
areaType Defines the export dimensions type. Could be template, custom or area.
area This property is required when areaType is area. A valid area id must be given here.
exportTemplate Boolean defining if the export should contain the template.
x Required when areaType is custom. Defines the export x position.
y Required when areaType is custom. Defines the export y position.
width Required when areaType is custom. Defines the export width.
height Required when areaType is custom. Defines the export height.

View areas properties

Sets the default export properties for the view.

Property Description
id Unique id for this area.
name The human readable name for this area.
x X position of the area.
y Y position of the area.
width Area width.
height Area height.

Element properties

Each element has these properties. Each element type has additional properties, unique to this element type. These properties are displayed later in this page.

Property Description
name An object with the name of the element which will be displayed in the app. Provide a translation for each language activated in your account.
selectable Defines if the user is able to edit this element.
required Marks an element required, which will trigger a message in the app if the end user doesn’t have a value selected for this element.
active Defines which element will be active by default in the view. Only 1 element in the array of elements can be active.
weight The order of the elements as displayed in the app. Ascending number, starting from 0. The lowest number will be displayed below all other elements, just like layers in Photoshop.
export Defines if the element should be included in customization exports.
type Defines the element type. This can be text, picture, illustration or background.
area Define the area this element is visible in. Only a valid area id from the areas property is allowed.

Element (text) properties

Following additional properties are required for text elements.

Property Description
multiline Allow the user to enter multiple lines
value An object with the default text value which will initially be displayed in the app. Provide a translation for each language activated in your account.
align Default alignment of the text if multiple lines are used (left, center (default) or right)
maxCharacters Defines the maximum amount of characters that can be entered. Set to 0 to allow unlimited characters.
draggable Allows the user to change the position of the element.
resizable Allows the user to change the size of the element.
rotatable Allows the user to rotate the element.
minFontsize The minimum font size of the text.
maxFontsize The maximum font size of the text.
bold Boolean indicating if the bold version of the font should be used.
italic Boolean indicating if the italic version of the font should be used. When combined with bold, the boldItalic version of the font is used
allColors Allows the user to add and use all colors.
colors An array of the colors displayed in the app. Each color is defined as an object containing a name (object with translations for each language in your account), default (one color can be the default in the array) and the color (a hex string defining the color to be used).
positionX The horizontal position of the text in pixels. Calculated from the top left corner of the view.
positionY The vertical position of the text in pixels. Calculated from the top left corner of the view.
rotation The initial rotation of the element (0 - 360).

Element (picture) properties

Following additional properties are required for picture elements.

Property Description
value The ID of the Media document which is used as default value when opening the app.
draggable Allows the user to change the position of the element.
resizable Allows the user to change the size of the element.
rotatable Allows the user to rotate the element.
scale The initial scale of the picture (if a value is set)
positionX The horizontal position of the picture in pixels. Calculated from the top left corner of the view.
positionY The vertical position of the picture in pixels. Calculated from the top left corner of the view.
rotation The initial rotation of the element (0 - 360).
scaleArea Define the area this element is scaled to. Only a valid area from the areas property is allowed.
autoResize Resize options how the picture should behave inside an area. Allowed values are none, fill and fit

Element (illustration) properties

Following additional properties are required for artwork elements (type illustration).

Property Description
value The ID of the Media document which is used as default value when opening the app.
draggable Allows the user to change the position of the element.
resizable Allows the user to change the size of the element.
rotatable Allows the user to rotate the element.
scale The initial scale of the picture (if a value is set)
positionX The horizontal position of the picture in pixels. Calculated from the top left corner of the view.
positionY The vertical position of the picture in pixels. Calculated from the top left corner of the view.
rotation The initial rotation of the element (0 - 360).
scaleArea Define the area this element is scaled to. Only a valid area from the areas property is allowed.
autoResize Resize options how the picture should behave inside an area. Allowed values are none, fill and fit

Element (background) properties

Following additional properties are required for artwork elements (type illustration).

Property Description
allColors Allows the user to add and use all colors.
colors An array of the colors displayed in the app. Each color is defined as an object containing a name (object with translations for each language in your account), default (one color can be the default in the array) and the color (a hex string defining the color to be used).
allowTransparant Allows the user to select no color (transparent).

Updating a template

To update a template, use the POST http method to send the JSON payload to the following endpoint:

1
POST https://api.colorlab.io/v1/template/:id

And replace :id with the productId property that was used used when creating the template. The endpoint uses the exact same JSON payload as the create endpoint.

Deleting a template

To delete a template, use the DELETE http method to the following endpoint:

1
DELETE https://api.colorlab.io/v1/template/:id

Important: created customizations based on this template won't be deleted. Referenced media documents are deleted automatically.

Generating the signature

Create a verification string containing this data:
shopId + productId

Example: with a shopIdequal to 555 and a productId equal to SKU_456, the verification string is:

1
555SKU_456

Now use your API secret to compute a sha256 HMAC signature. You can test the output using online generators like https://www.freeformatter.com/hmac-generator.html.

Use the resulting value in the X-Colorlab-Api-Signature header when sending requests to the above API endpoints.