This documentation page is in Beta

CloudPublish API

This documentation describes the CloudPublish API v1.0

Table of content

Getting started


To get started with CloudPublish API please contact our sales team: Click here

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

Content-type

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

Authentication

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

Catalog endpoints


Catalogs are collections of titles. Multiple catalogs can be created. The same title can be added to multiple catalogs. A catalog is linked to one specific Cloudprinter account.

When ordering a title the catalog reference code has to be specified.


List catalogs

https://api.cloudprinter.com/cloudpublish/1.0/catalogs

Request a list of all catalogs on the account. The API key is giving the link to the account.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0"
}

Example JSON Response

{
    "catalogs" : [
        {
            "catalog_reference" : "catalog_1",
            "name" : "First catalog",
            "note" : "The first catalog for all my titles",
            "create_date" : "2018-10-10T06:58:10+00:00",
            "modify_date" : "2018-10-10T06:58:10+00:00"
        },
        {
            "catalog_reference" : "catalog_2",
            "name" : "Second catalog",
            "note" : "The second catalog for all my titles"
            "create_date" : "2018-10-10T06:59:02+00:00",
            "modify_date" : "2018-10-10T06:59:02+00:00"
        }
    ]
}

Parameters

Name Type Description Required
apikey String API access key Required

Return values

Name Type Description
catalogs : catalog_reference String The reference code for the catalog
catalogs : name String The name of the catalog
catalogs : note String The description of the catalog
catalogs : create_date String The created timestamp - ISO 8601
catalogs : modify_date String The updated timestamp - ISO 8601

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

Get catalog details

https://api.cloudprinter.com/cloudpublish/1.0/catalogs/info

Request details on a specific catalog.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "catalog_reference" : "catalog_1"
}

Example JSON Response

{
    "catalog_reference" : "catalog_1",
    "name" : "First catalog",
    "note" : "The first catalog for all my titles",
    "create_date" : "2018-10-10T06:58:10+00:00",
    "modify_date" : "2018-10-10T06:58:10+00:00",
    "titles" : 2
}

Parameters

Name Type Description Required
apikey String API access key Required
catalog_reference String The catalog reference code Required

Return values

Name Type Description
catalog_reference String The catalog reference code
name String The name of the catalog
note String The description of the catalog
create_date String The created timestamp - ISO 8601
modify_date String The updated timestamp - ISO 8601
titles Number The number of titles in the catalog

HTTP status codes

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

Add a catalog

https://api.cloudprinter.com/cloudpublish/1.0/catalogs/add

Add a new catalog to the account. The proterty catalog_reference must be unique within the same account. The catalog_reference is used in all call to title endpoints.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "catalog_reference" : "catalog_1",
    "name" : "First catalog",
    "note" : "The first catalog for all my titles"
}

Example JSON Response

{
    "status" : {
        "catalogs" : {
            "added" : 1
        }
    }
}

Parameters

Name Type Description Required
apikey String API access key Required
catalog_reference String The catalog reference code - Max 128 chars Required
name String The name of the catalog - Max 64 chars Required
note String The description of the catalog - Max 256 chars Required

Return values

Name Type Description
status : catalogs : added Number The number of catalogs added

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 a unique key conflict

Remove a catalog

https://api.cloudprinter.com/cloudpublish/1.0/catalogs/remove

Remove a catalog from the account. Title available in the catalog will no longer be available.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "catalog_reference" : "catalog_1"
}

Example JSON Response

{
    "status" : {
        "catalogs" : {
            "removed" : 1
        }
    }
}

Parameters

Name Type Description Required
apikey String API access key Required
catalog_reference String The catalog reference code Required

Return values

Name Type Description
status : catalogs : removed Number The number of catalogs removed

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
410 Gone The element referenced is gone

Title endpoints


Title are the ISBN entries on the catalogs. Titles are linked to a catalog, a Product Mix, and a set of file.

When ordering a title the ISBN is the reference needed.


List titles

https://api.cloudprinter.com/cloudpublish/1.0/titles

Request a list of all titles available in the specific catalog.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "catalog_reference" : "catalog_1"
}

Example JSON Response

{
    "titles" : [
        {
            "isbn" : "1234567890123",
            "title" : "The book - Vol 1",
            "version" : 1,
            "create_date" : "2018-10-10T06:58:10+00:00",
            "modify_date" : "2018-10-10T06:58:10+00:00",
            "catalog_reference" : "catalog_1",
            "catalog_name" : "First catalog"
        },
        {
            "isbn" : "1234567890124",
            "title" : "The book - Vol 2",
            "version" : 1,
            "create_date" : "2018-10-10T06:58:10+00:00",
            "modify_date" : "2018-10-10T06:58:10+00:00",
            "catalog_reference" : "catalog_1",
            "catalog_name" : "First catalog"
        }
}

Parameters

Name Type Description Required
apikey String API access key Required

Return values

Name Type Description
titles : isbn String The ISBN number of the book
titles : title String The name of the title
titles : version Number Version number
titles : catalog_reference String The catalog reference
titles : catalog_name String The catalog 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

Get title details

https://api.cloudprinter.com/cloudpublish/1.0/titles/info

Request details on a specific title.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "isbn" : "1234567890123"
}

Example JSON Response

{
    "isbn" : "1234567890123",
    "title" : "The book - Vol 1",
    "version" : 1,
    "pages" : 244,
    "used_count" : 142,
    "create_date" : "2018-10-10T06:58:10+00:00",
    "modify_date" : "2018-10-10T06:58:10+00:00",
    "product_mix_reference" : "product_mix_test",
    "catalog_reference" : "catalog_2",
    "catalog_name" : "First catalog",
    "files" : [
        {
            "url" : "https://download.clp/2036b1bc48663b7837ce49bccd689f82/book",
            "size" : 10452964,
            "md5sum" : "12859c11fef78416133bde3980fd7367",
            "type" : "book",
            "format" : "pdf"
        },
        {
            "url" : "https://download.clp/2036b1bc48663b7837ce49bccd689f82/cover",
            "size" : 1734882 ,
            "md5sum" : "0d86d2917eede2343a08306db63b17d0",
            "type" : "cover",
            "format" : "pdf"
        }
    ]
}

Parameters

Name Type Description Required
apikey String API access key Required
isbn String The title reference code Required

Return values

Name Type Description
isbn String The title reference code
title String The name of the title
version Number Version number
pages Number Number of pages in the title
used_count Number Number of times the title was used in an order
create_date String The created timestamp - ISO 8601
modify_date String The updated timestamp - ISO 8601
product_mix_reference String The Product Mix reference
catalog_reference String The catalog reference
catalog_name String The catalog name
files Array Array of one or more file objects
files : url String The URL where the files is imported from
files : size Number The size of the file
files : md5sum String The MD5 sum of the file
files : type String The type of file - Valid values are: "cover", "book"
files : format String The format of the file - Valid values are: "pdf"

HTTP status codes

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

Add a title

https://api.cloudprinter.com/cloudpublish/1.0/titles/add

Add a new title to the account. The proterty catalog_reference must be unique within the same account. The isbn is used in all call to title endpoints.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "isbn" : "title_1",
    "name" : "First title",
    "note" : "The first title for all my titles"
}

Example JSON Response

{
    "status" : {
        "titles" : {
            "added" : 1
        }
    }
}

Parameters

Name Type Description Required
apikey String API access key Required
isbn String The title reference code - Max 128 chars Required
name String The name of the title - Max 64 chars Required
note String The description of the title - Max 256 chars Required

Return values

Name Type Description
status : titles : added Number The number of titles added

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 a unique key conflict

Remove a title

https://api.cloudprinter.com/cloudpublish/1.0/titles/remove

Remove a title from the account. Title available in the title will no longer be available.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "isbn" : "title_1"
}

Example JSON Response

{
    "status" : {
        "titles" : {
            "removed" : 1
        }
    }
}

Parameters

Name Type Description Required
apikey String API access key Required
isbn String The title reference code Required

Return values

Name Type Description
status : titles : removed Number The number of titles removed

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
410 Gone The element referenced is gone

Product Mix endpoints


Product Mixes are an abstraction on top of products and product options. A Product Mix defines one product with a fixed set of options. The concept can be compared to a SKU or PLU.

When a title is added to a catalog, the title references a product mix. This links the specific title to a specific product and a specific set of product options.


List Product Mixes

https://api.cloudprinter.com/cloudpublish/1.0/products/mixes

Request a list of all Product Mixes available for the specific account.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0"
}

Example JSON Response

{
    "mixes" : [
        {
            "product_mix_reference" : "product_mix_test",
            "name" : "Mix test",
            "note" : "A product and some options"
        }
    ]
}

Parameters

Name Type Description Required
apikey String API access key Required

Return values

Name Type Description
mixes Array Array of one or more Product Mix objects
mixes : product_mix_reference String The reference code for the Product Mix
mixes : name String The Product Mix name
mixes : note String The Product Mix 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

Product Mix details

https://api.cloudprinter.com/cloudpublish/1.0/products/mixes/info

Details on a specific Product Mix

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "product_mix_reference" : "textbook_a4_cw_matte_80gsm"
}

Example JSON Response

{
    "product_mix_reference" : "textbook_a4_cw_matte_80gsm",
    "name" : "Textbook A4 Casewrap - Basic",
    "note" : "Textbook, A4, Casewrap, Matte cover finish, 80gsm offset, 130gsm gloss cover",
    "product" : {
            "name" : "Textbook CW A4 P BW TNR",
            "note" : "Textbook Casewrap A4 Portrait Digital Toner BW"
    },
    "options" : [
        {
            "name" : "Cover finish Matte",
            "note" : "Cover lamination Matte finish"
        },
        {
            "name" : "Pageblock 80OFF",
            "note" : "Pageblock paper 80gsm Offset"
        },
        {
            "name" : "Pageblock 130MCS",
            "note" : "Cover paper 130gsm Machine Coated Gloss"
        }
    ]
}

Parameters

Name Type Description Required
apikey String API access key Required
product_mix_reference String The Product Mix reference code Required

Return values

Name Type Description
product_mix_reference String The reference code for the Product Mix
name String The Product Mix name
note String The Product Mix description
product : name String The product name
product : note String The product description
options Array Array of one or more option objects
options : name String The option name
oprions : note String The option description

HTTP status codes

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

Order endpoints


The predefined titles can be ordered with the isbn and catalog reference.


List orders

`https://api.cloudprinter.com/cloudpublish/1.0/orders

Request a list of all orders

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0"
}

Example JSON Response

{
    "orders" : [
        {
            "order_reference" : "200012345",
            "order_date" : "2018-10-10T10:00:00+00:00",
            "state_code" : "order_state_new"
        },
        {
            "order_reference" : "200012346",
            "order_date" : "2018-10-11T10:00:00+00:00",
            "state_code" : "order_state_new"
        }
    ]
}

Parameters

Name Type Description Required
apikey String API access key Required

Return values

Name Type Description
orders : order_reference String The clients own order reference identifier
orders : order_date String The ordered timestamp - ISO 8601
orders : state_code String The order state. See state definitions

HTTP status codes

Code Status Description
200 OK The request has succeeded
204 No content The requested element 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 details

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

Request details on a specific order

Example JSON Request

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

Example JSON Response

{
    "order_reference" : "200012345",
    "state_code" : "order_state_new",
    "order_date" : "2018-10-10T10:00:00+00:00",
    "email" : "test@cloudprinter.com",
    "addresses" : [
        {
            "type" : "delivery",
            "company" : "Example company",
            "firstname" : "Test firstname",
            "lastname" : "Test lastname",
            "street1" : "Test street1",
            "street2" : "Test street2",
            "zip" : "1234",
            "city" : "Test city",
            "state" : "FL",
            "country" : "US",
            "email" : "mail@customer.com",
            "phone" : "+112345678"
        }
    ],
    "items" : [
        {
            "item_reference" : "MW_ORDER_1_1",
            "catalog_reference" : "catalog_2",
            "isbn" : "1234567890123",
            "quantity" : 1,
            "tracking" : ""
        }
    ]
}

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
order_reference String The clients own order reference identifier
state_code String The order state. See state definitions
order_date String The ordered timestamp - ISO 8601
email String The email address of the end consumer
addresses Array Array of one or more address objects
addresses : type String The address type - Valid values are: "delivery"
addresses : company String Company name of the recipient
addresses : firstname String Firstname of the recipient
addresses : lastname String Lastname of the recipient
addresses : street1 String First address line
addresses : street2 String Second address line
addresses : zip String Zip code
addresses : city String City
addresses : state String State name - ANSI INCITS 38:2009 alpha-2 - Required for US
addresses : country String Country code - ISO 3166-1 alpha-2
addresses : email String E-mail address of recipient - May be used during delivery
addresses : phone String Phonenumber of recipient - May be used during delivery
items Array Array of one or more item objects
items : item_reference String The clients item reference id
items : catalog_reference String The clients item reference id
items : isbn String The name of the item
items : quantity String The quantity of the item
items : tracking String Tracking code of the item

HTTP status codes

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

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. This is done 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 recommended.

Example: "https://download.clp/2036b1bc48663b7837ce49bccd689f82/book"

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "order_reference" : "200012345",
    "email" : "support@client-company.com",
    "addresses" : [
        {
            "type" : "delivery",
            "company" : "Example company",
            "firstname" : "Test firstname",
            "lastname" : "Test lastname",
            "street1" : "Test street1",
            "street2" : "Test street2",
            "zip" : "1234",
            "city" : "Test city",
            "state" : "FL",
            "country" : "US",
            "email" : "mail@customer.com",
            "phone" : "+112345678"
        }
    ],
    "items" : [
        {
            "item_reference" : "123456-0001",
            "catalog_reference" : "catalog_1",
            "isbn" : "1234567890123",
            "shipping_level" : "cp_saver",
            "quantity" : "1",
        },
        {
            "item_reference" : "123456-0002",
            "catalog_reference" : "catalog_1",
            "isbn" : "1234567890124",
            "shipping_level" : "cp_saver",
            "quantity" : "1",
        }
    ]
}

Example JSON Response

{
    "order" : "12346"
}

Parameters

Name Type Description Required
apikey String API access key Required
order_reference String The clients own order reference identifier - this must be unique among all orders Required
email String Email address of the clients support team for contact regarding processing and production issues Required
custome_price String End customer sales price ex. vat/tax pr item in selected currency - comma as decimal separator, used for customs Optional
custome_currency String The currency of the end customer sales price - ISO 4217 Optional
custome_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 Array Array of one or more address objects
addresses : type String The address type - Valid values are: "delivery"
addresses : company String Company name of the recipient
addresses : firstname String Firstname of the recipient
addresses : lastname String Lastname of the recipient
addresses : street1 String First address line
addresses : street2 String Second address line
addresses : zip String Zip code
addresses : city String City
addresses : state String State name - ANSI INCITS 38:2009 alpha-2 - Required for US
addresses : country String Country code - ISO 3166-1 alpha-2
addresses : email String E-mail address of recipient - May be used during delivery
addresses : phone String Phonenumber of recipient - May be used during delivery
items Array Array of one or more item objects
items : item_reference String The clients item reference id
items : catalog_reference String The clients item reference id
items : isbn String The title isbn reference of the item
items : quantity String The quantity of the item
items : customs_price String End customer sales price ex. vat/tax in selected currency - comma as decimal separator, used for customs Optional
items : customs_currency String The currency of the end customer sales price - ISO 4217 Optional
items : customs_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

Return values

Name Type Description
order_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/cloudcore/1.0/orders/cancel

Request cancellation of a specific order.

Example JSON Request

{
    "apikey" : "13b37bb1ed6d3403e158abe719b4f6d0",
    "order_reference" : "200012345"
}

Example JSON Response

{
    "status" : {
        "orders" : {
            "cancelled" : 1
        }
    }
}

Parameters

Name Type Description Required
apikey String API access key Required
order_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 element 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",
    "order_reference" : "12346"
}

Example JSON Response

{
  "logs" : [
        {
            "order_reference" : "200012345",
              "create_date" : "2018-10-10T06:58:10+00:00",
            "state_code" : "order_state_verify"
        },
        {
            "order_reference" : "200012345",
            "create_date" : "2018-10-10T06:58:15+00:00",
            "state_code" : "order_state_verified"
        }
    ]
}

Parameters

Name Type Description Required
apikey String API access key Required
order_reference String The clients own order reference identifier Required

Return values

Name Type Description
order_reference String The clients own order reference identifier
create_date String The log entry created timestamp - ISO 8601
state_code String The order state. See state definitions

HTTP status codes

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

Handling errors


In case of an error in the request a HTTP return code 400 is returned. In most cases the response body contails an error code.

Example JSON Response

{
    "status" : {
        "errors" : {
            "missing_required_parameter" : "catalog_reference"
        }
    }
}

On requests where a single element is expected to be added, but the adding fails, the added counter will be 0. For each request these responses must me checked. These requests would normally have a HTTP response code 409 Conflict.

Example JSON Response

{
    "status" : {
        "catalogs" : {
            "radded" : 0
        }
    }
}

On requests to remove a single element, but the element is not found and therefore not removed, the removed counter would be 0. For each request these responses must me checked. These requests would normally have a HTTP response code 410 Gone.

Example JSON Response

{
    "status" : {
        "catalogs" : {
            "removed" : 0
        }
    }
}

Add multiple items - A request to add multiple items where a subset of the items fail will have the added counter set to the number of elements added and the skipped counter set to the number of elements skipped. For each request these responses must me checked. These requests have a HTTP response code 200 OK.