Cloudprinter order API JSON

This documentation describes the Cloudprinter order API JSON 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. JSON document posted to the productions API.

The order document in JSON 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 JSON 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 JSON format

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

Example order JSON

json

{
    "order": {
        "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
        "id": "123456780000",
        "date": "2016-07-14 08:25:08",
        "priority": "2",
        "shipping_date": "2016-07-15 08:25:08",
        "creator": {
            "id": 1,
            "name": "Cloudprinter.com",
            "version": "2.2",
            "date": "2016-07-14 08:25:08"
        },
        "client": {
            "id": 1,
            "name": "Cloudprinter.com",
            "date": "2016-01-20 08:25:08",
            "reference": "d15ddd390457e4f581e0835a979465df"
        },
        "costs": {
              "currency": "EUR",
              "shipping": "4.2000",
              "items": "7.0000",
              "vat": "0.0000",
              "total": "11.2000"
        },
        "shipping": {
            "method": "fedex_national_2_day",
            "consignor": "The Book Company",
            "invoice": {
                "shipments": 1,
                "currency": "EUR",
                "total": "4.2000"
            },
            "proforma_invoice": {
                "currency": "EUR",
                "total": "14.0000",
                "weight": "173.6986"
            }
        },
				"addresses": [
            {
                "type": "delivery",
                "company": "Example company",
                "name": "Example name",
                "street1": "Example street 1234",
                "street2": "Building 5",
                "zip": "99999",
                "city": "Example city",
                "country": "US",
                "state": "NY",
                "email": "email@example.com",
                "phone": "12345678",
                "customer identification": ""
            }
        ],
       "files": [
            {
                "type": "shipping_label",
                "format": "pdf",
                "url":    "https://s3-eu-west-1.amazonaws.com/a484c8da5ea1ce9c1db76eb04fdfc055f1aeb3ae597e5c.cloudprinter.com/106733300030000/106733300030000_shipping_label.pdf",
                "md5sum": "1455a007e7806c17aaf319701ce7f764",
                "size": 58586
            }
        ],
        "items": [
            {
                "id": "123456780001",
                "count": 1,
                "title": "Building High-Availability RESTful Services",
                "product": "textbook_cw_a3_p_fc",
                "desc": "Textbook Casewrap (PUR, 3 mm board) A3 Portrait DIG FC 80OFF",
                "pages": "44",
                "files": [
                    {
                        "type": "cover",
                        "format": "pdf",
                        "url": "https://s3-eu-west-1.amazonaws.com/13b37bb1ed6d3403e158abe719b4f6d0.cloudprinter.com/29c1d90b21bd7c8d28ba1fd1ae7646eb_cover.pdf",
                        "md5sum": "4578c3ecf64e47581b175d542f8b0160",
                        "size": 20785
                    },
                    {
                        "type": "book",
                        "format": "pdf",
                        "url": "https://s3-eu-west-1.amazonaws.com/13b37bb1ed6d3403e158abe719b4f6d0.cloudprinter.com/29c1d90b21bd7c8d28ba1fd1ae7646eb_book.pdf",
                        "md5sum": "1ef89e74e628e223ae94aa4586330833",
                        "size": 77459
                    }
                ],
                "options": [
                    {
                        "option": "pageblock_80off",
                        "desc": "Pageblock paper 80gsm Offset",
                        "count": 44,
                        "type": "type_main_paper"
                    },
                    {
                        "option": "cover_finish_gloss",
                        "desc": "Cover lamination Gloss finish",
                        "count": 1,
                        "type": "type_book_cover_finish"

                    }
                 ],
                "reorder_desc": "damaged parcel",
                "reorder_order_id": "1046305470000",
                "reorder_item_id": "1046305470002",
                "reorder_cause": "reorder_shipping_item_damaged"
            }
        ]
    }
}

Parameters

Document root

Name	Type	Description	Required
order	object	Order information	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
shipping date	string	Date by which the order is expected to be shipped to the customer	optional

Creator

Name	Type	Description	Required
creator	object	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	object	Information on the client business	required
client : id	number	ID of the client business	required
client : name	string	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	string	Shipping cost	required
costs : items	string	Items cost	required
costs : vat	string	VAT cost	required
costs : total	string	Total cost	required

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 shipment total cost	required
shipping : invoice : total	string	Total shipment invoice cost	required
shipping : proforma_invoice	object	Information on the proforma invoice related to shipping	required
shipping : proforma_invoice : currency	string	The currency used in the proforma invoice (e.g., EUR)	required
shipping : proforma_invoice : total	string	Total amount specified in the proforma invoice	required
shipping : proforma_invoice : weight	string	Weight of the shipment related to the proforma	required

Addresses

Name	Type	Description	Required
addresses	array	Array of delivery address objects	required
addresses : type	string	Type of address - valid values are: "delivery"	required
addresses : company	string	End customers company name	optional
addresses : name	string	End customers name	required
addresses : street1	string	End customers street name	required
addresses : street2	string	End customers street name	optional
addresses : zip	string	End customers zip/postal code	required
addresses : city	string	End customers city name	required
addresses : state	string	End customers state name - ANSI INCITS 38:2009 alpha-2 - required for US	optional
addresses : country	string	End customers country - ISO 3166-1 alpha-2	required
addresses : email	string	End customers email address - used in case of problems during delivery	optional
addresses : 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

Items

Name	Type	Description	Required
items	array	Array with one or more item objects	required
items : id	string	Cloudprinters item id	required
items : count	number	The number of copies to produce of this specific item	required
items : title	string	The title of the item project	optional
items : product	string	The name of the product	required
items : desc	string	Short description text of the product	optional
items : pages	string	The number of pages in the book block	optional
items : files	array	Array with one or more file objects	required
items : files : type	string	The type of file - valid values are: "product", "cover", "book", "archive"	required
items : files : format	string	The format of file - valid values are: "pdf", "jpg", "zip"	required
items : files : url	string	URL to the product file for the specific item	required
items : files : md5sum	string	Md5 sum of the file - used for validation	required
items : files : size	number	Size of the file in bytes - used for validation	required
items : options	array	Array with zero or more option objects	optional
items : options : option	string	Productions product id for the addon	required
items : options : desc	string	Short description of the addon	required
items : options : count	number	The quantity of the addon required	required
items : options : type	string	Option category type reference	required
items : reorder_cause	string	A predefined set of reorder causes	optional
items : reorder_desc	string	Custom text to give more details on the issue	optional
items : reorder_order_id	string	Reference back to the original order id	optional
items : reorder_item_id	string	Reference back to the original item id	optional

Files

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

Name	Type	Description	Required
files	array	List of file objects	optional
files : type	string	The type of file - valid values are: "shipping_label", "promotion"	required
files : format	string	Format of the file in the order	required
files : url	string	URL to the order file	required
files : md5sum	string	Md5 sum of the file - used for validation	required
files : size	number	Size of the file in bytes - used for validation	required

Cloudprinter order API JSON ​

Getting started ​

Basics ​

Communication ​

Order JSON format ​

Example order JSON ​

Parameters ​

Document root ​

Creator ​

Client ​

Costs ​

Shipping ​

Addresses ​

Items ​

Files ​