CloudSignal API

This documentation describes the CloudSignal API v2.0

Table of content

Getting started


To get started with Cloudprinter as a Print Partner please read the "Getting started as a Print Partner" article.

Online sign up as a Print Partner is found here: Sign up a Print Partner

Basics


RESTful API

The CloudSignal API is RESTful. All API calls are implemented as HTTP post requests.

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

In case on a HTTP response code 400 the return data can contain an error message. In all other cases the return data is not used.

HTTP response code

The HTTP response code 200 is a positive responses, all other response codes must be considered as error.

Content-type

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

Authentication

Authentication on the CloudSignal API is done via the API key. The API key is generated by the Cloudprinter system when you create the CloudSignal API Interface in the admin panel.

Please note: The API key for signals is not the same API key as for incoming orders.

Signal types


ItemRegistered: https://api.cloudprinter.com/cloudsignal/2.0/status/

Production has started for item.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemRegistered",
    "order": "123456780000",
    "item": "123456780001",
    "datetime": "2016-01-20 13:00:00 GMT"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: ItemRegistered required
order string the full order id required
item string the full item id required
datetime string timestamp required
Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
401 Unauthorized authentication failed
403 Forbidden authentication failed

ItemProduce: https://api.cloudprinter.com/cloudsignal/2.0/status/

Production has started for item.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemProduce",
    "order": "123456780000",
    "item": "123456780001",
    "datetime": "2016-01-20 13:00:00 GMT"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: ItemProduce required
order string the full order id required
item string the full item id required
datetime string timestamp required
Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
401 Unauthorized authentication failed
403 Forbidden authentication failed

ItemProduced: https://api.cloudprinter.com/cloudsignal/2.0/status/

Production completed for item.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemProduced",
    "order": "123456780000",
    "item": "123456780001",
    "datetime": "2016-01-20 13:00:00 GMT"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: ItemProduced required
order string the full order id required
item string the full item id required
datetime string timestamp required
Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
401 Unauthorized authentication failed
403 Forbidden authentication failed

ItemPacked: https://api.cloudprinter.com/cloudsignal/2.0/status/

Item has been packed.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemPacked",
    "order": "123456780000",
    "item": "123456780001",
    "datetime": "2016-01-20 13:00:00 GMT"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: ItemPacked required
order string the full order id required
item string the full item id required
datetime string timestamp required
Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
401 Unauthorized authentication failed
403 Forbidden authentication failed

ItemShipped: https://api.cloudprinter.com/cloudsignal/2.0/status/

Item has been shipped. The tracking code for the packet is included in this signal.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemShipped",
    "order": "123456780000",
    "item": "123456780001",
    "tracking": "1A2B3C4D5E6F",
    "shipping_option": "GLS",
    "datetime": "2016-01-20 13:00:00 GMT"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: ItemShipped required
order string the full order id required
item string the full item id required
tracking string tracking code for the item required
shipping_option string shipping option required
datetime string timestamp required
Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
401 Unauthorized authentication failed
403 Forbidden authentication failed

ItemError: https://api.cloudprinter.com/cloudsignal/2.0/status/

Item has an error during production, this could be a print error, cutting error, failed quality control etc., something the production can recover from, but it will cause a delay in production.

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemError",
    "order": "123456780000",
    "item": "123456780001",
    "cause": "Print error, reprint needed",
    "delay": "24",
    "datetime": "2016-01-20 13:00:00 GMT"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: ItemError required
order string the full order id required
item string the full item id required
cause string text string explaning the error optional
delay string expected delay in hours optional
datetime string timestamp required
Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
401 Unauthorized authentication failed
403 Forbidden authentication failed

ItemCanceled: https://api.cloudprinter.com/cloudsignal/2.0/status/

Item has to be canceled. This is done when there is an item issue the production can not recover from.

The cause must be specified as precise as possible. A custom messages is accepted and is recommended so the client can get a better idea about the nature of the issue.

Accepted cancellation causes can be found here: Print partner cancellation causes

Example JSON Request

{
    "apikey": "13b37bb1ed6d3403e158abe719b4f6d0",
    "type": "ItemCanceled",
    "order": "123456780000",
    "item": "123456780001",
    "cause": "CancelBookSize",
    "message": "Book has wrong width",
    "datetime": "2016-01-20 13:00:00 GMT"
}

Parameters

Name Type Description Required
apikey string api access key required
type string valid value: ItemCanceled required
order string the full order id required
item string the full item id required
cause string cause optional
message string message optional
delay string expected delay in hours optional
datetime string timestamp required
Code Status Description
200 OK the request has succeeded
400 Bad request the request was invalid or parameters are missing
401 Unauthorized authentication failed
403 Forbidden authentication failed

Changes from v1.1 to v2.0


The following list describes the changes made from version 1.1 and 2.0 of the CloudSignal API. When updating from 1.1 to 2.0 please go through these changes.

  • OrderRegistered has been removed and replaced with ItemRegistered.
  • New CloudSignal API endpoints
  • ItemShipped has a new required parameter shipping_option