# CloudApps API

This documentation describes the CloudApps API v1.0

# Table of content

# Getting started


To get started with Cloudprinter please register online here: Client registration

See how to register your app with Cloudprinter.com here: Register your app

# Basics


# RESTful API

The CloudApps API is RESTful. All API calls are implemented as HTTP post. The HTTP response codes 200 and 201 are positive responses, all other response codes must be considered as error. Data will only be returned for HTTP response code 200.

# Authentication

CloudApps use OAuth2 authentication method and each request to the API must include a valid Bearer Token. Read more about OAuth2 authentication for CloudApps.

# Request Data

All request data posted to the API must be in JSON objects. The documentation for each API call describes the request data parameters in detail.

# Return Data

Return data from the API is in JSON objects. The documentation for each API call describes the return values in detail.

# Content-type

Set content-type to application/json on all requests.

# Order calls


# List all orders https://api.cloudprinter.com/cloudapps/1.0/orders/

Request a list of all orders

Methods: GET, POST

Example JSON Request

{
}

Example JSON Response

[
    {
        "reference": "12346",
        "order_date": "2015-08-05 10:00:00",
        "state": "1",
        "state_code": "order_state_new"
    },
    {
        "reference": "12348",
        "order_date": "2015-08-05 10:00:00",
        "state": "1",
        "state_code": "order_state_new"
    }
]

Parameters None

Return values

Name Type Description
reference string the clients own order reference identifier
state string the order state. See state definitions
state_code string the text version of the order state
order_date string the time the order was added

HTTP status codes

Code Status Description
200 OK the request has succeeded
204 No content the requested order was not found
400 Bad request the request was invalid or parameters are missing
403 Forbidden the request was denied due to missing credentials

# Get order info: https://api.cloudprinter.com/cloudapps/1.0/orders/info

Request details on a specific order

Methods POST

Example JSON Request

{
    "reference": "12346"
}

Example JSON Response

{
  "reference": "123456",
  "state": "45",
  "state_code": "order_state_uploaded",
  "order_date": "2017-02-01 11:22:33",
  "email": "customer1@example.com",
  "is_cancelable": true,
  "addresses": [
    {
      "type": "delivery",
      "firstname": "John",
      "lastname": "Doe",
      "street1": "Example street",
      "zip": "1234",
      "city": "Example city",
      "country": "NL"
    }
  ],
  "items": [
    {
      "reference": "123561",
      "name": "Textbook PB A4 P BW TNR",
      "product_reference": "textbook_pb_a4_p_bw",
      "count": "1",
      "shipping_option": "DHL - National Standard (DE)",
      "tracking": "SA234425244",
      "is_reordable": false,
      "options": [
        {
          "option_reference": "total_pages",
          "note": "The total number of pages in a book",
          "type_name": "Total pages",
          "count": "24"
        },
        {
          "option_reference": "pageblock_80off",
          "note": "Pageblock paper 80gsm Offset",
          "type_name": "Main paper",
          "count": "24"
        },
        {
          "option_reference": "cover_finish_gloss",
          "note": "Cover lamination Gloss finish",
          "type_name": "Cover finishing",
          "count": "1"
        }
      ],
      "files": [
		{
		  "type": "cover",
		  "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
		  "md5sum": "4578c3ecf64e47581b175d542f8b0160"
		},
		{
		  "type": "book",
		  "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
		  "md5sum": "1ef89e74e628e223ae94aa4586330833"
		}
	  ]
    }
  ]
}

Parameters

Name Type Description Required
reference string the clients own order reference identifier required

Return values

Name Type Description
reference string the clients own order reference identifier
state string the order state. See state definitions
state_code string the text version of the order state
order_date string the time the order was added
email string the email address of the end consumer
is_cancelable boolean says whether the order can be canceled
Addresses Type Description
addresses array array of one or more address objects
addresses:type string the addres type (delivery)
addresses:firstname string firstname of the recipient
addresses:lastname string lastname of the recipient
addresses:street1 string Street
addresses:zip string zip
addresses:city string city
addresses:state string state - ANSI INCITS 38:2009 alpha-2
addresses : country string country - ISO 3166-1 alpha-2
Items Type Description
items array array of one or more item objects
items:reference string the clients item reference id
items:name string short description of the product
items:product_reference string the api reference of the product
items:count string the quantity of the item
items:shipping_option string the shipping option of the item
items:tracking string tracking code of the item
items:is_reordable boolean says whether the order can be reordered
Item options Type Description
options array array of zero or more option objects
options:option_reference string the option api reference
options:note string short description of the option
options:type_name string the name of the option category type
options:count string the quantity of the option on the item
Files Type Description
files array Array of one or more file objects
files : type string The type of file
files : md5 string Md5 sum of the file - used for validation
files : url string Url to the order file

HTTP status codes

Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
410 Gone the requested order was not found

# Add order: https://api.cloudprinter.com/cloudapps/1.0/orders/add

Add a new order including one or more items, adresses, options and files.

Note: Files are added with a URL from where Cloudprinter can fetch the files when the order has been accepted. A TLS encrypted HTTPS connection, use of an access key in the query string and use of a network access control list is recomented.

Example: "https://download.example.com/files/28fa76ff5a9e0566eaa1e11f1ce51f09"

Methods POST

Example JSON Request

{
    "reference": "12346",
    "email": "customer1@example.com",
    "addresses": [
        {
            "type": "delivery",
            "company": "Example company",
            "firstname": "Example firstname",
            "lastname": "Example lastname",
            "street1": "Example street 1234",
            "zip": "99999",
            "city": "Example city",
            "country": "DE",
            "email": "email@example.com",
            "phone": "12345678"
        }
    ],
    "items": [
        {
            "reference": "12346-1",
            "product_reference": "textbook_pb_a4_p_bw",
            "shipping_level": "cp_saver",
            "title": "A great book",
            "count": "5",
            "files": [
                {
                    "type": "cover",
                    "url": "https://download.example.com/files/9aade201b3a85ceec318b2240d5eb373",
                    "md5sum": "4578c3ecf64e47581b175d542f8b0160"
                },
                {
                    "type": "book",
                    "url": "https://download.example.com/files/c4b5a0b95114f40fc8c9d4e7cd504290",
                    "md5sum": "1ef89e74e628e223ae94aa4586330833"
                }
            ],
            "options": [
                {
                    "option_reference": "total_pages",
                    "count": "36"
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": "36"
                }
            ]
        }
    ]
}

Example JSON Response

{
    "reference": "12346"
}

Parameters

Name Type Description Required
reference string the clients own order reference identifier - this must be unique among all orders required
email string email address of end customer - used for sending tracking information required
price string end customer sales price ex. vat/tax pr item in selected currency - comma as decimal separator, used for customs optional
currency string the currency of the end customer sales price - ISO 4217 optional
hc string harmonized code - classify product according to Harmonized System optional
meta array meta data array for custom production parameters - only available for Enterprise clients optional
mode string order mode - valid values are: "live"(real order), "sandbox"(virtual order) optional
addresses
addresses array array of one or more address objects required
addresses : type string the type of address - valid values are: "delivery" required
addresses : company string end customers company name optional
addresses : firstname string end customers firstname required
addresses : lastname string end customers lastname 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 and CA 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 required
addresses : phone string end customers phone number - used in case of problems during delivery required
files
files array array of zero or more file objects optional
files : type string the type of file - valid values are: "delivery_note", "promotion", "reorder_doc" required
files : url string url to the order file required
files : md5sum string md5 sum of the file - used for validation required
items
items array array of one or more item objects required
items : reference string the clients own item reference identifier - this must be unique with in the order required
items : product_reference string the api reference of the product - valid values can be requested via Products Calls required
items : count string the number of copies to produce of this specific item required
items : shipping_level string the preferred shipping level - standard options are: "cp_postal", "cp_ground", "cp_saver", "cp_fast" (required if no "quote" hash is set) required
items : quote string A quote hash reference from a quote call. optional
items : title string the title of the product optional
items : price string end customer sales price ex. vat/tax in selected currency - comma as decimal separator, used for customs optional
items : currency string the currency of the end customer sales price - ISO 4217 optional
items : hc string harmonized code - classify product according to Harmonized System optional
items : reorder_cause string reorder cause for reorders - Read more optional
items : reorder_desc string additional description of the problem - Read more optional
items : reorder_order_reference string reference to the original order - Read more optional
items : reorder_item_reference string reference to the item in the original order - Read more optional
items files
items : files array array of one or more file objects required
items : files : type string the type of file - valid values are: "product", "cover", "book" 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 options
items : options array array of zero or more option objects optional
items : options : option_reference string the api reference of the option - "total_pages" required for books required
items : options : count string the number of times the specific option is used pr item required

Return values

Name Type Description
reference string the clients own order reference identifier

HTTP status codes

Code Status Description
201 Created the order registration was created with success
400 Bad request the request was invalid or parameters are missing

# Cancel order: https://api.cloudprinter.com/cloudapps/1.0/orders/cancel

Request cancellation of a specific order.

Methods POST

Example JSON Request

{
    "reference": "12346"
}

Parameters

Name Type Description Required
reference string the clients own order reference identifier required

HTTP status codes

Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
403 Forbidden the request was denied due to missing credentials
409 Conflict the request failed due to wrong order state
410 Gone the requested order was not found

# Order log: https://api.cloudprinter.com/cloudapps/1.0/orders/log

Request log data for a specific order.

Methods POST

Example JSON Request

{
    "reference": "12346"
}

Example JSON Response

[
    {
        "reference": "12346",
        "create_date": "2016-04-12 12:37:01",
        "state": "5"
    },
    {
        "reference": "12346",
        "create_date": "2016-04-12 12:37:02",
        "state": "6"
    }
]

Parameters

Name Type Description Required
reference string The clients own order reference identifier required

Return values

Name Type Description
reference string The clients own order reference identifier
create_date string The date the order was created
state string The order state. See state definitions

HTTP status codes

Code Status Description
200 OK The request has succeeded
204 No content The requested order was not found
400 Bad request The request was invalid or parameters are missing

# Order quote: https://api.cloudprinter.com/cloudapps/1.0/orders/quote

Request quote data for a list of items

Methods POST

Example JSON Request

{
    "country": "NL",
    "items": [
        {
            "reference": "ref_id_1234567",
            "product_reference": "textbook_pb_a4_p_bw",
            "count": "1",
            "options": [
                {
                    "option_reference": "pageblock_80off",
                    "count": "120"
                },
                {
                    "option_reference": "total_pages",
                    "count": "120"
                }
            ]
        }
    ]
}

Example JSON Response

{
  "price": "4.5412",
  "vat": "0.00",
  "currency": "EUR",
  "expire_date": "2018-02-18T15:32:58+00:00",
  "subtotals": {
    "items": "1.7912",
    "fee": "2.7500",
    "app_fee": "0.0000"
  },
  "shipments": [
    {
      "total_weight": "712",
      "items": [
        {
          "reference": "ref_id_1234567"
        }
      ],
      "quotes": [
        {
          "quote": "a1e771f2e375bc33b5385fcc8091a328481bc45f3bff13de96ba0e7585ff936f",
          "service": "Postal - Untracked",
          "shipping_level": "cp_postal",
          "shipping_option": "National Post - Int. Postal Untracked",
          "price": "4.2000",
          "vat": "0.0000",
          "currency": "EUR"
        },
        {
          "quote": "90aa928c65b6115e2fd76f5c3238381e42630fbe6cd137422db469fb070b5f7f",
          "service": "Express ground - Tracked",
          "shipping_level": "cp_ground",
          "shipping_option": "National Post - Int. Postal Tracked",
          "price": "6.2300",
          "vat": "0.0000",
          "currency": "EUR"
        },
        {
          "quote": "c6159e6c0a1b3e2d4ad7be940a327fb139351149e9f7ad7a1295a534cc37a4c3",
          "service": "Express fast - Tracked",
          "shipping_level": "cp_fast",
          "shipping_option": "DHL - International Express",
          "price": "14.5000",
          "vat": "0.0000",
          "currency": "EUR"
        }
      ]
    }
  ],
  "invoice_currency": "EUR",
  "invoice_exchange_rate": "1.0000"
}

Parameters

Name Type Description Required
currency string the currency of the price quote - ISO 4217 - default value is EUR optional
country string the country the order will ship to - ISO 3166-1 alpha-2 required
state string the state in the delivery country - ANSI INCITS 38:2009 alpha-2 - required for US and CA optional
items array array of item objects in the order required
items : reference string client item reference required
items : product_reference string the product api reference required
items : count string the product quantity required
items : options array array of option objects on a item optional
items : options : option_reference string the option api reference required
items : options : count string the option count required

Return values

Name Type Description Required
price string the total product sum for the order, ex shipping and incl VAT required
vat string the vat part of the total product sum required
currency string the currency of the price quote required
invoice_currency string the currency of the invoice for the order required
invoice_exchange_rate string the currency exchange rate between the quote currency and invoice currency required
expire_date string the quote expiration date, 48 hours after the request was made required
subtotals array array of objects - subtotals required
subtotals : items string the sum of the item cost for the order required
subtotals : fee string the sum of the fees for the order required
subtotals : app_fee string the sum of the app fees for the order required
shipments array array of objects - shipments (item bundles) required
shipments : total_weight string the calculated total weight of the shipment required
shipments : items array array of objects - the items contained in this shipment required
shipments : items : reference string the item reference required
shipments : quotes array array of objects - available shipping options required
shipments : quotes : quote string the unique quote id required
shipments : quotes : service string the service level - [Fastest, Normal, Economy] required
shipments : quotes : shipping_level string the shipping service level reference required
shipments : quotes : shipping_option string text description of the specific shipping option required
shipments : quotes : price string the price of the shipment required
shipments : quotes : vat string the vat part of the shipment required
shipments : quotes : currency string the currency of the price quote required

HTTP status codes

Code Status Description
200 OK the request has succeeded
204 No content the requested order was not found
400 Bad request the request was invalid or parameters are missing

# Product calls:

# List all products: https://api.cloudprinter.com/cloudapps/1.0/products

Request a list of all products already enabled for the account.

Methods GET, POST

Example JSON Request

{
}

Example JSON Response

[
  {
    "name": "Textbook CW A6 P BW",
    "note": "Textbook Casewrap (PUR, 3 mm board) A6 Portrait DIG BW 80OFF",
    "product_reference": "textbook_cw_a6_p_bw",
    "category": "Textbook BW",
    "from_price": "-",
    "currency": "EUR"
  },
  {
    "name": "Textbook CW A5 P BW",
    "note": "Textbook Casewrap (PUR, 3 mm board) A5 Portrait DIG BW 80OFF",
    "product_reference": "textbook_cw_a5_p_bw",
    "category": "Textbook BW",
    "from_price": "-",
    "currency": "EUR"
  }
]

Parameters None

Return values

Name Type Description
name string Product short name
note string Product long description
reference string Product API reference
category string Product category
from_price string Product from price
currency string The currency in ISO 4217

HTTP status codes

Code Status Description
200 OK The request has succeeded
204 No content The requested order was not found
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing credentials

# Product info: https://api.cloudprinter.com/cloudapps/1.0/products/info

Get detailed information on a single product. This includes price on the base product and available options, as well as specs on the product.

Methods POST

Example JSON Request

{
  "product_reference": "textbook_cw_a6_p_bw"
}

Example JSON Response

{
  "name": "Textbook CW A6 P BW",
  "note": "Textbook Casewrap (PUR, 3 mm board) A6 Portrait DIG BW 80OFF",
  "product_reference": "textbook_cw_a6_p_bw",
  "prices": [
    {
      "price": "3.3300",
      "min": "1",
      "max": "65535",
      "note": "Textbook Casewrap (PUR, 3 mm board) A6 Portrait DIG BW 80OFF",
      "reference": "-",
      "currency": "EUR",
      "price_unit": "Pr quantity"
    },
    {
      "price": "0.0150",
      "min": "1",
      "max": "65535",
      "note": "Pageblock paper 80gsm Offset",
      "reference": "pageblock_80off",
      "currency": "EUR",
      "price_unit": "Pr page"
    }
  ],
  "specs": [
    {
      "note": "Binding method / technology",
      "value": "CW - Casewrap",
      "reference": "binding"
    },
    {
      "note": "Bleed in mm",
      "value": "3",
      "reference": "bleed_in_mm"
    }
  ]
}

Parameters

Name Type Description Required
product_reference string The api reference of the product required

Return values

Name Type Description
name string Product short name
note string Product long description
reference string Product API reference
Name Type Description
prices array Array of price objects
prices : price string Product or option price
prices : min string Minimum item quantity range
prices : max string Maximum item quantity range
prices : note string Product long description
prices : reference string For options, the API reference
prices : currency string The currency in ISO 4217
prices : price_unit string The price unit type (Pr. Order, Pr. Item, Pr. Quantity, Pr. Page)
Name Type Description
specs array Array of spec objects
specs : note string Spec long description
specs : value string Spec value
specs : reference string Spec reference

HTTP status codes

Code Status Description
200 OK The request has succeeded
204 No content The requested order was not found
400 Bad request The request was invalid or parameters are missing

--

# Shipping calls:

# List all countries: https://api.cloudprinter.com/cloudapps/1.0/shipping/countries

Request a list of all countries that supported by cloudprinter.com

Methods GET, POST

Example JSON Request

{
}

Example JSON Response

{
    "shipping_countries": [
        {
            "country_reference": "AE",
            "note": "United Arab Emirates",
            "require_state": 0
        },
        {
            "country_reference": "AF",
            "note": "Afghanistan",
            "require_state": 0
        },
        {
            "country_reference": "AG",
            "note": "Antigua and Barbuda",
            "require_state": 0
        },
        {
            "country_reference": "AI",
            "note": "Anguilla",
            "require_state": 0
        },
        {
            "country_reference": "AL",
            "note": "Albania",
            "require_state": 0
        },
        {
            "country_reference": "AM",
            "note": "Armenia",
            "require_state": 0
        },
        {
            "country_reference": "AO",
            "note": "Angola",
            "require_state": 0
        },
        {
            "country_reference": "AQ",
            "note": "Antarctica",
            "require_state": 0
        },
        {
            "country_reference": "AR",
            "note": "Argentina",
            "require_state": 0
        }
    ]
}

Parameters None

Return values

Name Type Description
shipping_countries array List of countries
shipping_countries : country_reference string Country - ISO 3166-1 alpha-2
shipping_countries : note string The name of the country
shipping_countries : require_state boolean The '1' - if country has states, '0' - otherwise

HTTP status codes

Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing credentials

# List all states: https://api.cloudprinter.com/cloudapps/1.0/shipping/states

Request a list of all states depends on country

Methods GET, POST

Example JSON Request

{
    "country_reference": "US"
}

Example JSON Response

{
    "shipping_states": [
        {
            "state_reference": "AA",
            "note": "U.S. Armed Forces - Americas"
        },
        {
            "state_reference": "AE",
            "note": "U.S. Armed Forces - Europe"
        },
        {
            "state_reference": "AK",
            "note": "Alaska"
        },
        {
            "state_reference": "AL",
            "note": "Alabama"
        },
        {
            "state_reference": "AP",
            "note": "U.S. Armed Forces - Pacific"
        },
        {
            "state_reference": "AR",
            "note": "Arkansas"
        },
        {
            "state_reference": "AZ",
            "note": "Arizona"
        }
	]
}

Parameters

Name Type Description Required
country_reference string Country code - ISO 3166-1 alpha-2 required

Return values

Name Type Description
shipping_states array List of states
shipping_states : state_reference string State code - ANSI INCITS 38:2009 alpha-2
shipping_states : note string State name

HTTP status codes

Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing credentials

# List all shipping level: https://api.cloudprinter.com/cloudapps/1.0/shipping/levels

Request a list of all shipping levels

Methods GET, POST

Example JSON Request

{
}

Example JSON Response

{
    "shipping_levels": [
        {
            "shipping_level_reference": "cp_fast",
            "name": "Express fast - Tracked",
            "note": "Fast express - Fastest possible trackaed delivery - Cloudprinter shared"
        },
        {
            "shipping_level_reference": "cp_saver",
            "name": "Express saver - Tracked",
            "note": "Saver express  - Fast saver tracked delivery - Cloudprinter shared"
        },
        {
            "shipping_level_reference": "cp_ground",
            "name": "Express ground - Tracked",
            "note": "Ground express - Fast ground delivery - Cloudprinter shared"
        },
        {
            "shipping_level_reference": "cp_postal",
            "name": "Postal - Untracked",
            "note": "Postal - Untracked postal delivery - Cloudprinter shared"
        }
    ]
}

Parameters None

Return values

Name Type Description
shipping_levels array List of shipping levels
shipping_levels : shipping_level_reference string Shipping level reference
shipping_levels : name string Shipping level name
shipping_levels : note string Shipping level description

HTTP status codes

Code Status Description
200 OK The request has succeeded
400 Bad request The request was invalid or parameters are missing
403 Forbidden The request was denied due to missing credentials