One of our great partners, Matt Muresan, the proprietor of OncePressed.com let us know today about some of his experiences working with the Printfection API.

Its great to hear from folks in the trenches and Matt has done a great job of putting together some thoughts and feedback on his blog at http://www.oncepressed.com/blog/2009/06/my-printfection-api-t-shirt-store.html.

Matt has built himself a great way to bring much of his store onto his own domain (a great way to build a brand) and have it live alongside his blog and other parts of the OncePressed.com empire.

Well done Matt, and thanks for sharing.

Taltopia is a media distribution and social networking site designed to allow people to show off their talents. From music to acting, design and photography, Taltopia gives people a fantastic platform to showcase what they can do.

Taltopia has recently integrated with the Printfection Platform to give users of their service the ability to not just showcase their talents but also sell their designs, artwork and photography on custom printed on demand merchandise. Taltopia has used AddMerch to provide the interface and have done some clever creative development in their backend to handle the rewarding of their talent when things are purchased.

Another great example of dynamic Print on Demand in action. Check them out at http://www.taltopia.com

What is it?

Quick Merch was designed as a kind of bulk product create tool, where a user can select an image, choose a few options and hit go. Quick Merch goes off and uploads the image, creates a section and then creates all the selected products in one single step. It then returns some code and other marketing tools to help people market their creations. View the below video for a better understanding.

How does it work?

Printfection Quick Merch is built using PHP and the standard Printfection API. It use many of the methods to create things as well as PFQL to set up the input form and process the request. It is another practical example of what can be done with the Printfection API. We made no modifications or changes to the API, so you can build something similar as well.

Who can use it?

Even though we built it specifically for webcomic producers, Quick Merch can be used by anyone, especially, anyone who is producing a lot of new content on a regular basis and wants to create their product inventory fast. Feel free to try it out yourself, no matter what your background.

Creating a basic product is simple using the Printfection.Products.create method. This method has only four required parameters that must be sent in the request:

• rootid - The root product for your new item
• sectionid - where you want the product created
• rootcolorids - a list of colors that you want available
• specs - an array of design options to use to create your product

There are however some important concepts to understand to make the process smooth.

Root Products

Every product created at Printfection is based on a root product. A root product is the blank item that you want to base your custom product on. You can see the current range of root products in our catalog.

Each item has a unique ID to identify it to the API. Take the following root products as an example:

T-Shirt - Rootid 7Mens Ringer T - Rootid 20Jumbo Tote Bag - Rootid 18

You can retrieve a full list of root products using the following PFQL:

SELECT rootid, title FROM root_products WHERE 1 ORDER BY title

Root Colors

Each root product has its own unique set of root colors that are used to add color selections to your root products. You can send a single color, or a comma separated list with your request.

You can retrieve a full list of root products using the following PFQL ($rootID must be a valid root product):

SELECT rootcolorid FROM root_product_colors WHERE rootid= $rootID

Product Specs

The final parameter that we need to use when creating a basic product, is the specs. The specs tell the api how you actually want your design set upon the root product. The specs are sent as a serialized JSON array and contain the following items:

• side - 0 (front) or 1 (back)
• imageid - the image that you want on your product
• position - (optional) The position on the root product to use.
• center_percent_x - (optional) The percent from the top of the position to the center of the image.
• center_percent_y - (optional) The percent from the left of the position to the center of the image.
• rotation - (optional) Possible Values: 0,90,180,270 The rotation of the image.
• height - The height in inches of the image

In PHP, a sample specs variable would like like this:

$specs = '
{
"SPECS": {
"side": 0,
"imageid": "'.$imageID.'",
}
}';

Putting it all together

So now, to create our product, it is simply a matter of sending our request with all the parameters attached. As a sample, the following PHP code will use cURL to send the request:

$api_sig_tmp2 = "api_key=".$api_key."method=".$method."rootcolorids=".$rcid."rootid=".$rootid."sectionid=".$sectionid."session_key=".$sessionID."specs=".$specs."version=1.0".$secret;
$api_sig2 = md5($api_sig_tmp2);

$post_data = array();
$post_data['api_key'] = $api_key;
$post_data['api_sig'] = $api_sig2;
$post_data['method'] = $method;
$post_data['rootcolorids'] = $rcid;
$post_data['rootid'] = $rootid;
$post_data['sectionid'] = $sectionid;
$post_data['session_key'] = $sessionID;
$post_data['specs'] = $specs;
$post_data['version'] = "1.0";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://api.printfection.com/restserver.php" );
curl_setopt($ch, CURLOPT_POST, 1 );
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$postResult = curl_exec($ch);
if (curl_errno($ch)) {
print curl_error($ch);
}
curl_close($ch);

That will return an XML document that contains the productid for the product that you have just created.  You should store this in a variable for use in the next part, where we add some more information, as well as set our commision for the product.

Dynamic Product Creation

Traditionally, with a service like Printfection's, you would have to set up all of your products with designs, descriptions and prices in advance, but now with the API, you can create unique products from scratch as the customer wants it. For example, look at how the Printfection API is used at Ukulele Shirt World.

In this process, the customer is being given the option to create a custom back design (Step 1) to be paired with a standard design on the front (Step 2) and then a choice of shirts (Step 3).

The image in step 1 is generated dynamically using PHP and ImageMagick. You could use PHP GDI, Flash or some other way of generating the artwork. The list of images in Step 2 is pulled from a single image set using the API. The list of products in this case are hard coded, however they could be pulled from the Root Products using the API.

Once the shopper has selected all of their options, the Printfection API is used to upload the custom image, create the two sides on the chosen root product and then redirect them to the store for purchase. In this example, the standard Printfection checkout is being used, however for even tighter integration, the API cart and checkout methods could also be used.

Building products on the fly has some advantages, particularly if you want to adjust something down the track. If you have created hundreds of products, and now wish to alter pricing, you will need to do it one by one or delete them and start again. With dynamic products, the margin is set in a single point for all created products. You can change this number up and down as you like for all future products.

This is just one example of dynamic product creation, so how about showing us yours.

The Printfection API has a built in method for uploading images to your account, "Printfection.Images.upload", which is a little bit different from the other methods. Firstly, it must be sent as a POST request, and unlike the other methods, it has it's own URL for the request, http://upload.printfection.com/api_upload.php.

The upload method has four specific parameters that are sent with the request, the data of the file, the name for the image, the image set that you want to put it in and optionally, a comma separated list of keywords to associate with the image. As usual, you also need to send the global, api parameters and the api signature with the request.

Because we are sending file data with our parameters, we need a method for attaching the file to the request. You could use a form, however in PHP, the most flexible method is to use cURL.

Example

Like all of our other uses of methods, we need to set up our parameters. First, the global parameters

$api_key = your_api_key;
$secret = your_secret_key;
$sessionID = your_sessionID_recevied_from_authentication;
$method = "Printfection.Images.upload";

Then the parameters for our upload:

$uploadfile = "/home/public_html/images/HelloWorld.jpg";
$isetid = "50000";
$iname = "Hello World Image";

Then we can calculate the api_sig using our alphabetized list of parameters. Note that the actual image file is not part of the key:

$api_sig_tmp = "api_key=".$api_key."imagesetid=".$isetid."method=".$method."name=".$iname."session_key=".$sessionID."version=1.0".$secret;
$api_sig = md5($api_sig_tmp);

Sending the cURL request

Now that we have all our parameters and our file, we can send the request.

$post_data = array();
$post_data['api_key'] = $api_key;
$post_data['api_sig'] = $api_sig;
$post_data['session_key'] = $sessionID;
$post_data['method'] = $method;
$post_data['name'] = $iname;
$post_data['imagesetid'] = $isetid;
$post_data['version'] = "1.0";
$post_data['file'] = "@$uploadfile";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://upload.printfection.com/api_upload.php" );
curl_setopt($ch, CURLOPT_POST, 1 );
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$postResult = curl_exec($ch);

In this example, $postResult is the returned XML from your request, which includes the imageid for your newly uploaded image:

<?xml version="1.0" encoding="UTF-8"?>
<printfection_response>
<Images_upload>
<imageid>2487672</imageid>
<keywords>OK</keywords>
</Images_upload>
</printfection_response>

You will use the imageid for the next step of actually creating the product.

GirlinYourShirt.com is an innovative new marketing idea that uses t-shirts to promote a business. Each day a new business sends a shirt and for a small fee, Jenae, the girl in the shirt, will wear it and post a promotional video to most of the popular video sharing sites.

GirlinYourShirt.com uses the Printfection API to provide a way for people that don't already have a shirt for her to wear, to make one. They upload their logo and it is put onto a shirt ready for purchase, and can even be shipped straight to GirlinYourShirt.com, ready for the video. All this is achieved using the Printfection Platform and API.

GirlinYourShirt.com has been featured by a number of media outlets and popular blogs, and is another great example of the wide range of uses for the Printfection API.

You can see it in action here.

Getting Started

Printfection myBrand is available for every Printfection store, regardless of if you are using the Printfection API or not. The only requirement is that you have chosen a theme for your store. myBrand is not available with the default Printfection theme. To select a custom theme, log in to your account and go to the Store Settings for your store. Then, go to the Themes Tab and select a theme.

Setting up myBrand

Once you have saved your theme selection you will now have a myBrand tab in your store settings. On this tab, you will find all the possible myBrand settings to fully control your branded customer experience:

General Settings

• Hide Printfection Header - Select this to remove the Printfection logo and header bar from the top of your store. Make sure that if you select this option you add links within your store to the checkout and help pages.
• Contact / Help URL - The help section of your store has an unbranded form to contact Printfection Customer Service. Setting this option with your own URL will give your customers a link to a contact page that you setup on your own site or within your store.

Checkout

• Header Image - This is a specific logo that you select from your image basket that is used in the top header of your store's checkout. This image has a maximum size of 760px x 100px. If you select a larger image, it will be resized to fit.
• Background Image - The image from your image basket that you wish to use as your checkout's background.
• Background Image Position - Select the position, alignment and tiling for your checkout background.
• Page Background Color - The hex color code for your checkout background
• Sample myBrand Packing SlipHeader Background Color - The hex color code for your checkout header background
• Font Family - The font stack that you want for your checkout
• Order Complete Button Text - The text that you want on your button that the customer presses to complete their order.
• Order Complete Button URL - The URL that you want customers to be sent to after checkout is complete. Can be any URL, either internal or external

Email

• Email From Name - Store or Business name displayed in auto emails such as order confirmation emails and password reset emails.
• Email Footer - Displayed at the bottom of auto emails. Consider including Printfection's phone number and/ or the URL to your contact us page: eg - http://www.printfection.com/myBrandTest/help/contact/

Packaging

• Sample myBrand Mailing LabelPackaging From Name - Store / business name displayed above the return address on the shipping label. Also shows on the top of the packing slip if no image is selected below
• Packaging Image - The image from your image basket that you wish to have printed on the packing slip that is shipped with your customer's order.

How to use all this for best effect

We have designed myBrand to enable you to achieve two very important factors to improve your eCommerce success.

The first of these factors is conversions, the percentage of visitors that go to your checkout and then actually proceed through to payment and a completed order. When your checkout looks vastly different to your main store, customers may become confused or feel less confidence in actually making a purchase. To take full advantage of the myBrand features, you should choose images, colors and fonts that best match your store's look and feel. Without myBrand the checkout is likely to be vastly different to your store.

The second major factor that will help you is repeat business. myBrand gives you the ability to customize emails and packaging to ensure that your store's name, logo and even the web address is shown to the customer, instead of Printfection's. When they sit down to open their package, your brand will be prominently displayed, giving them ample reminder to return and buy more of your designs and even tell their friends.

Finally

We believe that this is a very valuable part of the Printfection Platform and urge all partners to take best advantage by taking their time and creating a consistent shopping experience for the customer.

The Printfection.com website will undergo scheduled maintenance beginning 11/24 at 10:00 PM MST. The maintenance period is scheduled to last up to 2 hours (Monday 11:59 PM MST).

During this time, the Printfection Platform will be unavailable. Thank you for your patience.

But what if you want to actual create or change things using the API. This is where API Methods come in. We've actually already used two methods for authentication and passing a PFQL query. There are many more Methods that can create, modify and delete pretty much anything. Stores, Sections, Products and shopping carts are all manageable using methods.

Method Structure

All methods follow a similar structure, with a number of required and optional parameters that need to be sent with the command. For example, the method to create a new store, Printfection.Stores.create, has two required and one optional parameters:

• name - the name of the store that you are creating (required)
• url - the url extension that you want your store to have e.g. http://www.printfection.com/url (required)
• store_access - 0,1 or 2 to set your new store to open, closed or hidden (optional)

Passing a Method

Passing a method to the Printfection API is very simple, It is really just a matter of constructing a formatted URL that is sent to the Printfection server. The URL consists of your API key, sessionID, the method name and all the parameters that you will be sending. You also need to generate the md5 API signature of the request to ensure that everything is above board.

An Example

Using the Printfection.Stores.create method from above, we would create our url as follows. I like to use variables to store my parameters, so first we need to define everything:

$method = "Printfection.Stores.create";

$store_name = "My New Store";

$store_url = "mynewstore";

$store_access = 0;

Then we need to construct our api signature. This is the md5 encrypted version of our command, without the & between each parameter. Remember also from the Authentication process, that all parameters must be in alphabetical order.

$cmd_str = "api_key=".$api_key."method=".$method."name=".$store_name."session_key=".$sessionID."store_access=".$store_access."url=".$store_url."version=1.0".$secret;
$api_sig = md5($cmd_str);

Now we can construct our complete url to send the command, using all of our gathered information:

$q_url = "http://api.printfection.com/restserver.php?api_key=".$api_key."&method=".$method."&name=".$store_name."&session_key=".$sessionID."&store_access=".$store_access."&url=".$store_url."&version=1.0""&version=1.0&api_sig=".$api_sig;

That gives us a complete API url, that when sent as a GET request will return an XML response with either the new store ID, or an error, if things have not been done correctly:

<?xml version="1.0" encoding="UTF-8"?>
<printfection_response>
<Stores_create>
<storeid>38874</storeid>
</Stores_create>
</printfection_response>

You can read more about methods in the Methods documentation.