Integration Guide
Before You Start
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 orders to EZP for fulfillment.
Currently, sending orders to EZP for fulfillment can be done in one of two ways:
- Use the EZP builder to allow customers to configure orders and then use your own shopping cart for the ecommerce transaction. Then post the orders to the EZP API.
- Use your own ecommerce system to generate product information and then post the orders to the EZP API.
This Integration Guide seeks to provide all the details necessary for all three of the methods mentioned above. Understand that not every detail in this guide will apply to you, depending on which option you choose.
The specific tasks you need to complete will also 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.
After configuring you site to post orders to EZP, 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 to ezprints, your integration can begin. The estimated time to complete each task depends on the starting point for your website or application. It also depends on whether you are planning to integrate any of the ezprints applications (e.g. ezp Builder), or if you're just submitting orders.
The ezp Builder is an image crop/edit tool that allows your end users to see what a product will look like with their image on it. The ezp Builders and the commerce module are described in detail at
ezpservices.com. The ezp Builder is 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 ezp Builder uses XML and Web services to talk to communicate with EZP servers.
To assist the EZP Integration Specialist you will work with, please complete the
New Partner Information Form. Return this form to your sales representative via email.
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 your retail product and shipping prices | You, the partner | 1 day + |
| Build the front-end of your website, which leads to product configuration | You, the partner | 1 week + |
| Deploy the ezp Builder or create your own product configurators | You, the partner | TBD, depending on decision |
| Configure your shopping cart | You, the partner | TBD, depending on decision |
| Integrate EZP Shipping Calculator | You, the partner | 2 days +< |
| Integrate EZP Country and State Codes | You, the partner | 1/2 day + |
| Configure code to create order XML to send to EZP | You, the partner | 2 days + |
| Configure code to post the XML order to EZP | You, the partner | 1/2 day + |
| Configure code to accept/store Event Notifications (order status messages) (Optional) | You, the partner | 2 days + |
| 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 |
Partner Go Live Task List
When integration is complete and you are ready to go live please follow these few steps to complete the set up process. Once this is complete your account will be in LIVE mode and all incoming orders will be treated as such.
To do this
- Login to the ezpTools site
- Click Account Settings then Builder Configuration
- Un-check the Test Mode check-box
- Save Changes
If you are using the ezprints cart please follow these steps.
- Login to the ezpTools site
- Click Account Settings then Super Admin
- Un-check the the "Bypass Authorization for Testing" checkbox
- Save Changes
Please email your account representative and integrationsupport@ezprints-inc.com when you have completed the steps above.
Posting URLs
You will need to post your order XML to EZP over http or https. You should post the order XML to either of these EZPrints APIs:
http://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyyOrhttps://order.ezprints.com/PostXmlOrder.axd?PartnerNumber=XXX&PartnerReference=yyyPartnerNumber 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:
<?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. If you receive a reference number in response to your post, EZP has the order in our database. If you did not receive a reference number, we did not receive the order. 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 a valid 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.
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 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. Allowing ezprints to pull images from your server via HTTP relieves you of the burden of transferring images.
For partners using the ezp Builder, your image URIs are specified in the ProjectId for each orderline, so you do not need to include the image URIs in the order XML. The rules above regarding image types still apply. For more details, see the ezp Builder deployment section.
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 or the ProjectId, 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 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. When orders split, EZP includes a 2nd index print that informs the customer that additional packages will contain the remaining parts of their order. Generally speaking, orders from different product families will ship separately. However, EZP is constantly tweaking the order splitting logic to ensure maximum efficiency in shipping times as well as cost savings for our partners.
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.
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.
Canada is the only international destination that is checked by the Address Verification system. All other international addresses (including Puerto Rico) as well as APO FPO are excluded.
As a result of address verification, we added a
<companyname> tag in our order XML (listed 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.