EZPrints FullIntegrationGuide-v2

ezprints, inc. 1

ezprints, inc. Integration Guide

Updated: 3/31/09

ezprints, inc. 2

Table of Contents Overview of Integration .........................................................................................4 Integration Task List..............................................................................................4

New Partner Integration Questionnaire .............................................................6 New Partner Information Form ..........................................................................9

Posting XML Orders............................................................................................10 Posting URLs...............................................................................................11 Sending Your XML Order File......................................................................11 Duplicate Order Checking............................................................................12 Image Collection and Granting EZPrints Access to Your Images................12

Order XML Format ..........................................................................................12 XML Structure:.............................................................................................12 Order Splitting..............................................................................................13 Sample XML Set:.........................................................................................13

Address Verification ........................................................................................14 XML Product Specifications ................................................................................24

Product Specification Layout ...........................................................................24 Index Print....................................................................................................25 Work Order ..................................................................................................25 Back print.....................................................................................................27 Watermark ...................................................................................................28 Image Resolution Considerations ................................................................29 Print Paper Considerations..........................................................................29 Paper Finishes.............................................................................................29

Image Manipulation (Sizing, Cropping, Auto-enhance) Functionality ..............30 Crop Settings ...............................................................................................30 Auto Enhance ..............................................................................................32 Sublimation..................................................................................................33 Image Orientation ........................................................................................33 Product Shots ..............................................................................................33

Shipping and the ezprints Shipping Calculator ...................................................34 Shipping Methods Offered...............................................................................34 The ezprints Shipping Calculator.....................................................................34

Instructions ..................................................................................................34 Available Shipping Services by Country ......................................................36 Shipping Charges ........................................................................................37 State and Country Codes ............................................................................37

Order Statuses and Errors ..................................................................................37 Event Notifications...........................................................................................37

Order Error Codes .......................................................................................38 The Partner Order Administration Tool ...............................................................39

XML Test Order URL ...................................................................................40 Testing Prior to Go Live ......................................................................................40 After Your Website Goes Live.............................................................................42

Invoicing ..........................................................................................................42

ezprints, inc. 3

Code Sample Library ..........................................................................................45 Posting Order XML..........................................................................................45

Sample function that will post the XML correctly in VB.Net .........................45 Event Notification XML Examples ...................................................................46

Failure to Unmarshal ...................................................................................46 Accepted......................................................................................................46 AssetsCollected ...........................................................................................46 InProduction.................................................................................................46 Canceled .....................................................................................................46 Shipment .....................................................................................................47 CompleteShipment ......................................................................................47 Complete .....................................................................................................48 Example PHP code to receive & parse the Event Notification XML data.....48

Shipping Calculator Code................................................................................48 Example Perl Code to Post to the Shipping Calculator................................48 Calculate Panoramic Print Price (JavaScript) ..............................................49

FAQs...................................................................................................................49

ezprints, inc. 4

Overview of Integration As a new ezprints (EZP) partner, we’re excited to start fulfilling orders for your company. In order to do so, you’ll need to configure your website or application to send XML orders to EZP for fulfillment. The specific tasks you need to complete will depend on how far you’ve advanced in the development process for your website or application. Some of our partners have live sites that are currently accepting orders and some are building a new site or application. Regardless of your progress, this Integration Guide will help you with all aspects of integration. The Integration Task List section describes some tasks you will likely need to accomplish in order to integrate with EZP. In general you will configure your site or application to allow your customers to place orders for ezprints digital image products, bundle the orders into a specified XML order format, and post the order to the ezprints API. Normally, you will develop your site or application concurrently with the EZP Integration team setting up your account. There is a particular ezprints XML order format that is described in detail in Posting XML Orders, along with instructions for gaining access to a list of the products you can order from EZPrints. ezprints offers integration with our Shipping Calculator, described in Shipping and the ezprints Shipping Calculator. Integration with the EZP Shipping Calculator is recommended because the prices we will ultimately charge you are returned from the Shipping Calculator. You have options for receiving order status notifications and/or having your customer service team access our Partner Order Administration Tool. These are described in Order Statuses and Errors and in The Partner Order Administration Tool. When your website or application is ready to be tested, you will coordinate closely with the EZP Integration team for testing. Please see the Testing section for a complete description of testing required before you can send live orders for fulfillment. After your site or application goes live (open to post real customer orders to EZP) your main point of contact transitions from the EZP Integration team to the EZP Account Management team. This is detailed in After Your Website Goes Live. For your developers’ reference we have compiled a library of code snippets that may be useful examples of what you might use in integrating with ezprints. These are shown in the Code Sample Library. A list of Frequently Asked Questions is available in FAQs.

Integration Task List After you have returned a signed agreement and approved credit application to ezprints, your integration can begin. The estimated time to complete each task depends on the starting point for your website or application and on the number of ezprints products you plan to offer. It also depends on whether you are planning to integrate any of the ezprints applications (e.g. Product Builders), or if you’re just submitting orders. The ezprints Product Builders are image crop/edit tools that allow your end users to see what a product will look like with their image on it. The ezprints Product Builders and suite of applications are described in detail at http://ezpservices.com. The Product Builders are built in Adobe Flex, which compiles into an SWF, similar to Flash. Flex is more of an application development tool than Flash, but they both compile to an SWF. The Product Builders use XML and Web services to talk to communicate with EZP servers.

ezprints, inc. 5

To assist the EZP Integration Specialist you will work with, please complete the New Partner Information Form and the New Integration Questionnaire, which are found on the next four pages. You can return these pages to EZP via email.

ezprints, inc. 6

New Partner Integration Questionnaire Instructions Please complete the following form to the best of your knowledge. You will

have the opportunity to make changes in the future. The information below is used to help the integration team prepare and guide you through the integration process. Please complete and email back to ezprints as soon as possible.

Question Answer Partner Name <Your company name you wish to appear in the "From" address on the

shipping label> Partner ID <To be assigned by ezprints> EZP Product Builders?

<Will you be integrating an EZP Product Builder into your website?> Please see http://ezpservices.com/services/how-it-works.aspx for details.

Start/Finish Dates for Site Development

<Estimated dates that development of your website will start and end. Does not include end-to-end testing.>

Estimated start date for testing

<Date you wish to schedule testing. Please allow 7 days after your website coding is complete, in order to do end-to-end testing with us. >

Target Go Live date

<Date that you plan to launch your site/send us live orders.>

Go live volume <Will 100% of your orders be transferred on day 1, or will they be transferred incrementally?>

30 day volume projection - images

<Please estimate the number of images we will retrieve from you over a 30 day period>

Average image size (MB)

<Please estimate the average size of the images we will collect>

30 day volume projection - orders

<Please estimate the number of orders that will be submitted to us in a 30 day period>

Seasonality <If available, please describe your seasonality i.e. May, Nov, Dec = 3x non peak volume>

ezprints Support Tier

<Please indicate which customer support model you have selected. Tier I - your customers call us or Tier II - your customers call you, your customer service team calls us.>

Will you use unique orderids?

<Y/N> We recommend you send unique order numbers which are in the ordersession.sessionid XML element, and a unique order.orderid for each of your orders. A session can have multiple orders in it, in which case the sessionid and orderids would all be different; or if you only send one order per session the sessionid should be the same as the orderid.

What will your orderid format be?

e.g. 12345, ABC123, 0000123, 000-123 etc.

Will you use the ezprints shipping calculator?

<Y/N>

ezprints, inc. 7

Will you verify your offered shipping destinations against those listed by ezprints?

<Y/N>

Will you use only ezprints offered Shipping methods?

<Y/N>

URL to which you will post orders

<http://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyy> Or <https://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyy>

Will you use ezprints product codes?

<Y/N> It is recommended that you use ezprints product codes when submitting orders to us.

Will you use Auto Enhance?

<Y/N> ezprints utilizes I2E's solution to provide you with the option to Auto Enhance images. You may turn it on per order line in a given order.>

Will you use backprinting on your images?

<Y/N>

Please indicate which order status event notifications you would like to receive

Yes, would like to receive

Accepted AssetsCollected InProduction Canceled Complete Shipment Complete Shipment

URL for ezprints to post XML status replies to.

<If using status codes please provide a URL for ezprints to post the XML status updates to. Example http://www.yoursite.com/ezprintsstatusupdate.php>

Product families you plan to offer at launch

Prints

Gifts Cards Calendars Canvas

Have you read and do you agree to our testing requirements below?

<Y/N>

ezprints, inc. 8

Have you read and do you agree to our Go Live Agreement below?

<Y/N>

Testing Requirements Information ezprints provide a mechanism for testing interfaces without producing live

product. We ask that your integration team utilize those mechanism's first before producing live orders through our systems. We will ask you to complete the tests listed below prior to certifying you to Go Live into our production environment. It is important that you do not send Live orders to us prior to being certified as these orders may be held for extra inspection or put on hold as the team is not complete integrating you internally. The product test is designed to ensure that you are getting quality product through our systems, and that your interface submits the order correctly. The shipping test is designed to ensure that your interface correctly implements the shipping methods we support. 1. Submit a single order that contains one of each product and finish that you will be taking live on your site. Each order line should use a different image. Ship this order to your QA person for review. Please submit on a weekday between 9AM and 4PM EST to allow us to intercept the order. 2. Alert ezprints that you have submitted this order so that we may review it to ensure that there are no problems that we see with the integration, i.e. image orientation, cropping, etc.

Product Test

3. Send a confirmation email to the ezprints integration manager confirming your reciept and acceptance or concerns regarding the test order. Note fulfilment time will take longer as we are going to QA the order prior to shipping.

Shipping Test 1. Submit a single order for each shipping method you will use that contains one print (4x6 or similar). Please submit on a weekday between 9AM and 4PM EST to allow us to intercept the order. Notify your integration contact to ensure that they intercept the order. We will attempt to intercept this order and prevent it shipping. We are looking to ensure that you have implemented the shipping methods correctly in your interface.

Test Costs ezprints will credit up to two product test orders, and one single line item test order for each shipping method in the event that your shipping test fails. Once you have gone live your subsequent test orders will be handled on a case by case basis.

Go Live Agreement

Go Live Agreement You will not Go Live without an email confirmation from the integration manager that you have been certified to Go Live. Additionally you will not launch new products after going live without first producing a test order and reviewing it yourselves.

ezprints, inc. 9

New Partner Information Form

New Partner Information Form Instructions: Please complete all fields of this document, with the exception of the

Partner ID, which ezprints will assign. Return this document via email and please include a 200 x 400 pixel logo. This logo is used on product packing slips and is placed on the outside of your packages.

Partner Name: <Legal Name>-<Doing Business As> Physical Address

Partner ID: <To be assigned by ezprints> Billing Address

Partner URL: <Your Web Site Address> Contact Details

Contract Contact: <Name> Contact Phone: Contact Email: Account Contact <Name> Contact Phone:

Contact Email: Financial Contact <Name> Contact Phone:

Contact Email: Technical Contact <Name> Contact Phone:

Contact Email: Customer Care Manager <Name> Contact Phone:

Contact Fax: Contact Email:

Customer Care <Name> Customer Care Phone: Customer Care Fax: Customer Care Email: Integration Contact <Name> Contact Phone:

Contact Email: Partner Portal Contacts

ezprints offers a "partner portal" for members of your organization to use for tracking orders, requesting reprints, modifying shipping addresses, running reports, etc. Please provide a list of names and email addresses for those who should have access to this portal. Members of your customer care team should find the portal to be particularly useful. Each user should have a separate username and password, so you can track particular actions back to specific users. First Name Last Name Email address

ezprints, inc. 10

The table below provides an overview of the tasks to be completed during your integration. Many of the below tasks may be developed and completed simultaneously, depending on your development resources available. Integration Task Who Does it? Estimated Time to Complete Determine the products you wish to offer You, the partner 1 day + Determine your retail prices for the products

You, the partner 1 day +

Determine your retail shipping prices You, the partner 1 day + Build your website or application You, the partner 1 week + Configure your EZP partner account EZP Integration

Team 72 hours after receipt of required forms

Configure your shopping cart You, the partner 4 days + Integrate photo configurator(s) (Optional) You, the partner 2 days + Integrate EZP Shipping Calculator (recommended)

You, the partner 2 days +

Integrate EZP Products (not necessary if you are integrating EZP Product Configurators).


Integrate EZP Country and State Codes You, the partner ½ day +

Configure code to create order XML to send to EZP

You, the partner 1 day +

Configure code to post the XML order to EZP

You, the partner ½ day +

Configure code to accept/store Event Notifications (order status messages) (Optional)


Test posting order XML You, the partner, with the EZP Integration Team member

1 day +

Train your customer service team on the EZP Partner Portal and order support workflow

You, the partner 1 day

Posting XML Orders The general workflow for order fulfillment is:

Your customer places an order on your website or application; You bundle the order data into the EZP XML order format; You post the XML order to the EZP API; You receive a response to the post; The order is validated and unmarshalled into the EZP internal order processing system; The images are collected by the EZP Assets Collector; The order is sent to a printer in the Production Facility; The order is printed; The product is produced and finished, packaged and scanned at a shipping station; You may receive order status notifications (optional) as the order progresses through the

system; The order is then picked up by the shipping carrier and delivered to the recipient.

ezprints, inc. 11

Posting URLs You should post the order XML to either of these EZPrints APIs: http://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyy Or https://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyy PartnerNumber corresponds to the partnerID you are assigned when your EZP account is created. PartnerReference is your internal orderid you are passing to ezprints. You get a generated number (ezpreferencenum) in response. Assuming a successful post, the response to your post looks like this (reference number in bold): <?xml version="1.0" encoding="utf-8" standalone="yes"?><XmlOrder Reference="00000-200703070113-00060" /> The reference number is what identifies your order in the ezprints order system. Use this number when communicating with the ezprints Customer Care team about the order. This number will appear in any order status notifications you receive. All valid XML that you post is received, regardless of body content, so you will always get a referencenumber in response to the post. The XML is then validated and unmarshalled into our order system, approximately 2-20 minutes later. An internal EZP orderid is also assigned to your order when the XML is unmarshalled. You will receive a failure notification if the order posted was not successfully unmarshalled: <?xml version="1.0" encoding="utf-8" standalone="yes"?><XmlOrderFailed Reason="Invalid Xml" /> Further, if the PartnerNumber is left off of the URL (or it is not a number) this is the response: <?xml version="1.0" encoding="utf-8" standalone="yes"?><XmlOrderFailed Reason="Failed to retrieve query string parameters" /> It is recommended that you include in your design a way to resubmit orders from your website or application. This is to allow you flexibility in case you ever need to resubmit one or more orders that have failed to post or failed to be unmarshalled, for whatever reason.

Sending Your XML Order File You may submit XML Orders to EZPrints through an HTTP post. You may do this via HTTP Post using Microsoft’s XMLDOM Object (available for download at msdn.microsoft.com/xml). You may submit XML content with a content type of “text/xml” and the body of the post is the order xml. Or, you may submit from your server by mimicking a web form with content type of “form/encoded” with the XML encoded in the form variable. While you will have to discover the best way to do this based on technology you are using, we do offer some help by providing code samples in the Code Sample Library section.

ezprints, inc. 12

Duplicate Order Checking To protect against an inadvertent flood of duplicate orders, ezprints has a process to identify duplicate orders. Unless you specify otherwise, your account will automatically be set up to participate in EZP Duplicate Order Checking. When an order comes in, the Duplicate Order Check process looks for another order that is not deleted for the same partnerID, with the same ordersession, sessionid, and ordersession wholesaletotal values. If one is found, the order is marked as a duplicate and deleted (marked as deleted). For this reason, we recommend you send unique ordersession sessionids (your orderids).

Image Collection and Granting EZPrints Access to Your Images The ezprints Asset Collector will accept JPG or PNG files (it will attempt to save PNG files in JPG format). All images sent to printers in the Production Facility are in JPG or PDF format. When you submit your order XML, your image URI will point to the location of the images on your server. Based on that URI, EZPrints can pull images directly from your server using HTTP or FTP. Allowing ezprints to pull images from your server via HTTP or FTP relieves you of the burden of transferring images. The EZP Asset Collector will scan for new images throughout the day, so if an image is not available when it first looks, it will continue looking. Specifically, the Asset Collector tries 6 times every 10 minutes the first hour, then 28 more attempts every 6 hours after that for a total duration of just over one week. If the image is not in the location specified in the order images uri element, the orderline will eventually be marked as a Missing Image which will flag the order for attention from our Customer Care team, who will contact your Customer Care team about the order’s missing image. If your image server is setup to deny anonymous access, we can use a username/password combination or provide you with our IP address for IP filtering.

Order XML Format As mentioned earlier, EZP requires a particular XML format. The following is an overview of the ezprints order XML standard. A summary of the order structure is provided, along with an example of XML elements in an order, and a description of each element. Your EZP Integration Manager can also provide an the XML schema in the form of a .XSD file, if desired.

XML Structure: A high level structure of the EZP Order XML consists of these key elements:

• Orders o Images o Order Session

Vendor Customer Order

• Shipping Address • Orderline

The format is designed to accommodate multiple orders per ordersession if desired (e.g. your application or website customer places one order to be sent to her, one order to be sent to

ezprints, inc. 13

grandma at another address, and you bundle both orders into one ordersession). However, it is most common to send ezprints one order per ordersession. If you send one order per ordersession, it is recommended that your ordersessionID be the same as your internal orderID for clarity in reporting. Recall that you pass your orderID in the order XML post statement. The orderline element is a unique combination of Image + Product SKU. You will pass a quantity with the orderline. The challenge for some partners is if you offer a “package” of products that in your system is one productid (e.g. your product009 is a set of 2 4x6 prints, 1 8x10 and 1 sheet of address labels), it needs to be broken down into unique EZP productids per orderline. This is a high level view of the images and orderlines structures: Image1 Image2 Image3 Orderline1 = Image1 + ProductSKU1, quantity = 1 Orderline2 = Image1 + ProductSKU2, quantity = 2 Orderline3 = Image2 + ProductSKU2, quantity = 1 Orderline4 = Image3 + ProductSKU1, quantity = 2 Orderline5 = Image3 + ProductSKU4, quantity = 1, Etc.

Order Splitting Your individual order may be split into more than one production order within the ezprints order processing system. This is to allow for different product types to ship as soon as they are produced, without having to wait for other products to be produced. Listed below are the order categories that will be shipped separately:

• Small Format • Large Format • Magnets • Gift Items / Photo Merchandise • Canvas • Digital Offset / Indigo Press products (i.e. folded cards, calendars, photo books, etc) • Framed prints

When orders split, EZP includes a 2nd index print that informs the customer that additional packages will contain the remaining parts of their order.

Sample XML Set: Listed below is an example of an XML order. <?xml version="1.0" encoding="UTF-8"?> <orders partnerid = "xxxxx" version = "1"> <images> <uri id="3" title="Logo">http://www.ezprints.com/images/logo.jpg</uri> <uri id="5" title="My Photo">http://www.ezprints.com/images/0/0_5.jpg</uri> <uri id="6" title="A Photo">http://www.ezprints.com/images/0/123.jpg</uri> </images> <ordersession> <sessionid>1234</sessionid> <vendor logoimageid = "3"> <name>MyCompanyName</name> <address1>123 Any St.</address1> <address2>Apartment 3</address2> <city>Anytown</city> <state>PA</state>

ezprints, inc. 14

<zip>12345</zip> <countrycode>USA</countrycode> <phone>303-555-1212</phone> <email>[email protected]</email> <url>www.ezprints.com</url> </vendor> <customer> <customerid>1234</customerid> <title>Ms</title> <firstname>Jane</firstname> <lastname>Doe</lastname> <address1>123 Any St.</address1> <address2>Apartment 3</address2> <city>Anytown</city> <state>PA</state> <zip>12345</zip> <countrycode>USA</countrycode> <phone>303-555-1212</phone> <email>[email protected]</email> </customer> <order> <orderid>1234</orderid> <shippingaddress> <title>Ms</title> <firstname>Jane</firstname> <lastname>Doe</lastname> <address1>456 Another St.</address1> <address2>Unit D</address2> <city>Anothertown</city> <state>ON</state> <zip>B6B-4G3</zip> <countrycode>USA</countrycode> <phone>301-555-1212</phone> <email>[email protected]</email> </shippingaddress> <shippingmethod>FC</shippingmethod> <orderline productid = "10050" imageid = "5"> <description>5x7 Glossy Print</description> <productprice>1.95</productprice> <quantity>1</quantity> <position>fit</position> </orderline> <producttotal>1.95</producttotal> <shippingprice>5.95</shippingprice> <tax>0.00</tax> <ordertotal>1.95</ordertotal> </order> <producttotal>1.95</producttotal> <shippingtotal>5.95</shippingtotal> <taxtotal>0.00</taxtotal> <total>7.90</total> </ordersession> </orders>

Address Verification EZP performs address verification on the shipping addresses passed to us in your order XML. We do this to minimize returns as a result of bad addresses. If an order fails address verification, it is put on hold and marked as failed. It then shows up in a review interface that is checked by a team member at EZP. The team member can approve it as is, correct it, or reject it. If it gets rejected, it is tagged for the EZP Exception Office to investigate. They will try to contact the customer or partner to get a valid address.

ezprints, inc. 15

Address Verification checks the entire address, and beyond the obvious checks of zip code, city and state codes being correct, it expects the address2 field to be a part of the street address rather than some kind of name. Suite, apartment, box, must be in the address2 string of text. As a result of address verification, we added a <companyname> tag in our order XML (listed below in the XML Elements and Contents grid). This is the appropriate place for you to place company names so they will not be stripped out by address verification. Long addresses will now be wrapped onto the second line of a shipping label rather than being cut off.

ezprints, inc. 16

XML Elements and Content – For use without EZP Product Configurators: Listed below is a description of all of the XML elements and associated content. Optional fields not contained in the above XML spec have been included. Element Name Child Name Element

or Attribute?

Required? Element Cardinality

Description

orders Root element

Required Root element - one only.

The Orders element has a required partnerid attribute that will be assigned by ezprints. There is also a required version attribute. The current version number is "1". The Orders element normally contains only 1 ordersession child. The following items are children of an Order element.

orders images Element Required 1 or more. The Images element contains n uri children. This section provides a listing of a images used in the document. The URL’s submitted in the XML do not need to be URL-encoded. If any XML reserved characters are used in the URL, they must be replaced by the proper escape sequence. For example, the URL http://www.foo.com?id=1&name=test would need to be escaped to: http://www.foo.com?id=1&name=test

orders ordersession Element Required Normally only 1.

The ordersession element normally contains 1 order child. There is one customer per ordersession.

orders partnerid Attribute Required Only 1. your partner ID as assigned by ezprints version Attribute Required Only 1. current version = "1"

images Element Required Only 1. The Images element contains n uri children. This section provides a

listing of images used in the document. The URL’s submitted in the XML do not need to be URL-encoded. If any XML reserved characters are used in the URL, they must be replaced by the proper escape sequence. For example, the URL http://www.foo.com?id=1&name=test would need to be escaped to: http://www.foo.com?id=1&name=test

ezprints, inc. 17

Element Name Child Name Element or Attribute?


Description

images uri Element Required The content of this element should contain the URL pointing to a high resolution image.

uri id Attribute Required The images id is referenced in Orderlines element, e.g. this image is to go on this product. The uri id can contain numbers or letters.

uri title Attribute Optional Image title. 40 characters of the image title will appear as backprint on any RA4 print.

ordersession Element Required Normally

only 1. The ordersession element normally contains 1 order child. There is one customer per ordersession.

ordersession order Element Required One or more.

The Order element represents an order to be shipped to a single address, and therefore contains a required shippingaddress and n orderline children.

ordersession vendor Element Optional Only 1. Use this element to specify the vendor/brand to be printed on the packing slip and index print. If included, the vendor element has an required logoimageid attribute. The children of the Vendor element are self-explanatory. The Name element is required. All other children are optional.

ordersession customer Element Optional Only 1. Partner's customer information (customer who placed the order). All children of the customer element are optional. Not used for any billing purposes.

ordersession producttotal Element Optional Only 1. Sum of all the retail producttotal elements in the ordersession order(s). Not visible on the work order.

ordersession discounttotal Element Optional Only 1. Sum of all the retail discount elements in the ordersession order(s). Not visible on the work order.

ordersession shippingtotal Element Optional Only 1. Sum of all the retail shippingprice elements in the ordersession order(s). Not visible on the work order.

ordersession taxtotal Element Optional Only 1. Sum of all the tax elements in the ordersession order(s). Not visible on the work order.

ezprints, inc. 18



Description

ordersession total Element Optional Only 1. Sum of retail producttotal, shippingprice, and taxtoal elements in ordersession order(s). Not visible on the work order.

ordersession sessionid Element Recommended Only 1. This is normally the same value as partner's orderid in the order element, and printed on the work order. The datatype is alphanumeric and has a maximum length of 50 characters.

ordersession sessiondate Element Optional Only 1. Partner's session date or order date.

order Element Required One or more.

The Order element contains a required shippingaddress andn orderline children.

order orderid Element Optional but recommended.

This is the partner's order ID and is printed on the index print and the work order. The datatype is alphanumeric and has a maximum length of 50 characters. The orderid value is usually the same as the ordersession sessionid value. This facilitates lookup of an order using the partner order number if necessary.

order producttotal Element Optional Sum of all the retail productprice elements in the orderlines. Not visible on the work order.

order discount Element Optional Partner's discount amount they applied to customer's order (e.g. from a promotion code). Not visible on the work order.

order shippingprice Element Optional Partner's retail price for shipping method. Not visible on the work order.

order tax Element Optional Tax for this order. Not visible on the work order.

order ordertotal Element Optional Sum of retail producttotal, shippingprice, and tax. Not visible on the work order.

order comment Element Optional Use this element to place your marketing message to the customer on the right side of the work order/ packing slip. Maximum 500 characters.

ezprints, inc. 19



Description

order shippingmethod Element required Code of shipping method. Valid shipping codes are provided by ezprints. Current codes are FC,PM,SD,ON

order orderline Element Required One or more.

Each orderline element contains a product and an image. The product being ordered is defined by the required productid attribute. The imageid attribute corresponds to an id from the images node of the document. The product id values are defined by ezprints. A table of current product SKUs can be found in the Products Specifications Guide .

order shippingaddress Element Required Only 1. Only 5 children of the <shippingaddress> are required: address1, city, state (US and Canada only), countrycode, and zip. address1 and address2 print on shipping labels and have a 35 character limit. Valid state and country codes can be found in in the Shipping section of the Parnter XML Integration Overview packet.

vendor Element Optional Only 1. Use this element to specify the vendor/brand to be printed on the packing slip and index print. If included, the vendor element has an required logoimageid attribute. The children of the Vendor element are self-explanatory. The Name element is required. All other children are optional.

vendor logoimageid Atttribute Optional Only 1. The logoimageid specified here will print on the work order as a 3.3”wide x 2” high sticker. It prints smaller on an index print. If no logoimageid is specified in the Vendor element we will use your partner logo uploaded in the Partner Portal.

vendor name Element Required Only 1.

vendor address1 Element Optional Only 1.

vendor address2 Element Optional Only 1.

ezprints, inc. 20



Description

vendor city Element Optional Only 1.

vendor state Element Optional Only 1.

vendor zip Element Optional Only 1.

vendor countrycode Element Optional Only 1.

vendor email Element Optional Only 1.

vendor url Element Optional Only 1.

customer Element Optional Only 1. Partner's customer information (customer who placed the order). All children of the customer element are optional.

customer firstname Element Optional Only 1.

customer lastname Element Optional Only 1.

customer companyname Element Optional Only 1.

customer address1 Element Optional Only 1.

customer address2 Element Optional Only 1.

customer city Attribute Optional Only 1.

customer state Attribute Optional Only 1.

customer zip Attribute Optional Only 1.

customer countrycode Attribute Optional Only 1.

ezprints, inc. 21



Description

customer phone Attribute Optional Only 1.

customer email Attribute Optional Only 1.

Orderline Element Required One or more.

Each orderline element contains a product and an image. The product being ordered is defined by the required productid attribute. The imageid attribute corresponds to an id from the images node of the document. The product id values are defined by ezprints. A table of current products id’s can be found in the Products Specifications. The children are described below.

Orderline affiliatekey Element Optional Only 1. You can specify an affiliatekey to assign a number to a specific orderline. This affiliatekey will be included in event notifications that describe specific orderlines.

Orderline imageid Attribute Required Only 1. Refers to an image listed in the <images> element.

Orderline productid Attribute Required Only 1. ezprints product SKU

Orderline quantity Element Required Only 1. Used to specify multiple copies of this product-image combination.

ezprints, inc. 22



Description

Orderline position Element Required Only 1. Please specify one of two values: Crop or Fit . Crop means that the image will fill the entire print area with any excess cropped off. Fit means that the entire image will be fit to the printable area of the product, producing a white border where the aspect ratios are different from the product spec.If the position is not specified for an orderline, the default is Fit. Please see the Product Specifications section of this packet for information on each product's Crop or Fit setting.

Orderline productprice Element Optional Only 1. This optional element allows the partner to specify the retail price for a product. Not visible on the work order.

Orderline productname Element Optional Only 1. This optional element is used to give the partner the option of naming product items differently from ezprints. If this element is omitted, the default ezprints product description will be used. Custom product descriptions must include print size and paper finish (matte, glossy, lustre, metallic).

Orderline enhance Element Optional Only 1. Optional tag indicating whether or not an enhancement algorithm should be applied to the image before printing. Can be an empty, self closing element; existance of element indicates the direction to enhance this orderline's image.

shippingaddress Element Required Only 1. 5 children of Shippingaddress are required: address1, city, state (US and Canada only), countrycode, & zip.

ezprints, inc. 23



Description

shippingaddress companyname Element Optional Only 1. companyname, if sent, will appear on work order in the Ship To and To areas.

shippingaddress title Element Optional Only 1.

shippingaddress firstname Element Optional Only 1.

shippingaddress lasntame Element Optional Only 1.

shippingaddress address1 Element Required Only 1. Address1 and Address2 print on shipping labels and have a 30 character limit.

shippingaddress address2 Element Optional Only 1. Address1 and Address2 print on shipping labels and have a 30 character limit.

shippingaddress city Element Required Only 1.

shippingaddress state Element Required Only 1. Valid state and country codes can be found in the Shipping section of the Parnter XML Integration Overview packet.

shippingaddress zip Element Required Only 1.

shippingaddress countrycode Element Required Only 1. Valid state and country codes can be found in the Shipping section of the Parnter XML Integration Overview packet.

shippingaddress phone Element Optional Only 1.

shippingaddress email Element Optional Only 1.

ezprints, inc. 24

XML Product Specifications The following specifications provide the details necessary to order products via the ezprints, Inc. XML Integration Platform. The product specifications will provide you with the information necessary to submit the correct order XML, and ensure you have the information necessary to appropriately prepare and size your images for collection. We ask that you end-to-end test each product that you integrate before taking the product live in your business to ensure that you receive the results you expect.

Product Specification Layout Each product family is grouped and detailed in typically one or two pages. Each product contains a summary of key information about the product, an image of the finished product, a section listing the SKU numbers related to the product, a link to the images available to you for marketing purposes, and finally information related to submitting the product to the ezprints order collection interface. Image submission orientation layout for folded cards is described at the end of the document. The information included in each specification is as follows: Field Description Specification Name Short description of the product specification Product Family An internal grouping name used by ezprints for grouping like products Product Description Summary of the product offering Product Materials Description of the materials used to produce the product Comes with Work Order?

Does this product come with a work order? The work order details the products being manufactured and shipped with this order, as well as 500 characters of marketing text you submit.

Has Index Print? Does this product family come with an index print? The index print contains work flow information used in the manufacturing process as well as the branding information you submit.

Manufacturing Process Main Process used in the manufacturing of products in this product family.

Single or Multi-Image Does this product require more than one image to produce? Image Bleed Amount of image that may be lost as a result of trimming and cutting the

product. The value listed is “all around bleed”, meaning the total bleed on 2 sides.

Image Pixel Recommendation

ezprints recommended Pixels Per Inch dimensions to facilitate sending orders to the order collection interface. The images you submit should have at least the PPI indicated.

XML Orderline Notes Important notes specifically related to the submission of the product. Pay particular attention to any issues called out in this section.

XML Orderline sample Sample of the <Images> node that displays how file/image locations should be submitted to us in XML. Additionally the <orders> node will be documented showing everything necessary to order the product.

Additional Notes Any additional notes outlining important information to consider when adding the product to your offering.

Complementary products

Suggestions for other products that have been found to be popular choices when ordering this product.

SKU SKU number representing the product in the Product Description. This is the product code that is included in the XML being submitted.

Description ezprints product description of listed SKU (product code)

ezprints, inc. 25

Product Dimensions Physical product dimensions Image Dimensions The image dimensions that ezprints recommends you submit in order to

ensure consistent results. We do not recommend submission of images that do not meet the published image dimensions. Image dimensions include the recommended bleed area.

Please refer to the Product Specifications PDF file, which is a separate document. If you did not receive this, please ask your Integration Manager.

Index Print Items that include an index print will come with a separate print that looks similar to the image below. This contains information used in the production process as well as your company name and logo, order number, and customer Name. (“ezprints” does not appear on the index print when the order is submitted through your account)

Sample Index Print

Note: The format and inclusion of the index print is subject to change as is deemed necessary to support our production processes.

Work Order The work order is a packing slip that lists all of the products that were ordered. Comments can be inserted in the ordersession orders comment node of the XML, limited to 500 characters. This will appear in the Personal Message section of the Work Order with top left justification. Products that come with a work order will include a document that looks similar to the image below. As with the Index print, this will include your company name and logo or the company name and logo submitted in the vendor node of the XML order you submit to us. This document also provides you with the ability to include messaging to your customers. Your logo is automatically printed on the Work Order in a pre-kiss-cut location that is 3.5” wide x 2” high. This sticker is placed on the outside packaging when the item is packaged for shipment.

ezprints, inc. 26

This process takes place for all products that come with a work order. Your logo will also appear on the index prints, which comes with prints and framed prints, but there is no sticker on the packaging for those products. Note: The format and inclusion of the work order is subject to change as is deemed necessary to support our production processes. A Message of 500 Characters may be included on a Work Order. Note that this feature is only available on the work order. It is not available on index prints. If you wish to use this feature you include the comment element inside the orders/ordersession/order element in the order XML: <order> ... <orderline> ... </orderline>

<comment>Thank you for shopping at ezprints.com! If you are not satisfied with your order please contact customer service at 1-800-xxx-xxxx</comment>

</order>

ezprints, inc. 27

Sample Work Order

Back print On most RA4 products ezprints will include two lines of text. One line is reserved for use by ezprints for production and Quality Assurance workflow information. The second line is available to you, allowing you to include custom branding or messaging up to 40 characters.

ezprints, inc. 28

Image showing two lines of back printing

If you wish to provide custom back print text then include the “Title” element in the Images node of your XML submission. If no “Image Title” is supplied ezprints will use a combination of the file name and the domain name the image is retrieved from. Example of title attribute: <images>

<uri id="2" title="color.jpg">http://www.ezprints.com/images/color.jpg</uri> </images> All lowercase letters are transformed to capital letters. Only alpha-numeric characters, parenthesis, underscore, and dash are supported. All other characters are transformed into underscores. Supported characters in backprinting: ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz0123456789 ()_- Backprinting is done by dot matrix printers in machine font that is 10 characters per inch.

Watermark A watermark is a design or text inserted or imprinted on documents to prove authenticity or reduce fraud/forgery. Most small format prints include a watermark on the paper used. Wherever possible we use paper with the manufacturers’ watermark. The watermark is not present on many large format prints as the manufacturer has removed that option on commercial size Matte paper. This was due to an increasing demand to remove the watermark due to its visibility in commercial backlighting situations. The following matte print sizes are printed without a watermark:

ezprints, inc. 29

8x12 10x15 16x24 24x30 8x24 12x12 18x24 24x36 9x12 12x18 20x20 30x40 10x10 13x22 20x24 36x48 10x12 16x20 20x30 48x96

Water Mark Sample

Image Resolution Considerations ezprints uses a variety of printers and each line of printers has its own specifications. We preprocess your images to fit the product and printer where it will be produced. Canvas and gifts are printed at 150 PPI, prints at 300 PPI and digital offset products at 110 PPI. However, you can submit all images for all products at 300 PPI if this is easier for you.

Print Paper Considerations ezprints provides professional quality prints in Matte, Gloss, and Lustre finishes.

Paper Finishes Glossy Glossy photos are printed on coated paper with a very smooth, shiny reflective surface. Glossy finishes have a high-contrast appearance and look slick to the touch when not under glass. This finish has an excellent dynamic range and color – slightly more "pop" than the matte paper, though less noticeable once framed.

Descriptors: • Photos will have a shiny finish. • Colors are vibrant. • Images are crisp and sharp (assuming the original photo was in focus). • Glossy finish does not produce a textured look when scanned and converted to digital.

To remove fingerprints and smudges, you need to use a photo cloth and/or a liquid solution. (Rubbing a photo, no matter how soft the cloth is, can produce scratches).

• Glossy photos produce a glare, making them difficult to see from certain angles. Lustre Lustre paper is the premier paper most preferred by portrait and wedding photographers and is considered a professional-grade paper. Lustre is often considered the finish “between” matte and glossy, and has a slight gloss with a subtle, often pearl-like texture. Lustre paper has a deeper color-saturization than matte as well as a higher contrast and is thicker than consumer paper. Lustre includes copyright and professional watermarking.

Descriptors: • Fingerprints and smudges are not as visible.

ezprints, inc. 30

• Anti Glare • Pro Watermark • Pro Quality Paper • Great for framing • Excellent for wedding photos

Matte Matte finishes have a very smooth, non-glare finish. Matte finishes have a lower-contrast when printed and are often used to enhance the texture of a print.

Descriptors: • Fingerprints and smudges are not as visible. • Since most professional prints are printed on matte-finish paper, photos printed on

matte paper can have a more professional look. This is especially true with black and white photographs.

• Glare is significantly reduced with matte-finish prints.

Metallic Metallic paper has a glossy finish and metallic appearance that creates images with exceptional visual interest and depth.

Descriptors: • Century-plus image stability • Rich, vibrant colors

Because the different paper types we offer each have a different SKU, you can order different paper types within each order.

Image Manipulation (Sizing, Cropping, Auto-enhance) Functionality ezprints. provides cropping and image manipulation through the XML interface. We recommend that you size your images and display the appropriate previews of your images to your customers prior to submitting your order, however we do offer the functionality listed below to assist you as necessary. This document will give you the recommended image sizes for each product. If you use the suggested image dimensions, your image will be processed for production without our systems altering the size of the image. We recommend that you default to “Crop” unless your order requires you choose another option. If you don’t specify “Crop” or “Fit” the default will be “Fit”.

Crop Settings There are six total settings that may be used based the position of the primary subject in the image or the amount of image lost due to cropping. These are typically used if the aspect ratio of the image submitted is different from the print size ordered. With the exception of FIT, these settings are based on where the starting point for printing the image (anchor) begins. If a specific crop setting is not specified in the XML, then a default setting of FIT will be used. Crop settings include:

• Crop • TopLeft • TopRight • BottomLeft • BottomRight • Fit

ezprints, inc. 31

BottomLeft The anchor for the image is placed at the bottom left corner of the image. For example, if the image size is 4x6, the print range is then expanded to 4 inches to the right and 6 inches up for a portrait image, 6 inches to the right and 4 inches up for a landscape image. Whatever is not included at this point is cropped off. Sample XML: <orderline productid="30125" imageid="5"> <description>125 Photo Greeting Cards</description> <productprice>50.00</productprice> <quantity>2</quantity> <position>BottomLeft</position> </orderline> BottomRight The anchor for the image is placed at the bottom right corner of the image. For example, if the image size is 4x6, the print range is then expanded to 4 inches to the left and 6 inches up for a portrait image, 6 inches to the left and 4 inches up for a landscape image. Whatever is not included at this point is cropped off. Sample XML: <orderline productid="30125" imageid="5"> <description>125 Photo Greeting Cards</description> <productprice>50.00</productprice> <quantity>2</quantity> <position>BottomRight</position> </orderline> Crop The anchor for the image is placed at the center of the image. The print range is then expanded to fit the size of the print that was ordered. For example, if the image size is 4x6, then the printed area will be a 4x6 rectangle (for portrait images) or a 6x4 rectangle (for landscape images) centered on the image provided. Whatever is not included within the rectangular region is cropped off. Sample XML: <orderline productid="30125" imageid="5"> <description>125 Photo Greeting Cards</description> <productprice>50.00</productprice> <quantity>2</quantity> <position>Crop</position> </orderline> Fit This setting is used if the aspect ratio of the image submitted is different from the print size ordered and it is important to print the entire image without cropping. This is accomplished by reducing the image to fit the size print that was ordered. For this reason, there is no anchor position for this setting. When reducing an image, all sides of the image are reduced proportionally. For example, if your image size is 4”x7” and the desired print size is 4” by 6”, then the 7” part of your image will be reduced by one inch in order to FIT it onto the 6” paper size. The 4” side of the image will also be reduced by 4/7“ as the entire image is reduced proportionally. This will result in a 2/7” white border on each side for portrait images or top and bottom for landscape images.

ezprints, inc. 32

Sample XML: <orderline productid="30125" imageid="5"> <description>125 Photo Greeting Cards</description> <productprice>50.00</productprice> <quantity>2</quantity> <position>Fit</position> </orderline> TopLeft The anchor for the image is placed at the upper most left corner of the image. For example, if the image size is 4x6, the print range is then expanded to 4 inches to the right and 6 inches down for a portrait image, 6 inches to the right and 4 inches down for a landscape image. Whatever is not included at this point is cropped off. Sample XML: <orderline productid="30125" imageid="5"> <description>125 Photo Greeting Cards</description> <quantity>2</quantity> <position>TopLeft</position> </orderline> TopRight The anchor for the image is placed at the upper most right corner of the image. For example, if the image size is 4x6, the print range is then expanded to 4 inches to the left and 6 inches down for a portrait image, 6 inches to the left and 4 inches down for a landscape image. Whatever is not included at this point is cropped off. Sample XML: <orderline productid="30125" imageid="5"> <description>125 Photo Greeting Cards</description> <quantity>2</quantity> <position>TopRight</position> </orderline>

Auto Enhance Auto Enhance is essentially a set of filters that allows you to adjust the appearance (i.e. color, contrast, etc.) of an image on a per orderline basis. ezprints uses I2E to perform these enhancements. To turn off color correction/auto-enhance, simply remove the <enhance/> tag from your XML. If the <enhance/> tag is there, then our auto-enhance/color correction takes place. If the tag is missing, the default value is not to Auto Enhance. <orderline productid="10050" imageid="39"> <description>5 x 7 (Gloss)</description> <productprice>0.79</productprice> <quantity>1</quantity> <position>crop</position> <enhance> </enhance> </orderline>

ezprints, inc. 33

For detailed information regarding the Auto Enhance settings ezprints uses, please contact your account manager or customer service representative.

Sublimation The process of phase transition from a solid to a vapor. For example, images are transferred from a transfer sheet and onto a mouse pad via sublimation using a heating process that causes the ink on the transfer sheet to vaporize and bond with the material. Sublimation processes tend to produce highly durable products.

Image Orientation The following image is provided to illustrate Portrait and Landscape Image Orientations for those less familiar with the terms.

Portrait/Landscape Examples

Product Shots Product marketing shots are available for you to use in your application/website if you would like. Produt shots are available at http://prodshots.ezprints.com. Check back regularly for updates.

ezprints, inc. 34

Shipping and the ezprints Shipping Calculator

Shipping Methods Offered The following are the shipping methods and estimated delivery times offered by ezprints. We may change carriers from time to time. Use the two-letter code in your XML order file as content for the <shippingmethod> element.

Shipping Category (Shipping

Code)

Possible Shipping Carriers/Methods Used Expected Delivery Time

Domestic UPS Mail Innovations, USPS First Class Mail or FedEx SmartPost

7 to 10 Business Days Economy (FC)

International Access Worldwide 7 to 14 Business Days

Express (PM) Domestic USPS Priority Mail, Fedex Home Delivery, FedEx ExpresSaver

2 to 5 Business Days

Domestic FedEx 2 Business day delivery 2 Business Days 2-3 Day Option (SD) International FedEx International Economy 3-5 Business Days

(depends on country) Next Business Day (ON)

Domestic FedEx Standard Overnight (delivered in the afternoon of the next business day)

1 Business Day

Not all carriers/services provide tracking numbers, but for those carriers/services that provide door-to-door tracking numbers we will include them in shipment information for the order. P.O. Boxes and APO/FPO (military addresses) can only be shipped via Economy or Express methods.

The ezprints Shipping Calculator The ezprints real-time shipping calculator is designed to return shipping options and prices for available ship methods. The system is simple and straightforward and can be implemented on the partners’ site in a minimum amount of time assuming familiarity with ezprints’ XML order specification and HTTP posting procedure. It is designed to integrate with your order system at the point where totals are calculated. Your system posts a partially formed XML order to the shipping calculator in the same way that the final order is posted. The calculator formulates an xml string containing the service options and price for each option. The shipping calculator will return a string to the calling agent, or in the event of an error, an error message is returned in the place of the shipping options.

Instructions Once you have your XML order file creation and posting process tested and working, duplicate that process to post a test order to the production shipping calculator at: http://www.ezprints.com/ezpartners/shippingcalculator/xmlshipcalc.asp If it’s helpful, your Integration Manager can provide a page you can run locally that calls the ezprints Shipping Calculator. All nodes except the <shippingaddress> and <orderline> will be ignored by the calculator. For example, this order XML can be passed to the Shipping Calculator: <?xml version="1.0" encoding="UTF-8"?> <orders partnerid="xxxxx" version="1"> <images>

ezprints, inc. 35

<uri id="5" title="Paul">http://www.partner.com/images/paul.jpg</uri> <uri id="7">http://www.ezprints.com/greetings/665h.jpg</uri> </images> <ordersession> <sessionid>1234</sessionid> <sessiondate>11/7/2000 1:22:54 PM</sessiondate> <customer> <customerid>4</customerid> <title> </title> <firstname>Janet</firstname> <lastname>Doe</lastname> <address1>151 Elm Street</address1> <address2> </address2> <city>Loganville</city> <state>GA</state> <zip>30039</zip> <countrycode>USA</countrycode> <phone>678-405-5000</phone> <email> </email> </customer> <order> <orderid>1234</orderid> <shippingaddress> <customerid>4</customerid> <title> </title> <firstname>Janet</firstname> <lastname>Doe</lastname> <address1>151 Elm Street</address1> <address2> </address2> <city>Loganville</city> <state>GA</state> <zip>30039</zip> <countrycode>USA</countrycode> <phone>678-405-5000</phone> <email> </email> </shippingaddress> <orderline productid="10127" imageid="49"> <description>Puzzle</description> <productprice>22.00</productprice> <quantity>3</quantity> <position>fit</position> </orderline> <producttotal>100</producttotal> <tax>0.00</tax> <ordertotal>105.95</ordertotal> </order> <producttotal>100</producttotal> <shippingtotal>5.95</shippingtotal> <taxtotal>0.00</taxtotal> <total>105.95</total> </ordersession> </orders> And the response from the Shipping Calculator will look like this <?xml version="1.0"?> <shippingOptions> <order orderid="1234"> <option type="FC" price="9.95" shippingMethod="USFC" description="Express to United States"/> <option type="PM" price="9.95" shippingMethod="USPM" description="Express to United States"/>

ezprints, inc. 36

<option type="SD" price="15.95" shippingMethod="USSD" description="Second Business Day to United States"/> <option type="ON" price="23.95" shippingMethod="OVNT" description="Next Business Day to United States"/> </order> </shippingOptions> If you can read the response text from the Shipping Calculator, the XML you bundled to submit to the Shipping Calculator is correct. The resulting data in the response from the shipping calculator is the set of available shipping options and costs. Your application or process should then select which shipping option/cost it wants, based on what the customer selected, and add the shipping method code to the order XML in the shippingmethod and shippingtotal elements, similar to this XML: <shippingmethod>ON</shippingmethod> <shippingaddress> <firstname>Karen</firstname> <lastname>Darren</lastname> <address1>429 Sage Ave</address1> <address2>Apt. 400</address2> <city>Denver</city> <state>CO</state> <zip>80538</zip> <countrycode>USA</countrycode> <phone> </phone> <email> </email> </shippingaddress> <orderline productid="80468" imageid="3551124"> <description>Wedge 18x24</description> <productprice>42.95</productprice> <quantity>1</quantity> <position>crop</position> </orderline> </order> <producttotal>42.95</producttotal> <shippingtotal>23.95</shippingtotal> <discounttotal>0</discounttotal> The shipping cost is what we will charge you, the partner, for shipping and handling on the order, so if you want to modify this price to your customer that is up to you.

Available Shipping Services by Country Available shipping services by country are listed here: http://www.ezprints.com/EZPartners/specifications/shipping.asp If you send an invalid shipping method for a particular country, you will receive the following Failure to Unmarshal notification (if you’ve subscribed to this event notification): <orderfailed AffiliateID="99999"> <ordernumber>Partner Order Number</ordernumber> <referencenumber>99999-200901031121-00024</referencenumber> <message>4000 Error: </message> </orderfailed>

ezprints, inc. 37

Shipping Charges Shipping charges are re detailed here: http://www.ezprints.com/EZPartners/shipping.asp

State and Country Codes You should use the state and country codes listed here: http://www.ezprints.com/EZPartners/specifications/statesandcountries.asp

Order Statuses and Errors

Event Notifications ezprints offers you the option to subscribe to one or more event notifications. These are XML posts we send to a URL you specify. The notifications provide a status update on your orders. Each notification type may go to a separate URL you specify, or they can all go to the same URL. You would need to code your site to accept the XML post for event notifications and store/parse the data into your own order system, as well as send a message received response to the notifications. Remember that you can choose to track orders via the Partner Order Administration Tool initially, and later subscribe to event notifications. The events you can set up to receive notifications for are:

Event Notification Name

Description

Accepted Indicates that the order XML has been validated against business rules and accepted (successfully unmarshalled) into the EZP order processing workflow.

AssetsCollected Indicates that all assets (image files) have been collected for this order.

InProduction Indicates that the order has entered the production plant and will be printed soon.

Canceled Indicates that the order has been canceled.

Shipment Information about an individual shipment for the specified order. Lists SKUs (orderline-level info). Shipment lists product codes (SKUs) and shipment/tracking information. There would be a second notification sent for the same order that shipped separately.

CompleteShipment Indicates that order fulfillment is complete and contains shipment information about all orders in the session.

Complete Indicates that order fulfillment is complete. I.e., an individual order in the session has shipped. We distinguish this from "Shipping Complete" because you may just want a notification that the order is complete, but not all the shipping information about the order.

The event notification post requires either the word “Success” or “OK” to be written somewhere in your response to the post. The response should either contain the word “success” somewhere in the body of the response or the response must begin with “OK”.

ezprints, inc. 38

For example: <?xml version="1.0" encoding="UTF-8"?> <OrderEventNotificationReceived Result="Success"/> Without the success response, our event notification system will continue to post the notifications to your URL 10 times (sent every 30 minutes), so the event notification messages may be posted to you multiple times if we don’t receive the success/OK response. In other words, regardless of a successful response and due to the nature of Internet communications, you’ll want to be able to receive a duplicate event notification without it causing problems in your system. Although the Accepted, AssetsCollected, and InProduction notifications will be sent regardless of whether or not a response is received, the shipping notifications require successful responses in order for subsequent notifications to be sent. For example, if a Shipment notification is sent and a successful response is not posted to ezprints, we will not send the CompleteShipment and Complete notifications. In addition to the Event Notifications in the table above, ezprints also offers a Failed notification for orders with XML that contains one or more errors. If you subscribe to any of the notifications in the table above, you will also receive Failed notifications for bad order XML. Note that the event notifications in the table above are URL encoded, but the Failed notification is not. See the Code Samples library portion of this document for samples of the Event Notification message XML.

Order Error Codes The following errors may be returned by the ezprints order processing system if there is a problem validating or unmarshalling your order XML. The code and description will be sent in the Failed to Unmarshal event notification post:

ezprints Error Codes 6010 invalid xml - no greeting address1 6011 invalid xml - no greeting city 6012 invalid state code 6013 invalid xml - no greeting zip 6014 invalid country code 6015 Customer processing error with database or datatype 6016 invalid xml - no month for calendar 6017 invalid xml - no year for calendar 6018 Customer processing error with database or datatype 6019 invalid xml -no imageid 6020 invalid image id in orderline 6021 Customer processing error with database or datatype 6022 invalid xml - no productid 6023 invalid xml - bad product id 6024 invalid xml - no imageid 6025 invalid image id in orderline 6026 Processing error with database or datatype 6027 invalid xml - no Address1 6028 invalid xml - no city 6029 invalid state code 6030 invalid xml- no zip 6031 invalid country code 6032 invalid country code 6033 processing error with database or datatype

ezprints, inc. 39

6034 invalid xml - no shipping method 6035 invalid xml - no shipping method 6036 Processing error with database or datatype 6037 invalid xml - no shipping address 6038 XML not valid - no orderline elements 6039 processing error with database or datatype 6040 Vendor processing error with database or datatype 6041 no vendor logo path 6042 invalid image id in vendor data 6043 no vendor name 6044 invalid state code 6045 invalid country code 6046 Vendor processing error with database or datatype 6047 invalid state code 6048 invalid country code 6049 Customer processing error with database or datatype 6050 XML not valid - no order elements 6051 session processing error with database or datatype 6052 session processing error with database or datatype 6053 invalid or missing image id 6056 invalid or missing image uri 6057 invalid or missing image id 6058 Image processing error with database or datatype 6059 Processing error 6060 Processing error 6061 XML not valid - no orders or no affiliateid 6070 XML not valid - no orders or no affiliateid 6071 XML not valid - no orders or no affiliateid 6062 XML not valid - no images 6063 XML not valid - no order elements 6064 XML parse error 6065 Processing error

The Partner Order Administration Tool ezprints offers a Partner Order Administration Tool for your teams to use to track order status, evaluate your sales trends and make requests of the EZP Customer Care team. It will provide you better service through faster resolution of issues and more proactive communication. Features of the tool provide you with: • The power to resolve order problems immediately. • Transparent visibility into real-time order status. • Dashboards with sales charts showing sales progress down to the last 90 minutes. • Order search capability by date range, order status, customer name, email address, partner

order ID, etc. • Estimated delivery date based on shipping method. • Ability to request reprints, shipping upgrades and changes to the shipping address. • Problem order notifications that will map you directly to the order details page of the

problem order. • The ability to run order summary reports as well as detailed order reports.

The Partner Order Administration Tool is located here: http://partner.ezprints.com/Login.aspx Contact your Integration Manager if you have not received a login to the tool.

ezprints, inc. 40

Test/Validate Your Order XML The first step in technical integration is to create and submit XML test orders. This helps you establish valid XML according to the ezprints XML Order specification. Below are some tools and directions that will assist you in testing your XML orders before you are ready to post live orders. Please use realistic data in your orders – do not use unrealistic quantities or dollar amounts.

XML Test Order URL This page will validate your XML order and return and order summary or error when you post to it: http://www.ezprints.com/xmlorder/placetestorder.asp. See http://www.ezprints.com/xmlorder/placetestorder.asp to view a sample order summary so you can view a mockup of the order data as it looks in the Partner Portal. You can also paste your order xml into the cut/paste window provided, here: http://www.ezprints.com/EZPartners/specifications/xmltesting.asp. This will show you a mockup of what the order will look like from the partner portal. This page will not work if your XML uses ProjectIDs from the EZP Product Builders. Once your XML is valid you can post to the production API. Your account will be set up in Test Mode initially so no orders will go into the ezprints order processing system. It is important that you schedule time with your ezprints Integration Manager for testing. Testing requires close coordination because it takes place in the production environment and most test orders will need to be deleted, not produced. The below test grid shows how to test after your order XML is valid. It allows you to test your ability to post to the API, test the accuracy of your order data, and test your ability to receive order status notifications (optional).

Testing Prior to Go Live Initial Tests (Test Mode Tests)

Test Description Test Order #

1) Post XML order to EZP API - your account is in Test Mode

Ensure you are posting your order XML successfully to the EZP API and that you get the GUID response to the post.

Order #1

2) EZP Integration Tech will test validate the order XML by manually unmarshalling the order and checking it in the EZP order system.

Ensure that the XML can be successfully unmarshalled into the EZP order system and contains required data

Order #1

3) Normal automatic workflow or manual Image Collection once order is in EZP order system.

Ensure that the EZP Assets Collector (Image Collector) can collect images for your order

Order #1

Note: The above test order will be cancelled, not produced/shipped.

ezprints, inc. 41

Secondary Tests (Production Mode Tests)

Test Description Test Order #

1) Post XML order to EZP API - your account is in Production Mode

The order can unmarshal successfully and the data in the order fields is what we expect

Order #2

Note: The above test order will be cancelled and not produced/shipped.

.

2) (Optional): Event Notification Tests -- post orders to test the event notifications you wish to receive; actions vary - see below.

Testing receiving order status notifications from EZP.

Message Type - Post or Response?

Description Test Order #

Failed to unmarshal Post an order with an invalid state code, e.g. 'GF'.

Order #4

Accepted This notification will be posted to you about 2-20 minutes after the order is posted.

Order #3

AssetsCollected This notification will be posted to you about 10 to 120 minutes after the order is posted.

Order #3 *

InProduction This notification will be posted to you about 2-24 hours after the order is posted.

Order #3

Shipment Posted to you when the order is scanned out at our shipping station.

Order #3

CompleteShipment Posted to you when all parts of order have been scanned out at our shipping station.

Order #3

Canceled Posted to you when the order is cancelled from within our order administration system – provide your Integration Tech with the date and order # to cancel the order

Order #5

* -- assumes Order 3 contains 2 products that split and ship separately, such as prints and a mug. Orders 4 and 5 will be deleted.

Final Testing (End-to-End Testing)

End-to-end testing. This is defined as a user entering an order on your website or application (e.g. as your customer would do) and the order flows to us from your website or application as it would for a live order, without special intervention on your side or on our side. The order is produced and shipped to the address on the order. You will receive this order to inspect for product quality.

ezprints, inc. 42

1) Product Test Submit a single order that contains one of each product family that you will offer on your site. Each orderline should use a different image. Ship this order to your QA representative for review. For example, if you are offering the prints and canvas product families, you could submit a test order for one 4x6 print and one 11x14 canvas. If you wish to see multiple finishes, sizes, or specific items from the same product family, you may also order those; our minimum requirement for this test is one product per family.

Product families are Prints, Gifts, Folded Cards, Calendars, Canvas

Test Costs ezprints will credit up to two product test orders. Once you have gone live your subsequent test orders will be handled on a case by case basis.

After Your Website Goes Live After you have completed testing and been certified by the ezprints Integration Manager to Go Live, you can begin sending real orders for fulfillment. At that time you will be introduced to the ezprints Account Management team. Your Account Management team will be your first point of contact for any account, policy, pricing or process questions you may have.

Invoicing After your Go Live date you will be invoiced by the EZP Accounting Team per the terms of our agreement. Generally, we will invoice you on a monthly basis. The invoice will contain product–specific details for the preceding month (totals will be grouped by product). The invoice is emailed to you in PDF format. The Partner Portal contains a search function that allows you to view orders for a specified date range and to export to Excel or CSV. A sample invoice is pictured below.

ezprints, inc. 43

Sample Invoice – Page 1

ezprints, inc. 44

Sample Invoice – Page 2

For questions about specific orders, your Customer Care team should first access the Partner Order Administration Tool to research the order status. The tool is designed to take care of 90% of questions about orders. If they still have questions they should call or email the ezprints Customer Care team at the 800# or email address provided to you by your Account Management team.

ezprints, inc. 45

Code Sample Library

Posting Order XML HTTP Post using Microsofts' XMLDOM Object (available for download at http://msdn.microsoft.com/xml). If you're using ASP, you can easily post orders directly from your server and bypass the need for HTML forms. The following is a sample of how to do this in ASP using VBScript: ' -- Create the object Set xmlPost = server.CreateObject ("MSXML2.XMLHTTP") ' -- Open a "POST" connection to the EZPrints Server. xmlPost.Open "POST", "http://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyy“ or “https://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyy“ PartnerNumber corresponds to the partnerID and PartnerReference is the orderid you use (the orderid you are passing to us). You get a GUID (ezpreferencenum) in response. All XML is received, then unmarshalled into our order system later. You will receive immediate feedback if the order posted was not successful. The EZP orderid is assigned to your order when the XML is unmarshalled. ' -- send the xml xmlPost.send strXML ' -- Retrieve the response Response.Write xmlPost.ResponseText The above code assumes that strXML is the string you built from your order data in the format described in Order XML Format section.

Sample function that will post the XML correctly in VB.Net Public Shared Function PostString(ByVal Data As String, ByVal Url As String, ByVal encode As Encoding) As String Dim result As String Dim webRequest As WebRequest = WebRequest.Create(Url) webRequest.Method = "POST" Dim bdata As Byte() = encode.GetBytes(Data) webRequest.ContentLength = bdata.Length Using requestStream As Stream = webRequest.GetRequestStream requestStream.Write(bdata, 0, bdata.Length) End Using Using webResponse As WebResponse = webRequest.GetResponse Using memoryStream As MemoryStream = New MemoryStream Dim length As Long = FileTransfer.TransferBytes(webResponse.GetResponseStream, memoryStream, &H2000, Nothing, New TimeSpan(0, 5, 0), Nothing, Nothing, New WaitHandle(0 - 1) {}) result = encode.GetString(memoryStream.GetBuffer, 0, CInt(length)) End Using End Using Return result End Function Public Shared Function PostString(ByVal Data As String, ByVal Url As String) As String Return WebHelper.PostString(Data, Url, Encoding.UTF8) End Function

ezprints, inc. 46

If you put these two functions in a class and then call the 2nd function with your string and URL, it will return the result.

Event Notification XML Examples

Failure to Unmarshal Indicates that the order XML has failed to pass validation against business rules and was not accepted (successfully unmarshalled) into the EZP order processing workflow. <orderfailed AffiliateID="499"> <ordernumber>718362</ordernumber> <referencenumber>00123-200708031121-62724</referencenumber> <message>4002 Error: Type mismatch</message> </orderfailed> <orderfailed AffiliateID="499"> <ordernumber /> <referencenumber>00244-200708031403-63077</referencenumber> <message>6047 Invalid State Code in Customer Node. </message> </orderfailed>

Accepted Indicates that the order XML has been validated against business rules and accepted (successfully unmarshalled) into the EZP order processing workflow.. <OrderEventNotification Id="1176390"> <Order Id="12345" EZPReferenceNumber="00392-200806131301-31515"> <Accepted DateTime="2008-06-13T13:01:51.0000000" /> </Order> </OrderEventNotification>

AssetsCollected Indicates that all assets (image files) have been collected for an order. <OrderEventNotification Id="1176463"> <Order Id="12345" EZPReferenceNumber="00392-200806131318-31606"> <AssetsCollected DateTime="2008-06-13T13:32:28.0000000" /> </Order> </OrderEventNotification>

InProduction Indicates that the order has entered the production plant and will be printed soon. <OrderEventNotification Id="1176466"> <Order Id="12345" EZPReferenceNumber="00392-200806131244-31405"> <InProduction DateTime="2008-06-13T13:26:19.0000000" /> </Order> </OrderEventNotification>

Canceled Indicates that the order has been canceled.

ezprints, inc. 47

<OrderEventNotification Id="1169450"> <Order Id="12345" EZPReferenceNumber="00392-200806120000-24262"> <Canceled DateTime="2008-06-12T00:45:00.0000000" /> </Order> </OrderEventNotification>

Shipment Information about an individual shipment for the specified order. Recall that there may be multiple shipments for each of our partner’s orders because we split shipments based on products ordered. This notification lists SKUs (orderline-level info). Shipment lists product codes (SKUs) and shipment/tracking information. The example below is for 2 of the same product with 2 different images. <OrderEventNotification Id="1192206"> <Order Id="002005990205-8000048_12884641" EZPReferenceNumber="00392-200806191259-57994"> <Shipment DateTime="2008-06-20T08:45:03.0000000" Carrier="FEDEX" Service="Second Business Day: FedEX 2 Day" DeliveryMethod="FedEx HOME DELIVERY" TrackingNumber="200326870226813"> <Item Id="313358640" Sku="10102" PartnerSku="10102" Quantity="1" /> <Item Id="313358639" Sku="10102" PartnerSku="10102" Quantity="1" /> </Shipment> </Order> </OrderEventNotification> This notification is the second notification sent for the same order above, that shipped separately: <OrderEventNotification Id="1192839"> <Order Id="002005990205-8000048_12884641" EZPReferenceNumber="00392-200806191259-57994"> <Shipment DateTime="2008-06-20T13:29:20.0000000" Carrier="USPS" Service="Priority Mail" DeliveryMethod="USPS Priority Mail" TrackingNumber="9101132138798011187865"> <Item Id="313358638" Sku="10106" PartnerSku="10106" Quantity="1" /> </Shipment> </Order> </OrderEventNotification>

CompleteShipment Indicates that order fulfillment is complete and contains shipment information about all orders in the session. <OrderEventNotification Id="1275335"> <Order Id="12345" EZPReferenceNumber="00417-200807251106-97968"> <CompleteShipment DateTime="2008-07-27T12:36:04.0000000" Carrier="USPS" Service="First Class" DeliveryMethod="USPS First Class" TrackingNumber=""> <Item Id="313358638" Sku="10020" PartnerSku="10020" Quantity="1" /> </CompleteShipment> </Order> <Order Id="12345" EZPReferenceNumber="00521-200807251106-97968"> <CompleteShipment DateTime="2008-07-27T14:56:04.0000000" Carrier="USPS" Service="Economy" DeliveryMethod="USPS Economy" TrackingNumber=""> <Item Id="313358623" Sku="10022" PartnerSku="10022" Quantity="2" /> </CompleteShipment> </Order> <Order Id="12345" EZPReferenceNumber="00506-200807251106-97968"> <CompleteShipment DateTime="2008-07-27T18:17:04.0000000" Carrier="USPS" Service="First Class" DeliveryMethod="USPS First Class" TrackingNumber=""> <Item Id="313358678" Sku="40026" PartnerSku="40026" Quantity="1" /> </CompleteShipment> </Order> </OrderEventNotification>

ezprints, inc. 48

Complete Indicates that order fulfillment is complete. I.e., all individual orders in the session have shipped. We distinguish this from CompleteShipment because you may just want a notification that the order is complete (this notification), but not all the shipping information about the order (complete shipment notification). <OrderEventNotification Id="1176501"> <Order Id="12345" EZPReferenceNumber="00392-200806121805-27961"> <Complete DateTime="2008-06-13T13:24:15.0000000" /> </Order> </OrderEventNotification>

Example PHP code to receive & parse the Event Notification XML data <?php $xml=$HTTP_RAW_POST_DATA; $obj=simplexml_load_string($xml); echo "Obj:\r\n"; print_r($obj); echo "Test="; echo $obj->attributes()->Test; ?> When this XML is posted: <Order Test="true" /> It responds by printing out the entire xml object and then getting the Test attribute of the root element and its value. Link to the documentation for the SimpleXML functions the above sample code uses: http://us3.php.net/manual/en/book.simplexml.php

Shipping Calculator Code

Example Perl Code to Post to the Shipping Calculator // Generate an XML stringto send to EZPrints. $doc is a DOMDocument populated with // required EZPrints data. Alternatively the $ezPrintsXML string can be generated manually. $ezPrintsXML = $doc->saveXML(); // create a header array that specifies a blank content type. $header[] = "Content-type:"; // initialize CURL to use the EZPrints URL $ch = curl_init("http://www.ezprints.com/ezpartners/shippingcalculator/xmlshipcalc.asp"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Returns response data instead of TRUE curl_setopt($ch, CURLOPT_POST, true); // specify that POST should be used curl_setopt($ch, CURLOPT_HTTPHEADER, $header); // set the customized headers curl_setopt($ch, CURLOPT_POSTFIELDS, $ezPrintsXML); // use HTTP POST to send data $resp = curl_exec($ch); //execute post and get results as string into $resp variable curl_close ($ch); // close the curl object

ezprints, inc. 49

// $resp is the response from EZPrints. This will output that result echo $resp;

Calculate Panoramic Print Price (JavaScript) Pano Length = (Pano Height x Image Length)/Image Height So if you want to make a 10” high pano with a 1000x2000 image the length will be: (10 x 2000)/1000 = 20” long EZPrints will bill in 6” increments with a minimum of 12” so if the price for a 10” panorama is $2.00, the charge would be: Ceiling(20/6) * $2.00 or 4 * $2.00 = $8.00 Here is some actual JavaScript code that calculates this: var panoPrice = skuHash.get( sku ).price; var panoLength = " "; var panoInches = 0; var qty6InSegments = ""; var imgWidth = Number( item.originalWidth ); var imgHeight = Number( item.originalHeight ); var paperWidthInches = parseInt( skuHash.get( sku ).description ); var segmentLength = 6; if( imgWidth > imgHeight ) panoInches = ( imgWidth/imgHeight ) * paperWidthInches; else panoInches = ( imgHeight/imgWidth ) * paperWidthInches; qty6InSegments = Math.ceil(panoInches / segmentLength ); if (qty6InSegments < 2) qty6InSegments = 2; // Minimum length is 12 inches. panoPrice = ( skuHash.get( sku ).price * qty6InSegments) panoLength = Math.round(panoInches) + ' in long';

FAQs Q: What do I need to do to send orders to EZP? A: You must configure your application or website to http post XML orders to us in our specified format. Details are in the Integration Task List and Posting XML Order to ezprints sections. Q: How long does it take to set up and start sending orders? A: It depends on several factors, including the setup of your application or website, the number of ezprints products you will be offering and your development resources. Ballpark estimates are 7 days minimum effort. That timeframe will decrease as ezprints offers more quick-integration “widgets” like the Product Builders. Q: What products should I offer? A: Depending on your business it might be a good idea to select 5 or 6 products to launch that are best suited to your content and audience. You can then go back to add products to your offering based on the success of your launch products and customer demand. Q: What should I charge for photo products? A: We are putting together an MSRP list for our most popular products. Please check with your Sales Executive or Account Manager for details on when the MSRP list will be available.

ezprints, inc. 50

Q: I don’t have an order system but still want to integrate with EZP – how can I send orders? A: Right now your best option is to record your customer orders in Excel and have your developer code a tool to extract the order data and bundle into ezprints order XML format to post. Q: If I choose only a limited number of ezprints products for the launch, can I add products later? A: Yes! You can always add products to your application/website later on. ezprints is committed to offer fresh, new digital image products throughout the year to keep your customers interested

Q: How long does that take? A: Depending on your website and whether you use the ezprints Product Configurator, it will take between 2 hours and 7 days (including time for end-to-end testing). You must set up your application or website to offer the product, add to shopping cart and write new product information into the order XML you post. Q: Who do I contact? A: Please contact your Account Manager to coordinate testing new products and to receive pricing for new products.

Q: What shipping options should I offer on my site? A: It depends on your target users and what you want to charge them.. The EZP Shipping Calculator returns 1 to 4 shipping options and prices – whatever is available for the destination address and products in the order. Your application or website will select the available option that matches what your customer chose. So you can offer from 1 to 4 shipping options (economy, express, 2-3 day or 1 day) to your customers. Q: How do I know if the Product Builders are something I should integrate into my site? A: The ezprints Product Builders (http://ezpservices.com) are tools that let your customer edit/crop images on ezprints digital image products. If you want to give your customers an easy and detailed view of the product with their image on it, you should integrate the Product Builders. If your application or site offers more static image content it may not be necessary to provide a crop/edit tool to your end users. Q: How will I be billed for my orders? A: Your agreement terms will cover this, but in general an invoice will be sent on a monthly basis and contain product totals for orders shipped during the previous month. Please see the sample invoice in this document. Q: How do I test during integration? A: You should test posting your order XML and do an end-to-end product test as a minimum before going live. You may also need to test receiving order status notifications if you have subscribed to receive any. Please see the Testing section of this document for more details. Q: How do I know when an order has shipped? A: Your customer care team can access the Partner Order Administration tool to search for an order and view order statuses. Please contact your Account Manager for login information to the Partner Order Administration tool. Q: Whom do I notify if I submit an order and then want to cancel it? A: The Partner Order Administration tool allows you to request an order cancellation. If the order has not been produced it can normally be cancelled. Please see the Partner OA documentation for more information. Q: What do I do if an order is late or incorrect or has a quality issue? A: The Partner Order Administration tool allows you to request a reprint or an upgrade in shipping. Please see the Partner OA documentation for more information.

ezprints, inc. 51

Q: Who will be my first point of contact at ezprints? A: During Integration your first point of contact will be your ezprints Integration Manager. After you have gone live, your first point of contact for pricing, billing or policy questions will be your ezprints Account Manager. For order questions your first point of contact will be the Partner Order Administration Tool (additional questions about specific orders should be directed to the ezprints Customer Care team).

EZPrints FullIntegrationGuide-v2

Documents

Transcript of EZPrints FullIntegrationGuide-v2