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

• http://www.printing.com/uk/catalogue/designs/leaflets
• http://www.drukland.be/Web2PrintProductsNew.aspx
• http://www.flyerzone.co.uk/business-cards
• http://www.templatecloud.com/uk/designs/
• http://www.printia.es
• http://dave.websitesforprinters.com/design-online/business-cards/

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

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

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.

GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=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)

(click for bigger image)

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.

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.

Your API Key

Guard your API Key

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 );

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:

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)

{
  "status": "error",
  "message": "Template not found"
}

Success (response code 200) 

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

GET http://api.templatecloud.com/sandbox/tag_types/1?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=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: 

GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=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: 

GET http://api.templatecloud.com/sandbox/tag_types/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=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>    

Retrieves a tag type, or lists tag types.

Request

Request a tag type by id

/tag_types/<tagtype_id>/

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

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

Request a list of tag types

/tag_types/

Retrieves all tag types:

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

Response

{
    "tag_types": [
        {
            "id": "1",
            "name": "Industry Types"
        },
        {
            "id": "2",
            "name": "Client"
        },
        etc...
    ]
}

If one result is returned,

{
    "tag_type":
        {
            "id": "1",
            "name": "Industry Types"
        }
}

Relations

References to tag types

• tag type in template: template.tag.tagtype_id
• tag type in tag group: taggroup.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>

Retrieves a tag group, or lists tag groups.

Request tag group by id

/tag_groups/<taggroup_id>/

Retrieves a tag group.

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

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

{
    "tag_group": {
        "id": "2",
        "name": "Easter",
        "tagtype_id": "8",
    }
}

Request list of tag groups

/tag_groups/

Retrieves all tag groups, using optional filters.

GET http://api.templatecloud.com/sandbox/tag_groups/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=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>

Request template size by id

/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

/template_sizes/

Retrieves all available template sizes.

GET http://api.templatecloud.com/sandbox/template_sizes/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=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>/

Templates

Buy an InDesign file

/templates/<template_id>/buyIndesignFile

Buys the InDesign file. This might incur a charge.

Fetch a bought InDesign file

/templates/<template_id>/indesignFile

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

Prepare a template for editing

/templates/<template_id>/edit

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

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

{
    "instance_id": "436935"
}

Template instances

Make a PDF

/instances/<instance_id>/makePDF

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

PUT http://api.templatecloud.com/sandbox/instances/50010/makePDF?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=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

/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.

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

{
    "status": "error",
    "message": "PDF generation in progress." 
}

{
    "status": "error",
    "message": "PDF generation failed." 
}

{
    "status": "error",
    "message": "PDF not created (probably instance not found, or some unknown error)." 
}

{
    "status": "ok",
    "message": "PDF ready." 
}

After receiving a 200 response, the file can be retrieved using the equivalent GET 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 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.

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>

Create session

/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

Example request & responses

http://api.templatecloud.com/sandbox/sessions/create/?template_id=31081

<?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>

http://api.templatecloud.com/sandbox/sessions/create?instance_id=2196517

<?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>

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:

With example data like this:

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

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.

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

The response looks like this:

{
     "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.

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.

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]

<!-- 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 -->

For development purposes please use the following values for variables:

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.

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:

// 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. 

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

Documentation