Cloudprinter Order API XML v2.1

# Cloudprinter order API XML

This documentation describes the Cloudprinter order API XML v2.1

# Table of content

Getting started
Basics
- Communication
Order XML format

# 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 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.1</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>
  <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>
  </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

Name	Type	Description	Required
apikey	string	API key specific to the production	required
id	string	Cloudprinters order id	required
date	string	Order date	required
priority	string	The number of days for production	optional

# Creator

Name	Type	Description	Required
creator	array	Information on the creator of the document	required
creator : id	number	ID of the creator service	required
creator : name	string	Name of the creator service	required
creator : version	string	Version of the document creator	required
creator : date	string	Date of document generation	required

# Client

Name	Type	Description	Required
client	array	Information on the client business	required
client : id	string	ID of the client business	required
client : name	number	Name of the client business	required
client : reference	string	The order reference of the client business	required
client : date	string	Order date registered by the client business	optional

# Address

Name	Type	Description	Required
address	array	List of delivery addresses	required
address : type	string	Type of address - valid values are: "delivery"	required
address : company	string	End customers company name	optional
address : firstname	string	End customers firstname	required
address : lastname	string	End customers lastname	required
address : street1	string	End customers street name	required
address : street2	string	End customers street name	optional
address : zip	string	End customers zip/postal code	required
address : city	string	End customers city name	required
address : state	string	End customers state name - ANSI INCITS 38:2009 alpha-2 - required for US	optional
address : country	string	End customers country - ISO 3166-1 alpha-2	required
address : email	string	End customers email address - used in case of problems during delivery	optional
address : phone	string	End customers phone number - used in case of problems during delivery	optional
addresses : customer_identification	string	End customers customer identification also known as CPF, CI, etc - Read more	optional

# Shipping

Name	Type	Description	Required
shipping	array	Information on shipping	required
shipping : method	string	The shipping carrier and service for the order	required
shipping : consignor	string	The consignor name for the shipping label	required
shipping : invoice	object	Information on shipping invoicing data	required
shipping : invoice : shipments	number	Expected number of shipments	required
shipping : invoice : currency	string	Currency of shipment total cost	required
shipping : invoice : total	string	Total shipment invoice cost	required

# Item

Name	Type	Description	Required
item	array	One or more items can be added	required
item : id	string	Cloudprinters item id	required
item : count	number	The number of copies to produce of this specific item	required
item : title	string	The title of the item project	optional
item : product	string	The name of the product	required
item : desc	string	Short description text of the product	optional
item : pages	string	The number of pages in the book block	optional
item : file	array	One or more files can be added	optional
item : file : type	string	The type of file - valid values are: "product", "cover", "book", "archive"	required
item : file : format	string	The format of file - valid values are: "pdf", "jpg", "zip"	required
item : file : url	string	URL to the product file for the specific item	required
item : file : md5sum	string	Md5 sum of the file - used for validation	required
item : file : size	number	Size of the file in bytes - used for validation	required
item : option	array	zero or more files can be added	optional
item : option : option	string	Productions product id for the addon	required
item : option : count	string	The quantity of the addon required	required
item : option : desc	string	Short description of the addon	required

# File

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

Name	Type	Description	Required
file	array	Zero or more files can be added	optional
file : type	string	The type of file - valid values are: "shipping_label", "promotion"	required
file : url	string	URL to the order file	required
file : md5sum	string	Md5 sum of the file - used for validation	required
file : size	number	Size of the file in bytes - used for validation	required