Learn about w3p: Advanced web-to-print software that places specific emphasis on the ease of template creation for the printer.

API Subsets

We’ve organised these into sub-APIs, to create selective subsets of FLAPI, aimed at implementing a type of service:

Services

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)

Your website and its data

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

Separating development from production

We provide a developers’ sandbox, to help you avoid incurring charges or writing to live data while you’re testing.

Development URLs

• API server: https://dev.flyerlink.com/api.php/

Production URLs

• API server: https://www.flyerlink.com/api.php/

w3p-Flyerlink is a complicated system, containing hundreds of tables, which store data relevant to our business and your business. FLAPI exposes the data that is relevant to your integrated application. In this guide, we explain:

• the data structure, and how tables relate to each other;
• what the objects represent in the businesses they support; along with
• some examples of workflows using the API.

Use this in conjunction with the “API Requests and Responses” chapter, which details each field of the data responses.

Relationships

FLAPI hides some of the complexity of the actual data structures. Instead, we designed our API to return simple lists of items associated with the object of interest.

The most important table is the job table.

Typically, a job results from a customer putting an item in their basket. Each job represents a deliverable item or service from a producer to a customer, including its associated options.

Each job can have several revenue items or options available, and multiple jobs can be grouped together in orders. An order may also have a package deal, where jobs purchased together earn discounts.

• If you are a producer, publishing products to w3p, and expecting jobs to arrive from other workgroup’s customers, see Production and Runs, below.
• If you are generating orders from your website, see Selling from your website.

Selling from your website

How customers choose products

If you are selling other producers’ existing products, then it’s fairly straightforward to present the products in a searchable interface, and optionally use the TemplateCloud library of professionally-designed, data-aware templates.

FLAPI provides all the job information you'll need to present our products in your listings. See also:

• TCAPI (TemplateCloud) Integration Guide.

Selling your own products

If you have your own products to sell, then you’ll need to create those products using POST /products/.

If you're building a website from scratch, you may want to check out our w3shop offering, which has the TemplateCloud & FLAPI in-built.

The customer will then make a product and quantity choice of item from your website, which you might add to your website’s basket, before placing the job (optionally in an order) after checkout.

If you are a supplier, you can produce orders made by others within Flyerlink. Simply use your Flyerlink login to access Production > Dashboard. This will show you all the jobs that need to be produced. P-FLAPI also provides functionality so you can progress these jobs within your own system. See Runs.

You can create jobs without creating orders; simply regard orders as a convenient way of grouping jobs together so they can be handled as one object, e.g. for payments, or combination offers.

Then you use the Production workflow. See Production and Runs, below.

Publishing your products

Maintaining your products

Authentication

Use the username and password we provide, in basic authentication.

Your API credentials

Your credentials allow your systems to access w3p services via FLAPI. If someone else has your credentials, 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 credentials:

• Use SSL for API calls (use https:// instead of http://). 

• If you experience problems due to unauthorised sharing of your credentials, then change your credentials, close the security hole, and update your services to use your new credentials.

• Do not hard-code your credentials in every request call; instead use a variable containing the credentials.

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

• Do not allow your web server to show code that might display your credentials.

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

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

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

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

  PHP

  <?php $thatWorked = 'Insecure handy calculator: ' . eval( $userInput ); ?>

   

Interface

You might like to use an interface to manage your API session, package your requests, and include authentication credentials.

In the example below, we use Pest, available at

https://github.com/educoder/pest

Here’s an code snippet that gets and displays FLAPI data (from the developer sandbox) in PHP

// Load the library (Pest folder must be in PHP's include path)
require_once 'Pest/PestJSON.php';
include '../data/flapi_credentials.php'; // e.g. contains: $flapi = [ ‘user’, ‘pass’ ];

// Init the library (put in your TC credentials here)
$apiClient = new PestJSON( 'https://dev.flyerlink.com/api.php' ); 
//  $apiClient->setupAuth( 'username', 'password' );
$apiClient->setupAuth($flapi[0],$flapi[1]);

// Make a simple get call (this returns tag types in JSON format)
try {
    $result = $apiClient->get('/product_categories/?format=json');
}
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 '<pre>';
print_r( $result );
echo '</pre>';

Our work here isn't yet done!

We're developing more content, and this should soon be complete.

Here we show lists of items that might be referred-to using fixed ids.

Languages

These profiles are used at product group level, to specify the file checks and corrections that are applied to all products within the product group.

Supplieready Preflight Types

These profiles are used at product group level, to specify the file checks and corrections that are applied to all products within the product group. Supplieready profiles perform corrections to the geometry and markup of the files.

Popular values are listed below. If you need something else, let us know.

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.

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

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