Support for

TemplateCloud API Guide

John Valentine
by John Valentine 4 years ago
 
This is for you if you're looking for a way to integrate TemplateCloud's extensive library of templates, powerful customisation tools, and printing services* into your own website.

Introduction

What is TemplateCloud API? What is TemplateCloud API?

Getting your App Approved Getting your App Approved

API reference: documentation style API reference: documentation style

TemplateCloud API Process Guide TemplateCloud API Process Guide

Development and Production: Access and Security Development and Production: Access and Security

API Requests and Responses

TCAPI: Format for requests TCAPI: Format for requests

Template Discovery

TCAPI: tag type TCAPI: tag type

TCAPI: tag group TCAPI: tag group

TCAPI: template size TCAPI: template size

TCAPI: templates TCAPI: templates

Template editing, data, and file assets

TCAPI: Template Editing and File Assets TCAPI: Template Editing and File Assets

Integration

TCAPI: Integration TCAPI: Integration

TCAPI: Embedding the editor TCAPI: Embedding the editor

TCAPI: Mapping your products TCAPI: Mapping your products

TCAPI: Choosing a template TCAPI: Choosing a template

TCAPI: Populating or customizing a template TCAPI: Populating or customizing a template

TCAPI: Buying a PDF TCAPI: Buying a PDF

TCAPI: PHP platform example TCAPI: PHP platform example

FAQ

TCAPI: FAQs TCAPI: FAQs

TemplateCloud API Guide

This is for you if you're looking for a way to integrate TemplateCloud's extensive library of templates, powerful customisation tools, and printing services* into your own website.

What is TemplateCloud API?

TCAPI has three services

  • Template listings
    Display available TemplateCloud templates on your own website

  • Template editor
    Present an editor where your customers customize and buy their chosen designs; and

  • PDF rendering
    When they have checked out from your website, you ask TemplateCloud for the PDF.

What you can build

Here's a wireframe sketch of a typical API-using website. This page chooses a template:

Here you may:

  • Filter (by keyword, industry type, style, logo options, event, product types, size, and colour);
  • Sort results;
  • Display Template Listing; and
  • Edit the Design, shown below:

These sites are currently using TCAPI

Getting your App Approved

Before you can use the TemplateCloud API, you'll need:

  • TemplateCloud developer account, and
  • a TemplateCloud API key.

How to start

  1. Apply at developer.templatecloud.com
  2. Your application will then be processed for approval.
  3. Our welcome pack contains everything you need!

You can then find your API credentials at https://developer.templatecloud.com/admin/access_details

API reference: documentation style

Conventions

Our conventions for formatting our API documentation can have the following elements:

  • Title: what an API call does.
  • Path: the HTTP URL's location, including ids.
  • Description: a bit more detail.
  • Parameters: a table of parameters, their value spec and effects.
  • Request example.
  • Response example.
  • Response Items: a table of possible items found in the response.
  • Relations: how data is shared between objects and methods.

Appearance

Code or data files are boxes and labelled with their type, e.g.

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "tag_types": [
        {
            "id": "1",
            "name": "Industry Types"
        },
        {
            "id": "2",
            "name": "Client"
        },
        etc...
    ]
}

Aside from standard code highlighting, we style as follows:

  • keywords or reserved words
    also used to identify nouns in the API path.
  • literal strings
    identify values for variables, or literally-entered text.
  • variables
    identify a variable or parameter name.
  • arguments
    identify a place where an argument should be inserted.
  • comments
  • annotations (comments set apart from the code)

TemplateCloud API Process Guide

(click for bigger image)

Development and Production: Access and Security

Your website and its data

You'll need to replicate some data structures on your website, which correspond with some of those in the TCAPI. At the very least, you'll be storing id fields from TemplateCloud, and temporarily holding lists of objects when processing the results of queries.

See also:

  • Template Discovery
  • Template Editing and File Assets

Separating development from production

We have provided a developers' sandbox, to help you avoid incurring charges and writing to live data while you're testing.

Environment API server URL
Development http://api.templatecloud.com/sandbox/...
Production https://api.templatecloud.com/v1/...

Your API Key

Guard your API Key

Your API Key allows your systems to access TemplateCloud. If someone else has your key, they too can access the same services, posing as your business.

It is important that you take reasonable measures to ensure that you do not publish your API Key:

  1. Use SSL for API calls — https:// instead of http://

  2. If you experience problems due to unauthorised sharing of your API Key, then request a new API Key, close the security hole, and update your services to use your new API Key.

  3. Do not hard-code your API Key in every request call; instead use a variable containing the key.

    • Specify your API Key once, in a file on a private part of your server, and include it (by reference) in your framework or page code.

  4. Do not allow your web server to show code that might display the API Key.

    • Do not use debug code in the production environment, which might reveal the contents of variables that contain the API Key.

    • Handle errors correctly, so they do not reveal the code that caused the error. If you want traceability, then handle and privately log the error, and optionally inform the user there was a problem along with a reference number that can be used for support.

    • Try to use syntax checkers and syntax-highlighting code editors, and separate the processing code from the presentation code. This helps to avoid serving code into your HTML pages.

  5. Do not serve scripts or web pages that contain the API Key, i.e. do not design your systems so that your clients' web browsers are making TCAPI requests directly. Instead, your servers should take minimal requests from your client's pages, and then your servers issue the TCAPI requests to the TemplateCloud API on your clients' behalf.

  6. Do not inject unprocessed user-supplied strings into expressions, e.g. do not use something like

    PHP
    $thatWorked = 'Insecure handy calculator: ' . eval( $userInput );

TCAPI: Format for requests

Sandbox and documentation site, to help you test

At https://developer.templatecloud.com/docs, we provide live documentation for each of the the API requests, along with convenient entry forms where you can specify values for parameters to test your queries.

Request format

Use standard HTTP requests to communicate with the API.

GET requests are used to read data from TemplateCloud using the API;

PUT and POST requests try to write information to TemplateCloud using the API.

The following example is a request to the API’s sandbox handler, which returns a list of tag types:

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json

You have the option of specifying the response format using the format parameter. Allowed values are json or xml, the default being xml.

You’ll need your own user_key (see Getting your App Approved).

Response format

Error (response code 404)

HTTP response (JSON)
{
  "status": "error",
  "message": "Template not found"
}

Success (response code 200) 

Where one record is returned, it is presented as a lone object, e.g.

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/1?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "tag_type": {
        "id": "1",
        "name": "Industry Types"
    }
}

Where more than one record is returned, the top-level object is an array (having a plural name tag_types), containing child tag type objects. 

e.g. here are the requests and responses for tag types

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "tag_types": [
        {
            "id": "1",
            "name": "Industry Types"
        },
        {
            "id": "2",
            "name": "Client"
        },
        etc...
    ]
}

XML format

The XML version is below. Note that the above JSON does not encapsulate the array's items as named objects, but the XML necessarily does: 

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=xml
HTTP response (XML)
<response status="ok">
    <tag_types>
        <tag_type>
            <id>1</id>
            <name>Industry Types</name>
        </tag_type>
        <tag_type>
            <id>2</id>
            <name>Client</name>
        </tag_type>
etc...
    </tag_types>
</response>    

TCAPI: tag type

Retrieves a tag type, or lists tag types.

Request

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml

Request a tag type by id

Syntax
/tag_types/<tagtype_id>/

After tag_types/, specify the id of the tag type like this:

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/2/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json

Request a list of tag types

Syntax
/tag_types/

Retrieves all tag types:

HTTP request
GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json

Response

HTTP response (JSON)
{
    "tag_types": [
        {
            "id": "1",
            "name": "Industry Types"
        },
        {
            "id": "2",
            "name": "Client"
        },
        etc...
    ]
}

If one result is returned,

HTTP response (JSON)
{
    "tag_type":
        {
            "id": "1",
            "name": "Industry Types"
        }
}

Relations

References to tag types

  • tag type in templatetemplate.tag.tagtype_id
  • tag type in tag grouptaggroup.tagtype_id

References from tag types

  • Use the tag_type.id to get tag groups having that tag type:
    /tag_groups/?…type_id=<tagtype_id>

TCAPI: tag group

Retrieves a tag group, or lists tag groups.

Request tag group by id

Syntax
/tag_groups/<taggroup_id>/

Retrieves a tag group.

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml
include List more data containers. Possible value: tag_type.

After /tag_groups/, specify the id of the tag group like this:

HTTP request
GET http://api.templatecloud.com/sandbox/tag_groups/2/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "tag_group": {
        "id": "2",
        "name": "Easter",
        "tagtype_id": "8",
    }
}

Request list of tag groups

Syntax
/tag_groups/

Retrieves all tag groups, using optional filters.

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml
type_id One tag type id (optional)
include List more data containers. Possible value: tag_type.
HTTP request
GET http://api.templatecloud.com/sandbox/tag_groups/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
   "tag_groups": [
      {
         "id": "1",
         "name": "Other Events",
         "tagtype_id": "8"
      },
      {
         "id": "2",
         "name": "Easter",
         "tagtype_id": "8"
      },
         ...
}

Relations

References to tag groups

  • Use tag_type.id to find tag groups having that tag type:

    Syntax
    /tag_groups/...?type_id=<tagtype_id>
  • Use template.tag.taggroup_id to get a tag group from a template:

    Syntax
    /tag_groups/<taggroup_id>/

References from tag groups

  • Use tag_group.id to find templates having tags belonging to that tag group:

    Syntax
    /templates/?…filter_options=0&type_id=<tagtype_id>
  • Use tag_group.id to find template filters for templates having tags in that tag group:

    Syntax
    /templates/?…filter_options=1&type_id=<tagtype_id>
  • Use tag_group.tagtype_id to get a single tag type:

    Syntax
    /tag_types/<tagtype_id>/

Self-references in tag groups

  • Use tag_group.id to get a single tag group:

    Syntax
    /tag_groups/<taggroup_id>/
  • Use tag_group.tagtype_id to find tag groups having that tag type:

    Syntax
    /tag_groups/?type_id=<taggroup_id>

Other references using tag groups

  • Use template.tag.taggroup_id to find all templates having that tag group:

    Syntax
    /templates/?group_id=<taggroup_id>

TCAPI: template size

Request template size by id

Syntax
/template_sizes/<templatesize_id>/

Retrieves a template size. Note that we do not publish these IDs in the API, so this is of limited use. Instead, just retrieve all template sizes.

Request list of template sizes

Syntax
/template_sizes/

Retrieves all available template sizes.

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml
templatesize_id One template size id (optional; deprecated)
units imperial or metric (optional).
HTTP request
GET http://api.templatecloud.com/sandbox/template_sizes/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "template_sizes" : [
        {
            "code" : "A4",
            "name" : "A4",
            "width" : "210.0000",
            "height" : "297.0000",
            "bleed" : "1.5000",
            "units" : "mm"
        }, {
            "code" : "A5",
            "name" : "A5",
            "width" : "148.0000",
            "height" : "210.0000",
            "bleed" : "1.5000",
            "units" : "mm"
        },
         ...
    ]
}

Relations

References to template sizes

  • Use template.size.code to find templates having that template size, when include contains size.

    Syntax
    /templates/?...include=size
  • Hidden: The unpublished template_size.id can be used as a template size argument in the API call, to retrieve a single template size:

    Syntax
    /template_sizes/<templatesize_id>/

TCAPI: templates

Retrieves a template, or retrieves filters for this request.

Request template by id

Syntax
/templates/<template_id>/

Retrieves a template.

HTTP request
GET http://api.templatecloud.com/sandbox/templates/12345/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json

Request list of templates

Syntax
/templates/

Retrieves all available templates, using (many) optional filters.

  • If more than one template is returned, then the response is a templates object containing many template items.

  • You can include your own templates using include_my_templates=true or only_my_templates=true and refine that list using workgroup, category and customer filters.

Getting available criteria for filters

If filter_options=0, the response contains templates that match the specified criteria. 

If filter_options=1, the response contains the allowed values of filter criteria, i.e. valid tags or other parameter values (see below).

Where filter criteria are not specified, those aspects are disregarded in the search.

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml
Search Criteria
template_id One template ID. Optional; omit to show all available templates.
include_my_templates

When true, 'private' templates assigned to your workgroup, category, or customer, are added to the public templates. If you specify more than one parameter (of workgroupcategorycustomer),  results are merged.

Default: false.

Adding workgroup=TEMP&category=AAC&customer=TCINST filters only the private templates. Filters are optional.

only_my_templates

When true, only 'private' templates assigned to your workgroup, category, or customer, are returned.  If you specify more than one parameter (of workgroupcategorycustomer),  results are merged.

Default: false.

Optional filters: workgroup=TEMP&category=AAC​&customer=TCINST​.

keywords Matches to tag.name. Optional.
keywords Matches to tag.name. Optional.
collection_id

Matches to a collection. Optional.

Equivalent to searching for a tag of tag type 7 ('collections').

tag_groups tag group IDs (optional). Multiple items allowed, comma-separated.
pages

If required, a value to match template.colour.pages (the number of ‘sides’ or ‘PDF pages’ in a document).

Typical values: 1 or 2.

sizes If specified, return only templates having matching template.size.code or template.size.id. Multiple items allowed, comma-separated.
colour If specified, return only templates having colour tag of matching colour, i.e. colour = template.tag.colour (hexadecimal colour). Specify the colour as 3-byte hexadecimal, RGB ordering, e.g. 0568b4.
designer_id If specified, return only templates designed by this designer.
exclusive_tag_types

0 or 1.

Default value 0: will only list template results that have a match on ALL tag groups you’ve search for.

Override value 1: will list ANY template result that matches at least one of the tag groups you’ve searched for.

Paging and ordering of template results
limit

For a paged response, specify this as the number of results to return per page. Optional.

Allowed range: 1-100.
Default values: &limit=20&page=0.
Typical value: 12.

page

Set the page index of results to return, starting with page = 0. Optional;

Default values: &limit=20&page=0.

sort_key

Allowed values: rank, price, or date.

Default: rank.

sort_order

Allowed values: desc or asc.

Defaults:
asc for sort_key = rank;
desc for sort_key = price|date.

Inclusion of metadata
include

Additional element metadata items to include in each template object. Multiple items allowed, comma-separated. See below.

All options: tags,size,colour,tag_group,images

filter_options 0 or 1. When 1, the response inludes filters rather than templates. See filteroptions=0, below.

Extra response items for include arguments

When (comma-separated) arguments are supplied for the include parameter, extra items are included in the response for each template item. Below is an example of each extra item.

include=size

HTTP response (JSON)
"size": {
    "code": "BC",
    "name": "Business Card",
    "width": "85.0000",
    "height": "55.0000",
    "bleed": "1.5000",
    "units": "mm"
}

include=colour

HTTP response (JSON)
"colour": {
    "coloursfront": 4,
    "coloursreverse": 4,
    "pages": 2
}

include=tags

HTTP response (JSON)
"tags": [
    {
        "id": "214",
        "name": "Business Cards",
        "sales": "16491",
        "taggroup_id": "60",
        "tagtype_id": "3"
    },
    /* more tags */
    ...
]

include=tag_group

HTTP response (JSON)
"tags": [
    {
        ...
        "tag_group": {
            "id": "60",
            "name": "Business Cards",
            "tagtype_id": "3"
        }
    },
    /* more tags */
    ...
]

include=images

HTTP response (JSON)
"images": [
    {
        "0": "http://www.templatecloud.com/api/...",
        "1": "http://www.templatecloud.com/api/...",
        "_attrs": {
            "name": "small"
            "size_code": "S"
        }
    },
    /* more images */
    ...
]

filter_options

filter_options=0

The request returns the matching templates.

HTTP request
GET http://api.templatecloud.com/sandbox/templates/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json&include=tags%2Csize%2Ccolour%2Ctags%2Ctag_group%2Cimages&filter_options=0
&tag_groups=2
HTTP response (JSON)
{
 "templates": {
    "0": {
     "id": "5924",
     "name": "Crunchy Cabbages Business Card ",
     "views": "102",
     "date_added": "2011-10-04 15:48:18",
     "designrank": "110",
     "allow_fotolia_library": true, 
     "allow_object_deletion": true, 
     "designed_by": "Norma Liza",
     "designer_id": "693971",
     "price": "20.00",
     "cost_price": "19.00",
     "click_charge": "0.00",
     "price_currency": "USD",
     "tags": [
         /* tag items */
     ],
    "size": {
        "code": "BC",
        "name": "Business Card",
        "width": "85.0000",
        "height": "55.0000",
        "bleed": "1.5000",
        "units": "mm"
     },
     "images": [
         /* image items */
     ],
     "colour": {
        "coloursfront": 4,
        "coloursreverse": 4,
        "pages": 2
     }
    },
    /* more template items */
    ...
}

filter_options=1

The request returns all of the filters (parameters and their values) available for the given search criteria. Note that this may not be used in combination with a template_id.

For keywords that were converted to tags, tags[].inferred=true. The remaining keywords are shown in keywords.refined[].

HTTP request
GET http://api.templatecloud.com/sandbox/templates/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json&filter_options=1
&tag_groups=2
HTTP response (JSON)
{
     "colours" : [
        {
            "colour" : "86200e",
            "name" : "Maroon"
        },
         ...
    ],
    "sizes" : [
        {
            "name" : "US Business Card (2x3in)",
            "code" : "USABC",
            "count" : "572",
            "selected" : false, 
            "area" : 7
        },
         ...
    ],
    "tags" : [
            {
            "title" : "Product Types",
            "types" : "PRODUCT",
            "tags" : [
                {
                    "name" : "Appointment Cards",
                    "code" : "194",
                    "count" : "42",
                    "selected" : false,
                    "inferred" : false
                }, 
                 ...
            ]
        }, {
            "title" : "Industry Types",
            "types" : "INDUSTRY",
            "tags" : [
                {
                    "name" : "Arts & Music",
                    "code" : "15",
                    "count" : "688",
                    "selected" : false,
                    "inferred" : true
                },
                 ...
            ]
        }, {
            "title" : "Styles",
            "types" : "STYLE",
            "tags" : [
                {
                    "name" : "Abstract & Illustrative",
                    "code" : "39",
                    "count" : "2406",
                    "selected" : false,
                    "inferred" : false
                }, 
                 ...
            ]
        }, 
         ...
    ]
    "keywords" : {
        "refined" : [
            "test"
        ],
    }
}

Relations

References to templates

  • Use template.tag.tagtype_id to get a tag type:

    Syntax
    /tag_types/<tagtype_id>/
  • Use template.tag.taggroup_id to get a tag group

    Syntax
    /tag_groups/<taggroup_id>/
  • Use template.tag.tag_group.tagtype_id to get a tag type

    Syntax
    /tag_types/<tagtype_id>/
  • Use template.size.name to get a template size

    Syntax
    /template_sizes/<template_size.name>/

Self-relations in /templates/

  • Use template.id to get the single template

    Syntax
    /templates/<template_id>/
  • Use template.tag.taggroup_id to get all templates having that tag group

    Syntax
    /templates/?group_id=<taggroup_id>
  • Use template.designer_id to get all templates by that designer

    Syntax
    /templates/?designer_id=<designer_id>

TCAPI: Template Editing and File Assets

Templates

Buy an InDesign file

Syntax
/templates/<template_id>/buyIndesignFile

Buys the InDesign file. This might incur a charge.

Fetch a bought InDesign file

Syntax
/templates/<template_id>/indesignFile

Fetches the template’s InDesign file, and returns it as an attachment.

Prepare a template for editing

Syntax
/templates/<template_id>/edit

Creates a template instance from a template.id. This instance can be edited by further API calls — see below.

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml
template_id One template id (required)
HTTP request
GET http://api.templatecloud.com/sandbox/templates/5277/edit?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "instance_id": "436935"
}

Template instances

Make a PDF

Syntax
/instances/<instance_id>/makePDF

Initiates the creation of a PDF file, and charges your account.

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml
queue 0 = generate and wait (synchronous)
1 = queue for later retrieval (asynchronous) – recommended!
skip_buy Some API consumers have a special permission enabled, to bypass the fees, which can be exercised using skip_buy=1. This option is disabled for the majority of API keys.
HTTP request
PUT http://api.templatecloud.com/sandbox/instances/50010/makePDF?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response (JSON)
{
    "status": "ok",
    "message": "PDF generation in progress",
    "job": "2152428"
}

No further edits of a template instance are possible after a call to makePDF; further edits must be made to a new template instance which may be created using call to /templates/<template_id>/edit

Poll/Fetch PDF

Syntax
/instances/<instance_id>/pdf

If the PDF is ready to download, the response to a GET request is a URL to the PDF file; otherwise it is an error notification.

It is advised that you poll /pdf with a HEAD request until the 200 response is returned; feed back the latest result to your web page via AJAX.

HTTP request
HEAD http://api.templatecloud.com/sandbox/instances/50010/pdf?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json
HTTP response 202 (JSON)
{
    "status": "error",
    "message": "PDF generation in progress." 
}
HTTP response 500 (JSON)
{
    "status": "error",
    "message": "PDF generation failed." 
}
HTTP response 404 (JSON)
{
    "status": "error",
    "message": "PDF not created (probably instance not found, or some unknown error)." 
}
HTTP response 200 (JSON)
{
    "status": "ok",
    "message": "PDF ready." 
}

After receiving a 200 response, the file can be retrieved using the equivalent GET request:

HTTP request
GET http://api.templatecloud.com/sandbox/instances/50010/pdf?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json

If the file is still available, the 200 response will contain a binary stream. If the file is not available, the response will be an XML/JSON notification of the error (as above).

TCAPI: Integration

TCAPI is platform-neutral because all communications with TemplateCloud are handled using simple requests and JSON/XML responses. You can develop your website using any competent framework.

Typically, your business will need a website that:

  • Presents and allows choice of a template, perhaps with a product in mind;

  • Presents the editor to work on an instance of the template;

  • Buys and downloads the customized PDF from TemplateCloud.

And of course

  • Handles the relationship with your customer: securely processes payments, shows progress, generates correspondence;

  • Controls manufacturing and logistics for your goods.

In this guide, we show how to choose a template and customize it using the editor.

 

TCAPI: Embedding the editor

This article explains how to embed the TemplateCloud editor on your website using some simple HTML & Javascript call.

You will also need to create an editor session to tell the editor which template or instance should be modified using an API call.

Note: this is a new simplified approach to opening the editor that means integrators no longer need to use the Create Instance API call.

Embedding the editor

Once you've got an sdsid, you can use this in your editor

To load the editor add this HTML

<html>
    <head>
        <title>Editor</title>
    </head>

    <body>
        <script src="https://dev.editor.w3p.com/js/editor.js"></script>

        <script type="text/javascript">
            TemplateEditor = new TemplateEditor({
                options: {
                    src: 'https://dev.editor.w3p.com',
                    height: '400px',
                    width: '600px'
                },
                params: {
                    sdsession: '<your sdsid>',
                    continue_url: '<your continue url>',
                    exit_url: '<your exit url>'
                }
            });
            TemplateEditor.init();
        </script>
    </body>
</html>
Options Description Required?
src

The url of the editor.
Dev editor url = https://dev.editor.w3p.com
Live editor url = https://editor.w3p.com

Yes
width Width of the editor
Eg 800px
No
height Height of the editor
Eg 400px
No
fullscreen either "true" or "false"
If "true" we'll load the editor fullscreen
No

 

Params Description Required?
sdsession Get this from the POST /sessions/create API call
See below for more details
Yes
continue_url The url to send people to after they press Next step in the editor Yes
exit_url The url to send people to after they press Quit & cancel in the editor Yes
locale

The language to open the editor in.
By default we use English.
Can also use:

tc_US for US.
tc_AU for Australia
tc_NZ for New Zealand
tc_IE for Ireland
tc_FR for France
tc_NL for Holland
tc_ES for Spain
tc_DE for Germany
tc_IT for Italy
tc_SE for Sweden
tc_PT for Portugal

No

 

Create session

 

Syntax
/sessions/create

Creates an editor session to open the editor.

  • Pass through a template id to start editing a new template.
  • Or pass through an instance id to re-edit a design that's already been started.

Works with both GET and POST API calls
POST only returns in XML, but requires no user_key

Parameter Description
format json or xml
Required option
template_id

One template ID.

Use this to get a SDSession to use when you open the editor.
Use a template_id to create a new instance and a new editor session.

instance_id

One instance ID.

Use this to get a SDSession to use when you open the editor.
Use a instance id to re-edit a design that's been opened in the editor by a customer at least 1 time before. Or to edit an instance you've made using the depreciated /templates/<template.id>/edit

Example request & responses

GET/POST template_id request
http://api.templatecloud.com/sandbox/sessions/create/?template_id=31081
GET/POST template_id response
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <message>SDSession created.</message>
  <sdsid>9cfcd1e8f11a5659752074ff33e17b9af869a34f</sdsid>
  <instance_id>2196719</instance_id>
  <template_id>31081</template_id>
</response>

 

GET/POST instance_id request
http://api.templatecloud.com/sandbox/sessions/create?instance_id=2196517
GET/POST instance_id response
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <message>SDSession created.</message>
  <sdsid>4cbde1cb9d1a81e397937a0576d654f03f824103</sdsid>
  <instance_id>2196517</instance_id>
  <template_id>31081</template_id>
</response>

TCAPI: Mapping your products

TemplateCloud templates are designed for an item of known size. It is expected that you have a list of products, each product having a size that can be matched to the templates in TemplateCloud.

So that you can present appropriate templates to your customers, you should select only the /template_sizes/ that have sizes corresponding to your products, i.e. matching template_size.width, template_size.height, and template_size.bleed.

TemplateCloud contains templates in landscape and portrait orientations, so there might be additional matches when height and width are swapped, or compare [min(h,w), max(h,w)] of template size and your product.

One approach would be to create a table defined like this:

Column Description
template_size_id ID from /template_sizes/, also used in template.size.
myProduct Your own product code.

With example data like this:

template_size_id myProduct
A4 StatPremA4
13rd StatPremCompl
A4 DistroLeafA4

Query your table to retrieve all template_size_id values, and feed them into the sizes parameter of the /templates/ API call.

TCAPI: Choosing a template

Approaches for selecting a template

The purpose of your website is to select a template and buy a PDF for your customer. Often your customer will not know which template they want, so your site will need to present some templates, to eventually reduce the selection to the one that the customer wants.

There are many approaches to achieving the objective of reducing your customer’s options to one.

  • Start with everything (possibly matching a user-initiated text search), and present filters to help narrow down the options.

  • Start with a few filters enabled,  to restrict your users to a subset of the total TemplateCloud library. Do this if:

    • Your site is ‘special interest’ or is dedicated to a business category, or you have a limited set of templates you want to sell (without the ability to remove those filters);

    • You want to inspire your users on a particular theme (where you make the filters available to switch back to the full collection).

  • Start with a suggestion of one template. Feature a design, or randomly choose from a small pool of designs, showing only one of them at a time. Your user then has the one template needed to (customise and) progress the order.

Getting a list of templates

TemplateCloud contains thousands of templates, tagged to enable their discovery. Each criterion (size, colour, industry type, number of pages, etc) is a tag type having several possible tags within that type.

If presented with an untargeted list of thousands of templates, it’s unlikely that your customer will find the template that they want, so you should ask TemplateCloud which tag types are available, and publish these tags as search options on your website, under tag type headings. It is conventional to add these as checkboxes alongside your search results.

You’ll probably want a page of initial search results, especially if you used a text search as a starting point. It’s also advisable to cache the results and present them to the client a page at a time.

Getting a list of tags

Call the template method, with filter_options=1, which returns the tags that are present in the templates that would be returned when filter_options=0. In other words, this gets a list of tags.

HTTP request
GET http://api.templatecloud.com/sandbox/templates/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json

The response looks like this:

HTTP response (JSON)
{
     "colours" : [
        {
            "colour" : "86200e",
            "name" : "Maroon"
        },
        more colours ...
    ],
    "sizes" : [
        {
            "name" : "US Business Card (2x3in)",
            "code" : "USABC",
            "count" : "572",
            "selected" : false,
            "area" : 7
        },
        more sizes ...
    ],
    "tags" : [
            {
            "title" : "Product Types",
            "types" : "PRODUCT",
            "tags" : [
                {
                    "name" : "Appointment Cards",
                    "code" : "194",
                    "count" : "42",
                    "selected" : false
                }, 
                more tags of type 'product'...
            ]
        }, 
        more tag types...
    ]
}

You can parse this response into an array, and present the options on your pages.

When your customer ticks the filter options, you should initiate a refined search using an API call having filter_options=0 and the ticked tags encoded into parameters. Note that when a tag is specified, then it excludes all templates that do not have that tag within the tag type.

Including meta-information in your search results

To ask for extra information about the templates, you use the &include parameter to ask for a list of properties. e.g. here we want to know about sizes, colours, tags, tag groups, and images.

HTTP request
GET http://api.templatecloud.com/sandbox/templates/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json&include=tags%2Csize%2Ccolour%2Ctags%2Ctag_group%2Cimages

%2C is a comma, encoded as URL-compatible text.

TCAPI: Populating or customizing a template

This information is based on content from our developer website.

Embedding the TemplateCloud Editor

To embed the Flash editor on your site simple copy-paste the code below and fill all “{}” blocks accordingly. [download jquery.flash.js]

HTML/JavaScript
<!-- Start Editor -->
<script type="text/javascript" src="/js/jquery.flash.js"></script>
<script type="text/javascript">
$(document)
    .ready(function () {
    $('#example')
        .flash({
        src: 'http://www.templatecloud.com/templates_frontend/PDCRobot.swf?1325859802',
        id: 'PDCRobot',
        width: 940,
        height: 800,
        quality: 'high',
        bgcolor: '#0000ff',
        allowscriptaccess: 'always',
        allownetworking: 'all',
        allowfullscreen: 'true',
        wmode: 'transparent',
        base: 'templates_frontend',
        flashvars: {
            autoParams: 'friendlynames=true',
            baseURL: 'http://www.templatecloud.com/api/',
            continueURL: '{your_continue_url}',
            cancelURL: '{your_cancel_url}',
            redirectURL: '{your_redirect_url}',
            templateid: '{template_id}',
            instanceid: '{instance_id}',
            customerid: '{your_customer_id}',
            locale: 'tc_GB',
            bleed: '1.5000',
            extraParam: '&asset_key=*******',
            activeButtonColor1: '0xc8d756',
            activeButtonColor2: '0xc8d756',
            fotoliaSearchTerm: 'business'
        }
    }, {
        version: 8
    });
});
</script>
<div id="example"></div>
<!-- EOF Editor -->
flashvars{ Parameter } Value, Description
Required
autoParams

'friendlynames=true'

When true, we show friendly names like "Your Business Name" instead of our active field placeholders like {{business_name}}

baseURL

The API server address.

  • 'http://www.templatecloud.com/api/' for live
  • 'http://dev.templatecloud.com/api/' for development (see “For development purposes…” below this table)
continueURL
cancelURL
redirectURL
Where the website sends users after they leave the editor:
  • Continue will accept the edits and continue to refine or complete the order (perhaps to select a product).
  • Cancel will be used if a user quits the editor. This will usually be a step backwards, e.g. to select another template, or re-view the existing template.
  • Redirect is invoked when there is a fatal error (e.g. bad parameters). 
templateid The ID of the template that is being loaded into the editor.
instanceid The ID of the template instance that is being loaded into the editor.
customerid Your own customer ID, assigned to you by the TemplateCloud team. (not an ID for your customer)
locale

Selects a language for notifications and display.

Allowed values: 'en', 'fr', 'nl', 'de', 'pt', 'it', 'es', 'se'

bleed Templates for our production have 1.5 bleed; your SupplieReady products might have a different value.
extraParam: asset_key = hex(SHA1(concat( <your editor_key>, <instanceid> )))
activeButtonColor1
Primary button colour (for the most important actions)

RGB hex (C format), e.g. '0xc8d756'

activeButtonColor2

Secondary button colour.

RGB hex (C format), e.g. '0xa88080'

allowFotoliaImages When false, the editor does not offer library images to replace existing images. (JS Boolean, default: true)
fotoliaSearchTerm The term searched for when the Fotolia editor appears.
Image chooser - paging
userImagesPagingRequired 'true' These help preserve client-side memory by loading user images in groups as required. E.g. If the first item is set to 'true', then the editor will load 10 images initially and load images in blocks of 5, as the user scrolls.
defaultNumberOfImages 10
numberOfImagesToAdd 5

For development purposes please use the following values for variables:

src

'http://dev.templatecloud.com/templates_frontend/PDCRobot.swf?1325859802'

baseURL

'http://dev.templatecloud.com/api/'

templateid

10014

Please use this ID for testing purposes; only a limited number are activated on the DEV server.

instanceid 

436738

This is generated using the method "Create Instance", see https://developer.templatecloud.com/docs#/instances 

customerid

'TCDEMO'

asset_key Hexadedimal representation of SHA1 hash of concat('bf6b7bb900dcb665497362cbce0a9e90', instanceid).

ExtraParam: asset_key

It’s worth explaining how to obtain a value for asset_key, in more detail.

  1. First join the instanceid to the API key,
    e.g. if instanceid=356 and the API key is ba386e729c5f6870cea89f38e92d7a5c,
    then the concatenated string will be ba386e729c5f6870cea89f38e92d7a5c356.

  2. then obtain the SHA1 hash of the result

  3. and then convert that hash to a hexadecimal string.

TCAPI: Buying a PDF

Protecting your cashflow

A PDF is bought when you call /makePDF/; a charge is made to your account.

You should endeavour to protect your cashflow by ensuring that whenever you are charged the small fee by TemplateCloud, you are charging your customer enough margin to cover the fee.

It might help to design your workflow so that it does not allow tight editing cycles.

Also remember to use the sandbox when developing and testing.

Avoiding PDF exploitation

If further edits are needed after makePDF, you’ll need to generate a new template instance from a template, which carries a further charge because that uses makePDF. As with the “protecting your cashflow” warning, you’ll want to avoid creating lots of instances for the same chargeable item on your site. For example, you’ll need to take payment before offering PDFs or derived works to your customer.

TCAPI: PHP platform example

Interface

The Pest interface (https://github.com/educoder/pest) can simplify API calls. Here’s an code snippet that gets and displays TemplateCloud data in PHP:

PHP
// Load the library (Pest folder must be in PHP's include path)
require_once 'Pest/PestJSON.php';
include '../data/tcapi_key.php'; // e.g. contains: $tcapi_key = '01234567890abcdef';

// Initialise the library (put in your TC credentials here; username not needed for dev/sandbox)
$apiClient = new PestJSON( 'https://api.templatecloud.com/v1' ); 
$apiClient->setupAuth( 'username', 'password' );

// Make a simple get call (this returns tag types in JSON format)
try {
    $result = $apiClient->get('/tag_types/?format=json&user_key='.$tcapi_key );
}
catch (Exception $e) {
    // Handle error. In practice there are several exception types,
    // which you can use to differentiate between different error conditions
    die( $e->getMessage() );
}

// Examine successful result
// This just outputs to the page; you'll want to present it nicely.
echo '
';
print_r( $result );
echo '
';

To use the sandbox, the above example is modified slightly:

  • Change the API access point to
    $apiClient = new PestJSON( 'https://api.templatecloud.com/sandbox' );

  • You don’t need to supply (username, password) at the authentication step.

When your production account is set up, we’ll give you the (username, password) for the authentication step.

Example: Templates

It’s likely you’ll want to get a list of templates that meet your criteria. Here’s an example where we look for templates suitable for two-sided A6. It also returns their meta-data (tags, colours, etc) which you can omit by removing them from the include parameter. 

PHP
...
    $result = $apiClient->get(
        '/templates/?format=json' .
        '&user_key=' . $tcapi_key .
        '&include=tags%2Csize%2Ccolour%2Ctags%2Ctag_group%2Cimages' .
        '&pages=2&sizes=A6'
    );
...

TCAPI: FAQs

Documentation

1. Is there some technical documentation where my engaged developer can learn how it works, and assess how easy it would be to integrate?

Besides this document, go to https://developer.templatecloud.com/ and request an API key.

The API is simple to integrate, and most of your time will usually be spent getting your database and website into the right ‘shape’.

TemplateCloud Capabilities

2. Listing Templates: Is it possible for me to pre-set and exclude some of the Filter? Can I hide the options?

The beauty of the TemplateCloud API is that it is totally customisable. If you only wanted to sell Business Cards, or blue coloured designs, or leaflets for beauty spas, you only request those thumbnails. You can filter out any designs you don't want to display by price, product type, size, colour type or just about any attribute you can think of.

3. Can a customer edit an old order?

Yes, it is possible to create a new instance as a reorder of a previous design. The original stays ‘intact’, but the copy can be pre filled with same text/images so that they can start from a previous design. Each time you request a new PDF, we charge a design fee.

4. I’m making a Business Card website where customers order for many employees...?

Since you are controlling the shopping cart/checkout process, you can treat this as a single order from the client's perspective.

Using the API you would just create (say) 5 instances, and include them all in same basket on your site.

Regardless of whether you're ordering them separately or all together, each card consumes the same service/server load and we pay the same royalties to the designer, we would charge for 5 PDFs.

5. Do the templates have Spot UV layer?

We support spot UV, die-cut shapes, embossing and foil blocking.

However, we [at the time of writing] don't have any designs in the TemplateCloud library which currently have any of those finishes. If you were adding content to the TemplateCloud library, we can teach you how to set these up – it’s simple.

API-consuming services

6. Do I keep my existing checkout and banking process?

Yes. TemplateCloud API provides the three services that help your customer select a template, edit the design, and for you to request a PDF of the customised design. Your website charges your customers.   

7. When do I incur transactional charges?

Only when you call /instances/<instance_id>/makePDF.  

8. Where do I find template prices?

The /templates/<template_id> API call gives you the pricing  of each template:

template.price = the price we advise you to sell to your customer (the “retail price”);

template.click_price will always be 0,00 for you and is thus redundant;

template.cost_price = the price we will charge you for generating the PDF.

9. What is the URL for the live TemplateCloud API?

We do not publish the address of the live TemplateCloud API to prospective developers, until we have assessed their release candidate.

10. Template editing fails. How do I build the hashed ‘instance ID’?

We describe how to build extraParams: asset_key in detail,  in Populating or Customizing a Template.

 
 

See also

TCAPI (TemplateCloud) live documentation

Jump to contents page of

w3p APIs

 
 
 

All content is (c) Grafenia Operations Limited, 2018 and may not be used, copied or distributed without permission.