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 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
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 |
Costs
Name | Type | Description | Required |
---|---|---|---|
costs | object | Information on overall costs | required |
costs : currency | string | Currency of the transaction | required |
costs : shipping | number | Shipping cost | required |
costs : items | number | Items cost | required |
costs : vat | number | VAT cost | required |
costs : total | number | Total cost | required |
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 | object | 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 the shipment invoice | required |
shipping : invoice : total | number | Total shipment invoice cost | required |
shipping : proforma_invoice | object | Information on the proforma invoice | required |
proforma_invoice : currency | string | Currency of the proforma invoice | required |
proforma_invoice : total | number | Total amount of the proforma invoice | required |
proforma_invoice : weight | number | Weight of the shipment | 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 |