Skip to content

PHP SDK CloudAPPS documentation

Jump to bottom
Vasyl Kushniruk edited this page Jun 9, 2020 · 3 revisions

Getting started

What is Cloudprinter PHP SDK

The Cloudprinter.com PHP SDK is a library with useful features that enable App developers to easily integrate their application with Cloudprinter.com and make requests to our CloudApps API. This PHP SDK makes it easy to set up the integration between your App and the Cloudprinter.com Print Cloud to request instant pricing, post-print orders, get production signals back, and more.

The CloudApps API is exclusively designed for app and platform developers and offers support for multiple users.

We at Cloudprinter.com have connected 150+ printers to print & ship print products in almost any country in the world. Whether this is around the corner or on the other side of the globe, we've got you covered: we can deliver 500+ different products in more than 100 countries currently.

Our platform makes use of smart routing algorithms to route any print job to the most local and qualified printer. Based on location, performance, price and production options, your print job is routed by these algorithms to the nearest printing facility near your delivery address to help you save on transit times and costs.

Visit our website for more information on all the products and services that we offer.

Prerequisites

  • composer (for installation)
  • PHP 7.0 or above
  • JSON, fileinfo, curl extensions must be enabled
  • Cloudprinter.com Print Cloud account

How to install?

The CloudApps SDK can be installed with Composer. Run this command:

composer require cloudprinter/cloudapps

Or manual installation:

git clone -b master https://github.com/cloudprintercom/cloudapps-php-sdk

<?php
require '/path-to-sdk/autoload.php';

Quick start

Once you have completed the installation, you could make the first call. To write an app that uses the SDK, you will create your first PHP script that will create a CloudApps client. Look at Authentication to know how to get an access token.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);

After creating a Cloudapps client, you can work with cloudprinter API.

$response = $client->order->getList();
$orderList = $response->getData();

General

Creating an app

The CloudApps API is designed as the backend for integrated apps. An app could as an example be an e-commerce system integration.

Each app needs to be created in the Cloudprinter.com system. Please contact the Cloudprinter.com support team for this.

Authentication

Authentication is done via OAuth2. Each app requires a unique client identifier, client password, and a return URL. This information is required for the Cloudprinter.com support team when creating the app.

The Cloudprinter.com user login grants access to the CloudApps API. Each request to CloudApps API requires an access token. The CloudApps SDK makes it easier to do it. This is a 2 step process. First, get the link to redirect the user:

use CloudPrinter\CloudApps\Authentication\OAuth2;  

$config = [  
  'client_id' => '***',  
  'client_secret' => '***',  
  'redirect_uri' => 'http://www.your-site.com',  
  'scope' => 'read-write'  
];  
$oAuth2 = new OAuth2($config);  

$authorizationCodeUrl = $oAuth2->getAuthorizationCodeUrl();

This will give you the URL to redirect the user. You need to specify a redirect URI which will be the one that the user will redirect after a successful authorization process.

Once the user is redirected to your redirect URI, you'll receive in the query string, a parameter named code. You'll need this for the second part of the process.

$code = $_GET['code'];  
$accessTokenData = $oAuth2->getAccessToken($code);

Error Handling

API errors.

Each call to API via CloudApps SDK returns Response object. To be sure that it succeeded you need to check the status code.

$accessToken = '***';  
$orderReference = '123';  
  
$client = new CloudAppsClient($accessToken);  
$response = $client->order->getInfo($orderReference);  

if ($response->getStatusCode == 200) {
	print_r($response->getData());
}

Exception.

In a case of request: data is not valid, SDK throws ValidationException exception. here are examples on how to handle it.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
use CloudPrinter\CloudApps\Exception\ValidationException;  
use CloudPrinter\CloudApps\Model\{Option, OrderQuote, OrderQuoteItem};  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
  
$option = new Option();  
$option->setOptionReference('paper_90off')  
  ->setCount(1);  
  
$itemQuote = new OrderQuoteItem();  
$itemQuote->setReference('123')  
  ->setCount(250)  
  ->setProductReference('letterheading_ss_a4_2_0')  
  ->addOption($option);  
  
$orderQuote = new OrderQuote();  
$orderQuote->setCountry('NL')  
  ->addItem($itemQuote);  
  
try {  
  $response = $client->order->quote($orderQuote);  
  print_r($response->getData());  
} catch (ValidationException $e) {  
  print_r($e->getValidationMessages());  
}

Debugging

The model method toArray() returns the request API data. This information contains all data that will be used for API calls. Look at the example below.

use CloudPrinter\CloudApps\Client\CloudAppsClient;
use CloudPrinter\CloudApps\Model\Order;

$accessToken = '***';
$client = new CloudAppsClient($accessToken);

$order = new Order();
.............
var_dump($order->toArray());

$client->order->create($order);

Examples

Order

List all orders

Request the list of all orders.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
$response = $client->order->getList();  
  
print_r($response->getData());

Get order info

Request a detailed order info by reference.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$orderReference = '123';  
  
$client = new CloudAppsClient($accessToken);  
$response = $client->order->getInfo($orderReference);  
  
print_r($response->getData());

Add order

Add a new order including one or more items, addresses, options, and files. Files should be added with a URL from where Cloudprinter can fetch the files when the order has been accepted. An MD5 hash of the file is not required, but if you have one it will save you time on calculating. Look for more details in Documentation.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
use CloudPrinter\CloudApps\Exception\ValidationException;  
use CloudPrinter\CloudApps\Model\{Address, File, OrderItem, Order, Option};  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
  
$address = new Address();  
$address->setEmail('test@mail.com')  
  ->setFirstName('John')  
  ->setLastName('Doe')  
  ->setCountry('NL')  
  ->setCity('Amsterdam')  
  ->setStreet('Street1')  
  ->setPhone('+31-655-538-848')  
  ->setZip('1071 JA')  
  ->setType('delivery');  
  
$fileCover = new File();  
$fileCover->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Cover_Textbook_80_gsm_Casewrap_v2.1.pdf')  
  ->setType('cover');  
  
$fileBook = new File();  
$fileBook->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Interior_Textbook_v2.1.pdf')  
  ->setType('book');  

$itemQuote = '***';
$item = new OrderItem();
$item->setReference('item-1')
  ->setCount(1)
  ->setProductReference('textbook_cw_a4_p_bw')
  ->addFile($fileCover)
  ->addFile($fileBook)
  ->addOption(new Option('cover_finish_gloss', 1))
  ->addOption(new Option('pageblock_80off', 1))
  ->addOption(new Option('cover_130mcg', 1))
  ->addOption(new Option('total_pages', 100))
  ->setQuote($itemQuote);

$order = new Order();  
$order
  ->setEmail('test@mail.com')
  ->setReference('sdk-' . time())
  ->addItem($item)
  ->addAddress($address);  

try {  
  $response = $client->order->create($order);  
  print_r($response->getData());  
} catch (ValidationException $e) {  
  print_r($e->getValidationMessages());  
}

Reorder

Reorders use the regular order create method, they just require a few extra parameters. Reorders are done on item level. Only items from a single order can be included in a reorder. Look for more details in Documentation.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
use CloudPrinter\CloudApps\Exception\ValidationException;  
use CloudPrinter\CloudApps\Model\{Address, File, OrderItem, Order, Option};  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
  
$address = new Address();  
$address->setEmail('test@mail.com')  
  ->setFirstName('John')  
  ->setLastName('Doe')  
  ->setCountry('NL')  
  ->setCity('Amsterdam')  
  ->setStreet('Street1')  
  ->setPhone('+31-655-538-848')  
  ->setZip('1071 JA')  
  ->setType('delivery');  
  
$fileCover = new File();  
$fileCover->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Cover_Textbook_80_gsm_Casewrap_v2.1.pdf')  
  ->setType('cover');  
  
$fileBook = new File();  
$fileBook->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Interior_Textbook_v2.1.pdf')  
  ->setType('book');  
  
$itemQuote = '*';  
$item = new OrderItem();  
$item->setReference('item-1')  
  ->setCount(1)  
  ->setProductReference('textbook_cw_a4_p_bw')  
  ->addFile($fileCover)  
  ->addFile($fileBook)  
  ->setReorderItemReference('reorder-item-1')  
  ->setReorderOrderReference('order-reference')  
  ->setReorderCause('reorder cause')  
  ->setReorderDescription('reorder description')  
  ->addOption(new Option('cover_finish_gloss', 1))  
  ->addOption(new Option('pageblock_80off', 1))  
  ->addOption(new Option('cover_130mcg', 1))  
  ->addOption(new Option('total_pages', 100))  
  ->setQuote($itemQuote);  
  
$order = new Order();  
$order  
  ->setEmail('test@mail.com')  
  ->setReference('sdk-' . time())  
  ->addItem($item)  
  ->addAddress($address);  
  
try {  
  $response = $client->order->create($order);  
  print_r($response->getData());  
} catch (ValidationException $e) {  
  print_r($e->getValidationMessages());  
}

Cancel order

Request a cancellation of a specific order by reference.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$orderReference = '123';  
$client = new CloudAppsClient($accessToken);  
$response = $client->order->cancel($orderReference);  
  
print_r($response->getData());

Order log

Request an order log by reference.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$orderReference = '123';  
  
$client = new CloudAppsClient($accessToken);  
$response = $client->order->getLog($orderReference);  
  
print_r($response->getData());

Order quote

Request an order quote. Cloudprinter provides a quote on product prices, shipping options, and shipping prices through the quote API endpoint. Each quote request returns both product prices and shipping options with pricing. Each quote has its unique hash, which has to be included in the order. A quote hash is valid for 48 hours.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
use CloudPrinter\CloudApps\Exception\ValidationException;  
use CloudPrinter\CloudApps\Model\{Option, OrderQuote, OrderQuoteItem};  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
  
$option = new Option();  
$option->setOptionReference('paper_90off')  
  ->setCount(1);  
  
$itemQuote = new OrderQuoteItem();  
$itemQuote->setReference('123')  
  ->setCount(250)  
  ->setProductReference('letterheading_ss_a4_2_0')  
  ->addOption($option);  
  
$orderQuote = new OrderQuote();  
$orderQuote->setCountry('NL')  
  ->addItem($itemQuote);  
  
try {  
  $response = $client->order->quote($orderQuote);  
  print_r($response->getData());  
} catch (ValidationException $e) {  
  print_r($e->getValidationMessages());  
}

Get quote info

Request detailed information about quote hash.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$quoteHash = '123';  
  
$client = new CloudAppsClient($accessToken);  
$response = $client->order->quoteInfo($quoteHash);  
  
print_r($response->getData());

Product

List all products

Request a list of all cloudprinter products.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
$response = $client->product->getList();  
  
print_r($response->getData());

Product info

Request detailed product information.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$productReference = 'folder_s150_s_fc';  
$client = new CloudAppsClient($accessToken);  
$response = $client->product->getInfo($productReference);  
  
print_r($response->getData());

Webhook

CloudSignal Webhooks are used to deliver signals from Cloudprinter and the productions back to the partner.

Subscribe

To create a new CloudSignal subscription you should register URL and CloudApps will create a new CloudSignal Webhooks configuration. This can also be found in the Cloudprinter admin dashboard.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$url = 'test.com';  
$client = new CloudAppsClient($accessToken);  
$response = $client->webHook->subscribe($url);  
  
print_r($response->getData());

Unsubscribe

The CloudSignal subscription can at anytime be unsubscribed. Look at an example to see how to do this.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$webHookId = 1;  
  
$client = new CloudAppsClient($accessToken);  
$response = $client->webHook->unSubscribe($webHookId);  
  
print_r($response->getStatusCode());

Shipping

List shipping levels

Request a list of shipping levels.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
$response = $client->shipping->getLevels();  
  
print_r($response->getData());

List shipping countries

Request a list of shipping countries that are supported in the cloudprinter.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
$response = $client->shipping->getCountries();  
  
print_r($response->getData());

List shipping states

Request a list of shipping states that are supported in the cloudprinter.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
$countryReference = 'US';
$response = $client->shipping->getStates($countryReference);  
  
print_r($response->getData());

User

Get info

Request detailed user information.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
$response = $client->user->getInfo();  
  
print_r($response->getData());

Price

Lookup

Request detail info about price, product, and shipping in a specific region.

use CloudPrinter\CloudApps\Client\CloudAppsClient;  
use CloudPrinter\CloudApps\Exception\ValidationException;  
use CloudPrinter\CloudApps\Model\{Option, OrderQuote, OrderQuoteItem};  
  
$accessToken = '***';  
$client = new CloudAppsClient($accessToken);  
  
$option = new Option();  
$option->setOptionReference('paper_90off')  
  ->setCount(1);  
  
$itemQuote = new OrderQuoteItem();  
$itemQuote->setReference('123')  
  ->setCount(250)  
  ->setProductReference('letterheading_ss_a4_2_0')  
  ->addOption($option);  
  
$orderQuote = new OrderQuote();  
$orderQuote->setCountry('NL')  
  ->addItem($itemQuote);  
  
try {  
  $response = $client->price->lookup($orderQuote);  
  print_r($response->getData());  
} catch (ValidationException $e) {  
  print_r($e->getValidationMessages());  
}

CloudSignal

Getting status signals back to your app is an important step, it allows you to:

  • keep track of the order production state
  • provide your end-user with tracking information
  • get notified if there is an issue with the order causing a delay
  • get notified if the order can not be produced and gets canceled

Handle a single signal

Your CloudSignal endpoint must be RESTful. All calls must be implemented as HTTP post and with TLS encrypted. The HTTP response code 200 or 204 is expected on positive calls, all other response codes will be considered as error.

Each webhook request includes a CloudSignal API key, which is different from the account API key. This key should be validated on each request.

use CloudPrinter\CloudApps\CloudSignal\CloudSignalHandler;  
  
$cloudSignalApiKey = '***';  
$cloudSignalHandler = new CloudSignalHandler($cloudSignalApiKey);  
  
// handle ItemShipped signal  
$cloudSignalHandler->onItemShipped(function(array $signalData) {  
  // handle  
});  
  
// handle CloudprinterOrderCanceled signal  
$cloudSignalHandler->onCloudprinterOrderCanceled(function(array $signalData) {  
  // handle  
});  
  
// handle CloudprinterOrderValidated signal  
$cloudSignalHandler->onCloudprinterOrderValidated(function(array $signalData) {  
  // handle  
});  
  
// handle ItemCanceled signal  
$cloudSignalHandler->onItemCanceled(function(array $signalData) {  
  // handle  
});  
  
// handle ItemError signal  
$cloudSignalHandler->onItemError(function(array $signalData) {  
  // handle  
});  
  
// handle ItemPacked signal  
$cloudSignalHandler->onItemPacked(function(array $signalData) {  
  // handle  
});  
  
// handle ItemProduced signal  
$cloudSignalHandler->onItemProduced(function(array $signalData) {  
  // handle  
});

Handle multiple signals

It can be useful when you want to handle more than one signal in one way.

use CloudPrinter\CloudApps\CloudSignal\CloudSignalHandler;  
  
$cloudSignalApiKey = '***';  
$cloudSignalHandler = new CloudSignalHandler($cloudSignalApiKey);  
  
$signals = [  
  'ItemProduced',  
  'ItemProduced',  
  'CloudprinterOrderValidated',  
];  
  
$cloudSignalHandler->on($signals, function(array $signalData) {  
  // handle  
});

Getting help

If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue:

Clone this wiki locally