Producer Integration Guide

RSS
Modified on 2016/03/01 17:15 by rrao Categorized as Uncategorized

PRODUCER INTEGRATION GUIDE

Overview

EZPrints Fulfillment Manager (FM) supports advanced order fulfillment network routing capabilities. At a high level, we support receiving a single sales order, rendering images in a highly customizable way, and routing to multiple producers. This guide details how to become a producer in the fulfillment network. Producers are able to (1.) receive orders from FM and (2.) report order status information to FM.

Receiving Orders from FM

To receive orders from FM, two basic requirements must be met:

  • Expose an internet-facing HTTPS-based endpoint to receive HTTP POST requests containing orders in XML format.
    • The standard producer order XML format is documented below. If a custom integration is required which deviates from our standard, please contact integration support.
    • Web services or similar technologies may be utilized.
    • We recommend and support passing standards-based internet authentication as a part of the HTTP requests.
    • As necessary, our public IP addresses are available upon request for white-listing purposes.

  • In the HTTP response of the order POST request, return specific information in XML format regarding the received order.
    • The standard response XML is documented below. If a custom integration is required which deviates from our standard, please contact integration support.
    • The standard response requires the word "Success" to be written somewhere in the response to the POST.
    • The standard response requires an attribute located in the XML named 'Reference', which contains a unique identifier corresponding to the producer's internal ID for the recieved order. This field may be utilized for customer or technical support purposes.

Reporting Order Status to FM

To support sending order status to FM, we have a SOAP-based producer-focused web service located at the URI https://api.ezprints.com/producer.svc. At this link, you may access the WSDL in various formats for importing into your development tools. There are mandatory operations that producers must support, and optional operations which enhance customer support scenarios.

  • Mandatory operations:
    • CompleteOrderShipment - indicates a single producer order was shipped and specifies shipment information. Shipment information may include ship carrier, ship service, ship date/time in UTC format, and tracking information. Security credentials will be provided to you by your integration contact.
    • RejectOrder - indicates a single producer order is unable to be produced for some reason.

SAMPLE SOAP DOCUMENT - CompleteShipment
Datetime stamps must be set to UTC

    <s:Envelope>
      <s:Header>
        <a:Action s:mustUnderstand="1">http://www.ezprints.com/IProducerService/</a:Action>
        <a:MessageID>25E94F38-A191-4779-90C6-841DDA527680</a:MessageID>
        <a:ReplyTo>
          <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
        </a:ReplyTo>
        <a:To s:mustUnderstand="1">https://dev-api.ezprints.com/Producer.svc</a:To>
        <o:Security s:mustUnderstand ="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
          <u:Timestamp u:Id="_0">
            <u:Created>2015-11-23T15:31:25Z</u:Created>
            <u:Expires>2015-11-23T15:36:25Z</u:Expires>
          </u:Timestamp>
          <o:UsernameToken u:Id="C4BBE33A-158E-4991-9A38-C55034F8445F"/>
            <o:Username><<USERNAME>></o:Username>
            <o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"><<PASSWORD>></o:Password>
          </o:UsernameToken>
        </o:Security>
      </s:Header>
    <s:Body>
      <CompleteOrderShipment xmlns="http://www.ezprints.com">
        <requestDto xmlns:b="http://schemas.datacontract.org/2004/07/EZP.Fulfillment.Communication.Data" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
          <b:ProducerOrderKey><<ProduceOrderKey>></b:ProducerOrderKey>
          <b:Shipments>
              <b:ShipmentInfoDto>
                <b:CarrierName>UPS</b:CarrierName>
                <b:ShipDateTime>2015-11-23T15:28:12Z</b:ShipDateTime>
                <b:ShipMethod>Ground</b:ShipMethod>
                <b:TrackingNumber>1Z283429490234834</b:TrackingNumber>
                  <b:Weight>2</b:Weight>
              </b:ShipmentInfoDto>
          </b:Shipments>
        </requestDto>
      </CompleteOrderShipment>
    </s:Body>
    </s:Envelope>

  • Optional operations:
    • SetOrderAssetsCollected - indicates a producer has completed collecting the images for a single producer order.
    • SetOrderInProduction - indicates a producer has started fulfilling/producing a producer order.

Sample Standard Producer Order Request XML

Listed below is an example of an XML order you will receive in the body of the HTTP request.

<fo:ProducerOrder Reference="4059907" Key="P201509211436500351715XXX" xmlns:fo="http://messaging.ezprints.com/Schema/3.0/ProducerOrder">
  <fo:Extra>
    <Shipping Method="FC" />
  </fo:Extra>
  <fo:SalesOrder Key="S201509021425245621686XXX" OriginatorReference="AluminyzeTest001" CreateDateTime="9/2/2015 2:25:00 PM"CreateDateTimeFormatted="20150902022500" 
  OriginatorName="ez prints test " OriginatorNumber="405" LocationCode="" RetailCurrency="USD">
    <fo:Shipping>
      <fo:Address Address1="1890 Beaver Ridge cir" Address2="Suite B" City="Norcross" Company="" Country2="US" Country3="USA" PostalCode="30071"StateProvince="GA" />
      <fo:Contact Email="jdoe@test.com" Fax="555-555-1212" FirstName="John" LastName="Doe" Phone="555-555-1212" Title="" />
    </fo:Shipping>
    <fo:Vendor VendorUri="">
      <fo:Logo Id="64350728" Sort="logo" Type="Image" Uri="https://api.ezprints.com/GetAsset.ashx?Type=Producer&ProducerOrderKey=P201509211436500351715536&Key=logo&Track=True" FileSize="631" Width="10" Height="10" />
    </fo:Vendor>
    <fo:Message>This is the a message that should show up on a packing slip</fo:Message>
  </fo:SalesOrder>
  <fo:Shipping>
    <fo:Address Address1="1890 Beaver Ridge cir" Address2="Suite B" City="Norcross" Company="" Country2="US" Country3="USA" PostalCode="30071"StateProvince="GA" />
    <fo:Contact Email="jdoe@test.com" Fax="555-555-1212" FirstName="John" LastName="Doe" Phone="555-555-1212" Title="" />
  </fo:Shipping>
  <fo:OrderLine Key="1" Reference="59631536" Sku="S12X12" Quantity="1" Name="12x12 Aluminum 3/4" Wall Float - Glossy - White"Description="12x12 Aluminum 3/4" Wall Float - Glossy - White" ProjectId="14t8-dvcl-rn6v-z0rz" OriginatorDescription="12x12 Aluminum 3/4"Wall Float - Glossy - White">
    <fo:Product Type="Originator" Sku="87516" Name="" Description="" />
    <fo:Product Type="Sales" Sku="87516" Name="12x12 Aluminum 3/4" Wall Float - Glossy - White" Description="12x12 Aluminum 3/4" Wall Float - Glossy - White" />
    <fo:Product Type="Base" Sku="87516" Name="12x12 Aluminum 3/4" Wall Float - Glossy - White" Description="12x12 Aluminum 3/4" Wall Float - Glossy - White" />
    <fo:Product Type="Producer" Sku="S12X12" />
    <fo:Asset Id="64350781" Sort="1" Type="Image" Uri="https://api.ezprints.com/GetAsset.ashx?Type=Producer&ProducerOrderKey=P201509211436500351715536&ProducerOrderLineKey=1&Key=1&Track=True" FileSize="3380655" Width="1815"Height="1815" />
  </fo:OrderLine>
</fo:ProducerOrder>

Sample Standard Producer Order Response XML

Listed below are the recommended HTTP responses as a result of the order HTTP request.

Example successful response:
<OrderResponse Success="true" Reference="YourInternalOrderId" Message="" />

Example failed response:
<OrderResponse Success="false" Reference="" Message="Some error message pertaining to the order request" />

Producer Order XML Elements and Content

Listed below is a description of selected producer order XML elements and associated content.

Element NameChild NameElement or Attribute?RequiredElement CardinalityDescription
ProducerOrder ElementRequired Only 1Root element of producer order.
ProducerOrderKeyAttributeRequired Only 1Primary unique identifier for a producer order. We recommend you store this value in your internal systems for customer and technical support purposes.
ProducerOrderReferenceAttributeOptional Only 1Secondary identifier for a producer order. Not guaranteed to be unique.
ProducerOrderExtraElementRequired for physical delivery orders. Only 1Extra metadata associated with an order.
ProducerOrderVendorElementRequired for white label brandingOnly 1Contains Originator Logo information
LogoUriAttributeRequired for white label brandingOnly 1Originator Logo Uri
ExtraShippingElementRequired for physical delivery orders. Will be deprecated in future release. Only 1Contains information related to shipment commitment.
Extra/ShippingMethodAttributeIndicates shipping commitment level. Only 1Code of shipping method. Valid shipping codes are 'FC', 'PM', 'SD', and 'ON'. FC = first class, PM = priority mail, SD = second day, ON = overnight.
ProducerOrderSalesOrderElementRequiredOnly 1Contains information from the original sales order placed by the business partner's customer. All information should be ignored/not utilized by producer.
ProducerOrderShippingElementRequiredOnly 1Contains the order ship-to information.
ProducerOrder/ShippingAddressElementRequiredOnly 1Contains the order ship-to address.
ProducerOrder/ShippingContactElementRequiredOnly 1Contains the order ship-to customer details.
ProducerOrderOrderLineElementRequired1 or moreContains information about an order line item and associated digital assets.
OrderLineReferenceAttributeRequiredOnly 1FM internal reference for a producer order line. Uniquely identifies a producer order line within a single producer order.
OrderLineSkuAttributeRequiredOnly 1Alphanumeric code associated with product being ordered.
OrderLineQuantityAttributeRequiredOnly 1Units to produce
OrderLineDescriptionAttributeRequiredOnly 1Description of product sku being ordered.
OrderLineAssetElementRequired1 or moreDigital asset/file associated with order line. Number of Asset's depends on the product sku being ordered.
AssetIdAttributeRequiredOnly 1FM internal ID for a producer order line asset.
AssetSortAttributeRequiredOnly 1Specifies ordering of assets for an order item. I.e., some product skus may require a specific ordering of images (e.g., photo books).
AssetTypeAttributeRequiredOnly 1Indicates the general image category. Valid values are 'Raw', 'PDF', and 'Image'. We recommend using the content-type on the download asset HTTP request for determining exact file type.
AssetUriAttributeRequiredOnly 1URI to the high-resolution image.