Cloudprinter Core API

This documentation describes the Cloudprinter Core API v1.0

Table of content

Getting started


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

Basics


RESTful API

The Cloudprinter API is RESTful API. 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. Error descriptions can be returned on 4xx response codes.

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 descirbes the return values in detail.

Content-type

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

Authendication

Each request to the API contains an API key for authendication. API keys are created in the Cloudprinter admin system under CloudCore API Interface.

Order calls


List all orders https://api.cloudprinter.com/cloudcore/1.0/orders/

Request a list of all orders

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0"
}

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

Name Type Description Required
apikey string api access key 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

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 credentils

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

Request details on a specific order

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "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",
  "addresses": [
    {
      "type": "delivery",
      "firstname": "John",
      "lastname": "Doe",
      "street1": "Example street",
      "zip": "1234",
      "city": "Example city",
      "state": "Example state",
      "country": "NL"
    }
  ],
  "items": [
    {
      "reference": "123561",
      "name": "book_hardcover_21x21",
      "count": "1",
      "tracking": "FEDEX",
      "options": [
        {
          "type": "total_pages",
          "count": "24"
        },
        {
          "type": "gloss_pages_170g",
          "count": "24"
        },
        {
          "type": "gloss_laminate_cover",
          "count": "1"
        }
      ]
    }
  ]
}

Parameters

Name Type Description Required
apikey string api access key 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
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
addresses:country string ISO country code
Items Type Description
items array array of one or more item objects
items:reference string the clients item reference id
items:name string the name of the item
items:count string the quantity of the item
items:tracking string tracking code of the item
Item options Type Description
options array array of zero or more option objects
options:type string the option type
options:count string the quantity of the option

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/cloudcore/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"

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "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"
        }
    ],
    "files": [
        {
            "type": "delivery_note",
            "url": "https://download.example.com/files/28fa76ff5a9e0566eaa1e11f1ce51f09",
            "md5sum": "1ddec3ecf64e47581b175d552f6b016f"
        }
    ],
    "items": [
        {
            "reference": "12346-1",
            "product": "book_hardcover_21x30",
            "shipping_level": "cp_saver",
            "title": "Book Hardcover 21x30",
            "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": [
                {
                    "type": "total_pages",
                    "count": "36"
                },
                {
                    "type": "paper_130mcg",
                    "count": "36"
                }
            ]
        }
    ]
}

Parameters

Name Type Description Required
apikey string api access key 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
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 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
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 string the name 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
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 : ur 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 : type string the type of option - "total_pages" required for books, adding papertype eg. 130mcg is recomended required
items : options : count string the number of times the specific option is used pr item required

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/cloudcore/1.0/orders/cancel

Request cancellation of a specific order.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "reference": "12346"
}

Parameters

Name Type Description Required
apikey string api access key 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 credentils
409 Conflict the request failed due to wrong order state
410 Gone the requested order was not found

Order log: https://api.cloudprinter.com/cloudcore/1.0/orders/log

Request log data for a specific order.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "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
apikey string api access key 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 clients own order reference identifier
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/cloudcore/1.0/orders/quote

Request quote data for a list of items

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "country": "NL",
    "items": [
        {
            "reference": "ref_id_1234567",
            "product": "textbook_pb_a4_p_bw",
            "count": "1",
            "options": [
                {
                    "type": "pageblock_80off",
                    "count": "120"
                },
                {
                    "type": "total_pages",
                    "count": "120"
                }
            ]
        }
    ]
}

Example JSON Response

{
  "shipments": [
    {
      "price": "8.7300",
      "vat": "0.00",
      "currency": "EUR",
      "total_weight": "712",
      "expire_date": "2018-02-18T15:32:58+00:00",
      "items": [
        {
          "reference": "ref_id_1234567"
        }
      ],
      "quotes": [
        {
          "quote": "04b50524181f8d365a469daa6058d38a",
          "service": "Fastest",
          "text": "EU - FedEx Europe/International First",
          "shipping_quote": "11,80",
          "currency": "EUR"
        },
        {
          "quote": "1b3d6db969fbd72c9019176e0cbd78c7",
          "service": "Normal",
          "text": "EU - FedEx International Priority",
          "shipping_quote": "7,35",
          "currency": "EUR"
        },
        {
          "quote": "c1962f25ae4079d28f56d03b24529aa0",
          "service": "Economy",
          "text": "EU - FedEx International Economy",
          "shipping_quote": "4,90",
          "currency": "EUR"
        }
      ]
    }
  ]
}

Parameters

Name Type Description Required
apikey string api access key required
country string the country the order will ship to required
items array array of item objects in the order required
items : reference string client item reference required
items : product string the product id required
items : count string the product quantity required
items : options array array of option objects on a item optional
items : options : type string the option type required
items : options : count string the option count required

Return values

Name Type Description Required
shipments array array of objects - shipments (item bundles) required
shipments : total_weight string the calculated total weight of the shipment required
shipments : expire_date string the quote expiration date, 48 hours after the request was made 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 : text string a description of the shipping provider required
shipments : quotes : shipping_quote string the price 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/cloudcore/1.0/products

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

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0"
}

Example JSON Response

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

Parameters

Name Type Description Required
apikey string API access key required

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 credentils

Product info: https://api.cloudprinter.com/cloudcore/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.

Example JSON Request

{
  "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
  "name": "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",
  "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"
    },
    {
      "note": "Bleed in mm",
      "value": "3"
    }
  ]
}

Parameters

Name Type Description Required
apikey string Api access key required
name string The 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

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