View Page Code

XML Specifications

RSS

Modified on 2014/11/24 16:48 by jdibble Paths: Integration Categorized as Uncategorized

Home >
Integration >
XML Specification

XML Specifications

XML Structure

As mentioned earlier, EZP requires a particular XML format for partners who are not using the ezp ecommerce module. 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.

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

Orders
Images
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 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.

For partners who are not using the ezp Builder, 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 sample 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.

For partners using the ezp Builder, the orderline element in the XML is slightly different. These differences are explained in the ezp product builders section. The rest of the XML will be the same, regardless of whether or not you are using the ezp product builders.

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>
            <zip>12345</zip>
            <countrycode>USA</countrycode>
            <phone>303-555-1212</phone>
            <email>jane@host.com</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>jane@host.com</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>jo@hots.com</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>

XML Elements and Content

Listed below is a description of all of the XML elements and associated content. Many 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"
Element Name	Child Name	Element or Attribute?	Required	Element Cardinality	Description
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
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.
Element Name	Child Name	Element or Attribute?	Required	Element Cardinality	Description
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	Required	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 a 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.
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.
Element Name	Child Name	Element or Attribute?	Required	Element Cardinality	Description
order		Element	Required	One or more	The Order element contains a required shippingaddress and n orderline children.
order	orderid	Element	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.
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. A link to valid state and country codes can be found in the Shipping section of this document.
Element Name	Child Name	Element or Attribute?	Required	Element Cardinality	Description
vendor		Element	Required	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	Attribute	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 the logo you provide to your Integration Manager.
vendor	name	Element	Required	Only 1
vendor	address1	Element	Required	Only 1
vendor	address2	Element	Optional	Only 1
vendor	city	Element	Required	Only 1
vendor	state	Element	Required	Only 1
vendor	zip	Element	Required	Only 1
vendor	countrycode	Element	Required	Only 1
vendor	email	Element	Optional	Only 1
vendor	url	Element	Optional	Only 1
Element Name	Child Name	Element or Attribute?	Required	Element Cardinality	Description
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	50 character limit.
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
customer	phone	Attribute	Optional	Only 1	30 character limit.
customer	email	Attribute	Optional	Only 1
Element Name	Child Name	Element or Attribute?	Required	Element Cardinality	Description
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.
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.
shippingaddress	companyname	Element	Optional	Only 1	companyname, if sent, will appear on work order in the Ship To and To areas. 50 character limit.
shippingaddress	title	Element	Optional	Only 1
shippingaddress	firstname	Element	Optional	Only 1
shippingaddress	lastname	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 Web Service 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 Web Service Integration Overview packet.
shippingaddress	phone	Element	Optional	Only 1	30 character limit.
shippingaddress	email	Element	Optional	Only 1

XML Specifications

XML Specifications

Quick Links

XML Structure

Sample XML Set

XML Elements and Content