Support for

w3p APIs

John Valentine
by John Valentine 10 years ago
 
API services provided by w3p.

Public sites

w3p.com w3p.com

FLAPI: Flyerlink API

Developer Documentation

Flyerlink API Guide Flyerlink API Guide

Corporate process: licensing, guarantees, documentation, care

TCAPI: TemplateCloud API

Developer Documentation

TemplateCloud API Guide TemplateCloud API Guide

TCAPI developer (public site) TCAPI developer (public site)

Supporting API Developers/Consumers

P-FLAPI: Production subset API

P-FLAPI Flow-Chart Process P-FLAPI Flow-Chart Process

w3p APIs

API services provided by w3p.

w3p.com

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

Flyerlink API Guide

This is for you if you're integrating w3p services into your own systems.

What is FLAPI (Flyerlink API)?

FLAPI is a collection of services, which share a common access point.

API Subsets

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

P-FLAPI For Producers to fetch jobs that have been sold via Flyerlink, a franchisee, or printing.com channel.
M-FLAPI For w3marketplace suppliers, to create products to be sold in Flyerlink channels
S-FLAPI Stock management, to help fulfil jobs needing materials or off-the-shelf goods.

Services

Service FLAPI P-FLAPI M-FLAPI S-FLAPI
Product specifications (get, create)    
Product prices (get, create)    
Product categories (get)    
Product tags (get, create)    
Product groups (get, create)    
Customers (get, create, update) get get  
Customer addresses (get, create, update) get get  
Jobs (get, create, update) get, upd get, upd  
Job despatches (get, create)  
Job finances (get, create, update, delete) get get  
Orders (get, create, list jobs, add package, update) get, list get, list  
Payments (get) get get  
Invoices (get)  
Runs (get, get filtered, accept)    
Jobs in runs (get, delete) get    
Run types (get, create)    
Stock control functionality       TBC

 

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)

FLAPI: Development and Production

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.

See also

Separating development from production

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

Please ask one of our team to set you up with a production account. 

Development URLs

Production URLs

FLAPI: Relationships

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.

 

FLAPI: About Orders and Jobs

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.

 

FLAPI: About Production and Runs

Checking your ‘in-box’

w3p automatically assigns jobs to your workgroup when they are ordered by customers. These jobs are packaged in runs, the objects that track production.

Periodically poll your list of runs, with criteria: state=production and days=<despatch target>

HTTP request
GET https://dev.flyerlink.com/api.php/runs?state=production&days=10&format=json

Starting work

Examine a run, to get the specifications of all its jobs (there is usually just one job in a run).

HTTP request
GET https://dev.flyerlink.com/api.php/runs/1234/jobs?format=json

Claim the run with ‘accept’ call:

HTTP request
POST https://dev.flyerlink.com/api.php/runs/1234/accept
format=json

The locations of artwork files are detailed in each job object in the above GET /runs/.../jobs/ call.

Now do what you do best: convert the order into goods or services, and then process your items for despatch. Inform w3p that this is done by logging the despatch (see Despatching, below).

Aborting a job

If something 'abortive' happens during production of a job, you can remove it from its run

Either you or the studio can then make changes before it does to production again (status 081)

Note for admins

When a job.status is set to 081, and the run type should be configured to be ‘auto-allocating’, then the job will be allocated immediately to a new run.

Just deallocate - make API changes

If you want to change the job, but the job is locked.

First deallocate the job and then make changes using PUT /jobs API requests.

HTTP request
POST https://dev.flyerlink.com/api.php/runs/1234/jobs/5678/deallocate

OR (alias)

HTTP request
POST https://dev.flyerlink.com/api.php/jobs/5678/deallocate

Deallocate & status 091 - require changes from design studio

To require a studio to make changes provide a costing and reason as url parameters

The studio will then be notified the job has been sent to status 091 and requires changes before it can be produced.

HTTP request
POST https://dev.flyerlink.com/api.php/runs/1234/jobs/5678/deallocate
?costing=CAN&reason=My%20Reason

OR (alias)

HTTP request
POST https://dev.flyerlink.com/api.php/jobs/5678/deallocate
?costing=CAN&reason=My%20Reason

Despatching

Immediately before despatching, get the despatch specification again, in case it has changed since calling GET /runs/1234/jobs

Use the POST /job/…/despatch request to register that you have physically packed and processed a job for despatch.

HTTP request
POST https://dev.flyerlink.com/api.php/jobs/<job.id>/despatch
line=2316091&quantity=1000&boxes=1&run=12345

Other Queries

Has a job been despatched?

HTTP request
GET https://dev.flyerlink.com/api.php/jobs/<job.id>/despatch

What runs have been completed?

HTTP request
GET https://dev.flyerlink.com/api.php/runs?state=production&days=10

FLAPI: About Products

Publishing your products

Stage API call
1. create product category POST /product_categories
2. create product group POST /product_groups
3. create product POST /products
4. add pricing POST /products/.../prices
5. assign permissions (Flyerlink)
6. make live (publish) (always live; use Flyerlink to re-enable)

Maintaining your products

Stage API call
7. change pricing POST /products/.../prices
8. change specifications PUT /products
9. retire product (Flyerlink)

 

FLAPI: About Customers

Stage API call (some parameters omitted)
1. create customer category
POST /categories
2. create customer
POST /customers
    (add addresses)
POST /customers/<customer.code>/addresses

    (view contacts/users)


     (view specific contacts)


      (create contacts/users)


     (update contacts/users)

 

GET /customers/<customer.code>/contacts
GET /customers/<customer.code>/contacts/<contact.id>
POST /customers/<customer.code>/contacts
PUT /customers/<customer.code>/contacts/<contact.id>
    create order for customer
POST /orders
customer=<customer.code>
    create job for customer
POST /jobs
customer=<customer.code>
    view invoices
GET /invoices

Then filter your results by customer.

    (retire customer) Customer records become dormant, rather than retired, so that historical records remain. If you have reason to employ checks before trading with a customer, then record it in your own data.

FLAPI: Authentication and Credentials

Authentication

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

Getting your App approved

You’ll need to obtain credentials (username, password) before you can use the API. Get your developer account details by speaking to w3p API support.

This guide documents the API interface itself. For licensing and legal, see http://w3p.com.

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

     

FLAPI: Format for requests

Sandbox and documentation site, to help you test

At https://dev.flyerlink.com/api.php/, we provide a sandbox for API requests, which documents the API requests, along with convenient entry forms where you can specify values for parameters..

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 https://dev.flyerlink.com/api.php/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.

When sending a POST or PUT request, we expect them as HTTP form fields
You can push them through as an array
Here's an example of a POST customer request

<?php

$postFields = [
"id" => "HOTEST",
"name" => "Jean TEST",
"username" => "API example",
"password" => "example1234",
"email" => "bbb@test.com",
"telephone" => "01470054111",
"mobile" => "0674584511",
"address1" => "",
"address2" => "Your Address",
"address3" => "",
"address4" => "Manchester",
"address5" => "",
"postcode" => "M17 1AA",
"countrycode" => "GB",
"workgroup" => "W11",
"category" => "816",
"payment_terms_code" => "CASH",
"payment_terms_description" => "Cash"
];

$s = curl_init();
$username = 'xxx';
$password = 'xxx';

curl_setopt($s, CURLOPT_URL, 'http://dev-7.flyerlink.com/api.php/customers');
curl_setopt($s, CURLOPT_USERPWD, $username . ":" . $password);
curl_setopt($s, CURLOPT_RETURNTRANSFER, true);
curl_setopt($s, CURLOPT_POST, true);
curl_setopt($s, CURLOPT_POSTFIELDS, $postFields);

$result = curl_exec($s);
$resstatus = curl_getinfo($s, CURLINFO_HTTP_CODE);
curl_close($s);

var_dump($result);
var_dump($resstatus);

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 https://dev.flyerlink.com/api.php/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 https://dev.flyerlink.com/api.php/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 https://dev.flyerlink.com/api.php/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>    

POST responses

  • Currently, responses to POST requests are only returned in XML format.
  • Remember to format POST requests by inserting a new line between the path and the parameters. See examples.

FLAPI: PHP platform example

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

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

P-FLAPI Zapier triggers & actions

P-FLAPI can be connected to via Zapier setting up a few Zapier triggers & actions

Zapier simplifies the process of development with APIs by connecting to a number of pre-built services (such as wordpress, woocommerce, gravity forms, drupal and other CMS) and also simplifies the management of APIs

Here's a video of integrating P-FLAPI with a simple Gravity Form sheet to understand how it works.

 

1) Trigger when job is ready for production
When a job is ready for production we will send a webhook to notify you, you can create a "Zap" in zapier so Zapier catches the webhook and then you can add another zap to manage the zap.

Create a Zapier account via https://zapier.com
Choose "Create Zap"

For a trigger choose Webhook by Zapier (premium)

Let your account manager know the webhook url zapier provides ( it'll be similar to https://hooks.zapier.com/hooks/catch/11111111/xxxx111/ )

Then add another application to your zap for your next step. This could be to create a job in a CMS you use such as WooCommerce

2) Action for job despatch

When you've completed a job in your system you'll need to create a new zap with a trigger coming from your CMS (perhaps a webhook?)

Then add an action with this python code

import requests
if ('JobID' in input_data):
    url = 'https://API_UESRNAME:API_PASSWORD@www.flyerlink.com/api.php/jobs/' + input_data['JobID'] + '/despatch?format=json&all=true'
    payload={all:true}
    headers = { 'Authorization': 'Basic Wi5XTVVLLkFQSTo5eUw2MkhhdmFX' }
    response = requests.request('POST', url, headers=headers, data=payload)
    print(response.text)
    return {}

The Job ID sent through will need to match our Job ID sent in the original Trigger
The Job ID will need to be sent in your first zap step to confirm which job is ready for production

The parts in bold API_USERNAME and API_PASSWORD will need to be replaced with your API username and password to give permission for you to despatch your jobs and only your jobs. You'll need to get in touch if you do not know this.

3) Trigger for job request to cancel production
If a studio makes a mistake (perhaps the job despatch needs to be changed, or there's a file mistake) they can send a request to cancel production.
You can then have a process to decide if it's too late to cancel or if a cancel is possible. If it's too late, you don't need to do anything. But if it's too late you can do step 4).

For step 3), again create a zap that's a webhook trigger.
Let your account manager know the webhook trigger url zapier provides ( it'll be similar to https://hooks.zapier.com/hooks/catch/11111111/xxxx111/ )

4) Action to cancel job

Create a zap to process a trigger from your CMS to cancel a job. This could be because of an issue with the file or because it was requested by a studio in the trigger 3).

The python code you'll need to process this is

import requests
if ('JobID' in input_data):
    url = 'https://API_USERNAME:API_PASSWORD@www.flyerlink.com/api.php/jobs/' + input_data['JobID'] + '/deallocate?format=json&all=true'
    payload={'all':'true'}
    headers = { 'Authorization': 'Basic Wi5XTVVLLkFQSTo5eUw2MkhhdmFX' }
    response = requests.request('POST', url, headers=headers, data=payload)
    print(response.text)
    return {}

(Work in Progress)

Our work here isn't yet done!

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

FLAPI: Enumerated Types

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

Contents

  • Languages
  • Job Status
  • Preflight Types
  • Supplieready Preflight Types
  • Websitecolour

Languages

language
id locale local name language group
22 tc_IE Irish (W3P & TC) Irish (W3P & TC) 1 English
14 tc_NZ New Zealand (TemplateCloud) New Zealand (TemplateCloud) 1 English
15 tc_AU Australia (TemplateCloud) Australia (TemplateCloud) 1 English
9 tc_GB English (W3P & TC) English (W3P & TC) 1 English
23 tc_FR French (TemplateCloud) Français (TemplateCloud) 2 French
24 tc_NL Dutch (TemplateCloud) Nederland (TemplateCloud) 3 Dutch
25 tc_ES Spanish (TemplateCloud) Espanol (TemplateCloud) 4 Spanish
18 tc_SE Swedish (TemplateCloud) Svenska (TemplateCloud) 5 Swedish
19 tc_DE German (TemplateCloud) Deutsch (TemplateCloud) 6 German
20 tc_IT Italian (TemplateCloud) Italiano (TemplateCloud) 7 Italian
21 tc_PO Portuguese (TemplateCloud) Portugues (TemplateCloud) 8 Portuguese
16 tc_US American (TemplateCloud) American (TemplateCloud) 9 American

Job Status

Job status can be used to manage your workflow. Read them to see the state of items in your workflow, and write them to report when you have made progress and want to choose the next step. 

Popular values are listed below.

status
id name
000 Job has been created
011 Design required
033 Proof has been requested
061 Changes required
071 All aspects of the job have been accepted by the customer; make the job ready for production.
081 Ready for production
091 Error found during production: job abandoned/rejected
094 Error found during production: job continued

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.

preflighttype
id name
C Coated preflight
L Large Format preflight
N No preflighting
U Uncoated preflight
UR Uncoated reverse preflight (coated front, uncoated reverse)
Z Don’t convert files

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.

id description
SN Uncoated No crop marks Don’t scale
SE Uncoated No crop marks Scale
SM Uncoated Crop marks Don’t scale
SU Uncoated Crop marks Scale
SC Coated No crop marks Don’t scale
SS Coated No crop marks Scale
ST Coated Crop marks Don’t scale
SW Coated Crop marks Scale

Websitecolour

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

id name
1 Blank – unprinted
2 Full colour front
3 Full colour front, black and white reverse
4 Full colour both sides
5 1 colour front
6 2 colour front
15 Full colour
39 Full colour both sides + spot UV front
40 Full colour both sides + spot UV both sides
46 Full colour booklet: 8 pages
47 Full colour booklet: 12 pages
48 Full colour booklet: 16 pages
62 Full colour booklet: 20 pages
63 Full colour booklet: 24 pages

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

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

TCAPI developer (public site)

Site for developers/consumers of TemplateCloud API (TCAPI). Includes live interactive documentation.

P-FLAPI Flow-Chart Process

Here's the process of the necessary API requests for a  P-FLAPI integrator:

Option 1) Webhook & confirm

Let us know a url to send a webhook to

When a job is ready for production (at status 081 in our termonology)
We will webhook either XML or JSON of our GET /jobs/<job.code> request
For XML response we resend every 5 minutes until we get a JSON response "Accepted" (0)
For JSON we resend every 5 minutes until we get a Status 200 HTTP response

When job is completed send us back a despatch all approach
POST /jobs/<job.code>/despatch?all=true

Option 2) Pooling lookup

 
 
 
 
 

All content is (c) Nettl Systems Limited, 2024 and may not be used, copied or distributed without permission.