Cloudprinter order API XML

This documentation describes the Cloudprinter order API XML v2.2


Getting started

To get started with Cloudprinter please contact us at info@cloudprinter.com to get your account created. To each account is associated an API key, which is used as authentication in all API calls.


Basics

This API is Used for deliverying order from Cloudprinter to a production. XML document posted to the productions API.

The order document in XML format is posted at the productions order endpoint. The document consists of one order, one or more items and reference to the needed production files for the specific product.

Communication

The XML document is delivered with a HTTP POST request to a API endpoint over HTTPS or HTTP. The HTTP response code 200 indicate success, all other response codes are treated as error.


Order XML format

The order XML document containes all needed information for printing and shipping the products. This example is a very basic order with one item.

Example order XML

xml
<?xml version="1.0" encoding="UTF-8"?>
<order>
  <apikey>13b37bb1ed6d3403e158abe719b4f6d0</apikey>
  <id>123456780000</id>
  <date>2016-07-14 08:25:08</date>
  <priority>2</priority>
  <creator>
    <id>1</id>
    <name>CloudPrinter.com</name>
    <version>2.2</version>
    <date>2016-01-20 08:25:08</date>
  </creator>
  <client>
    <id>999</id>
    <name>YourCompany</name>
    <date>2016-01-20 08:25:08</date>
    <reference>d15ddd390457e4f581e0835a979465df</reference>
  </client>
  <costs>
    <currency>EUR</currency>
    <shipping>4.2000</shipping>
    <items>3.0240</items>
    <vat>3.2240</vat>
    <total>10.4480</total>
  </costs>
  <address>
    <company>Example company</company>
    <type>delivery</type>
    <name>Example name</name>
    <street1>Example street 1234</street1>
    <street2>Building 5</street2>
    <city>Example city</city>
    <zip>99999</zip>
    <country>US</country>
    <state>NY</state>
    <email>email@example.com</email>
    <phone>1234567890</phone>
  </address>
  <shipping>
    <method>fedex_national_2_day</method>
    <consignor>The Book Company</consignor>
    <invoice>
      <shipments>1</shipments>
      <currency>EUR</currency>
      <total>4.2000</total>
    </invoice>
    <proforma_invoice>
      <currency>EUR</currency>
      <total>6.0480</total>
      <weight>133.2472</weight>
    </proforma_invoice>
  </shipping>
  <item>
    <id>123456780001</id>
    <count>1</count>
    <title>Building High-Availability RESTful Services</title>
    <product>textbook_cw_a3_p_fc</product>
    <desc>Textbook Casewrap (PUR, 3 mm board) A3 Portrait DIG FC 80OFF</desc>
    <file>
      <type>cover</type>
      <format>pdf</format>
      <url>https://s3-eu-west-1.amazonaws.com/13b37bb1ed6d3403e158abe719b4f6d0.cloudprinter.com/29c1d90b21bd7c8d28ba1fd1ae7646eb_cover.pdf</url>
      <md5sum>4578c3ecf64e47581b175d542f8b0160</md5sum>
      <size>20785</size>
    </file>
    <file>
      <type>book</type>
      <format>pdf</format>
      <url>https://s3-eu-west-1.amazonaws.com/13b37bb1ed6d3403e158abe719b4f6d0.cloudprinter.com/29c1d90b21bd7c8d28ba1fd1ae7646eb_book.pdf</url>
      <md5sum>1ef89e74e628e223ae94aa4586330833</md5sum>
      <size>77459</size>
    </file>
    <pages>44</pages>
    <option>
      <option>pageblock_80off</option>
      <desc>Pageblock paper 80gsm Offset</desc>
      <count>44</count>
      <type>type_main_paper</type>
    </option>
    <option>
      <option>cover_finish_gloss</option>
      <desc>Cover lamination Gloss finish</desc>
      <count>1</count>
      <type>type_book_cover_finish</type>
    </option>
  </item>
</order>

Parameters

Document root

NameTypeDescriptionRequired
apikeystringAPI key specific to the productionrequired
idstringCloudprinters order idrequired
datestringOrder daterequired
prioritystringThe number of days for productionoptional

Creator

NameTypeDescriptionRequired
creatorarrayInformation on the creator of the documentrequired
creator : idnumberID of the creator servicerequired
creator : namestringName of the creator servicerequired
creator : versionstringVersion of the document creatorrequired
creator : datestringDate of document generationrequired

Client

NameTypeDescriptionRequired
clientarrayInformation on the client businessrequired
client : idstringID of the client businessrequired
client : namenumberName of the client businessrequired
client : referencestringThe order reference of the client businessrequired
client : datestringOrder date registered by the client businessoptional

Costs

NameTypeDescriptionRequired
costsobjectInformation on overall costsrequired
costs : currencystringCurrency of the transactionrequired
costs : shippingnumberShipping costrequired
costs : itemsnumberItems costrequired
costs : vatnumberVAT costrequired
costs : totalnumberTotal costrequired

Address

NameTypeDescriptionRequired
addressarrayList of delivery addressesrequired
address : typestringType of address - valid values are: "delivery"required
address : companystringEnd customers company nameoptional
address : firstnamestringEnd customers firstnamerequired
address : lastnamestringEnd customers lastnamerequired
address : street1stringEnd customers street namerequired
address : street2stringEnd customers street nameoptional
address : zipstringEnd customers zip/postal coderequired
address : citystringEnd customers city namerequired
address : statestringEnd customers state name - ANSI INCITS 38:2009 alpha-2 - required for USoptional
address : countrystringEnd customers country - ISO 3166-1 alpha-2required
address : emailstringEnd customers email address - used in case of problems during deliveryoptional
address : phonestringEnd customers phone number - used in case of problems during deliveryoptional
addresses : customer_identificationstringEnd customers customer identification also known as CPF, CI, etc - Read moreoptional

Shipping

NameTypeDescriptionRequired
shippingobjectInformation on shippingrequired
shipping : methodstringThe shipping carrier and service for the orderrequired
shipping : consignorstringThe consignor name for the shipping labelrequired
shipping : invoiceobjectInformation on shipping invoicing datarequired
shipping : invoice : shipmentsnumberExpected number of shipmentsrequired
shipping : invoice : currencystringCurrency of the shipment invoicerequired
shipping : invoice : totalnumberTotal shipment invoice costrequired
shipping : proforma_invoiceobjectInformation on the proforma invoicerequired
proforma_invoice : currencystringCurrency of the proforma invoicerequired
proforma_invoice : totalnumberTotal amount of the proforma invoicerequired
proforma_invoice : weightnumberWeight of the shipmentrequired

Item

NameTypeDescriptionRequired
itemarrayOne or more items can be addedrequired
item : idstringCloudprinters item idrequired
item : countnumberThe number of copies to produce of this specific itemrequired
item : titlestringThe title of the item projectoptional
item : productstringThe name of the productrequired
item : descstringShort description text of the productoptional
item : pagesstringThe number of pages in the book blockoptional
item : filearrayOne or more files can be addedoptional
item : file : typestringThe type of file - valid values are: "product", "cover", "book", "archive"required
item : file : formatstringThe format of file - valid values are: "pdf", "jpg", "zip"required
item : file : urlstringURL to the product file for the specific itemrequired
item : file : md5sumstringMd5 sum of the file - used for validationrequired
item : file : sizenumberSize of the file in bytes - used for validationrequired
item : optionarrayzero or more files can be addedoptional
item : option : optionstringProductions product id for the addonrequired
item : option : countstringThe quantity of the addon requiredrequired
item : option : descstringShort description of the addonrequired

File

The file section provides the general order level files, this could be a shipping label or promotional material.

NameTypeDescriptionRequired
filearrayZero or more files can be addedoptional
file : typestringThe type of file - valid values are: "shipping_label", "promotion"required
file : urlstringURL to the order filerequired
file : md5sumstringMd5 sum of the file - used for validationrequired
file : sizenumberSize of the file in bytes - used for validationrequired