Skip to content

NodeJS SDK CloudAPPS documentation

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

Getting started

What is Cloudprinter NodeJS SDK

The Cloudprinter.com NodeJS SDK is a package with useful features that enable App developers to easily integrate their application with Cloudprinter.com and make requests to our CloudApps API. This NodeJs 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

  • npm (for installation)
  • nodejs 6.0 or above
  • Cloudprinter.com Print Cloud account

How to install?

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

npm i @cloudprinter/cloudapps --save

# Or, if you prefer yarn
yarn add @cloudprinter/cloudapps

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 NodeJs script that will create a CloudApps client. Look at Authentication to know how to get access token.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);

After the CloudApps client is created, you can work with cloudprinter api.

cloudAppsClient.order.getList()
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

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:

const CloudApps = require('@cloudprinter/cloudapps');

const config = {
    client_id: '***',
    redirect_uri: 'http://www.your-site.com',
    scope: 'read-write'
};

const oAuth2 = new CloudApps.OAuth2(config);
const 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.

const CloudApps = require('@cloudprinter/cloudapps');

const code = '***';
const config = {
    client_id: '***',
    client_secret: '***',
    redirect_uri: 'http://www.your-site.com',
};

const oAuth2 = new CloudApps.OAuth2(config);
oAuth2.getAccessToken(code)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Error Handling

API errors.

Errors can happen for many reasons: an expired token, or just used an invalid argument. In these cases, the returned Promise will reject with an Error. You should catch the error and use the information it contains to decide how your app can proceed.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const orderReference = 'order-123';

cloudAppsClient.order.getInfo(orderReference)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Examples

Order

List all orders

Request a list of all orders.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);

cloudAppsClient.order.getList()
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Get order info

Request detailed order info by reference.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const orderReference = 'order-123';

cloudAppsClient.order.getInfo(orderReference)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

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.com 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.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const data = {
    "reference": "order-1234",
    "email": "test@mail.com",
    "addresses": [
        {
            "type": "delivery",
            "firstname": "John",
            "lastname": "Doe",
            "street1": "Street1",
            "zip": "1071 JA",
            "city": "Amsterdam",
            "country": "NL",
            "email": "test@mail.com",
            "phone": "+31-655-538-848"
        }
    ],
    "items": [
        {
            "reference": "item-1",
            "product_reference": "textbook_cw_a4_p_bw",
            "count": 1,
            "files": [
                {
                    "type": "cover",
                    "url": "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",
                    "md5sum": "15c518d3d105ecaaab014df2456dd22b"
                },
                {
                    "type": "book",
                    "url": "https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Interior_Textbook_v2.1.pdf",
                    "md5sum": "15c518d3d105ecaaab014df2456dd22b"
                }
            ],
            "options": [
                {
                    "option_reference": "cover_finish_gloss",
                    "count": 1
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": 1
                },
                {
                    "option_reference": "cover_130mcg",
                    "count": 1
                },
                {
                    "option_reference": "total_pages",
                    "count": 100
                }
            ],
            "quote": "*"
        }
    ]
};

cloudAppsClient.order.create(data)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Reorder

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

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const data = {
    "reference": "order-2",
    "email": "test@mail.com",
    "addresses": [
        {
            "type": "delivery",
            "firstname": "John",
            "lastname": "Doe",
            "street1": "Street1",
            "zip": "1071 JA",
            "city": "Amsterdam",
            "country": "NL",
            "email": "test@mail.com",
            "phone": "+31-655-538-848"
        }
    ],
    "items": [
        {
            "reference": "item-1",
            "product_reference": "textbook_cw_a4_p_bw",
            "count": 1,
            "reorder_cause": "cause",
            "reorder_desc": "description",
            "reorder_order_reference": "order-1",
            "reorder_item_reference": "item-1",
            "files": [
                {
                    "type": "cover",
                    "url": "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",
                    "md5sum": "15c518d3d105ecaaab014df2456dd22b"
                },
                {
                    "type": "book",
                    "url": "https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Interior_Textbook_v2.1.pdf",
                    "md5sum": "15c518d3d105ecaaab014df2456dd22b"
                }
            ],
            "options": [
                {
                    "option_reference": "cover_finish_gloss",
                    "count": 1
                },
                {
                    "option_reference": "pageblock_80off",
                    "count": 1
                },
                {
                    "option_reference": "cover_130mcg",
                    "count": 1
                },
                {
                    "option_reference": "total_pages",
                    "count": 100
                }
            ],
            "quote": "*"
        }
    ]
};

cloudAppsClient.order.create(data)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Cancel order

Request cancellation of a specific order by reference.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const orderReference = 'order-123';

cloudAppsClient.order.cancel(orderReference)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Order log

Request order log by reference.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);

const orderReference = 'order-123';
cloudAppsClient.order.getLog(orderReference)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Order quote

Request an order quote. Cloudprinter.com 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 is valid for 48 hours.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const data = {
    "country": "NL",
    "items": [
        {
            "reference": "1",
            "product_reference": "brochure_pb_a5_p_fc",
            "count": 68,

            "options": [
                {
                    "option_reference": "pageblock_130mcs",
                    "count": 1
                },
                {
                    "option_reference": "cover_200mcs",
                    "count": 1
                },
                {
                    "option_reference": "total_pages",
                    "count": 100
                }
            ]
        }
    ]
};

cloudAppsClient.order.quote(data)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Get quote info

Request detailed information about a quote hash.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const quoteHash = "*";
const cloudAppsClient = new CloudApps.Client(accessToken);

cloudAppsClient.order.quoteInfo(quoteHash)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Product

List all products

Request a list of all cloudprinter products.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);

cloudAppsClient.product.getList()
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Product info

Request detailed product information.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const productReference = 'flyer_ss_a4_fc';

cloudAppsClient.product.getInfo(productReference)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Webhook

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

Subscribe

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

const cloudApps = require('@cloudprinter/cloudapps');

const url = 'http://test.com';
const accessToken = '*';
const client = new cloudApps.Client(accessToken);

client.webHook.subscribe(url)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Unsubscribe

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

const cloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const webHookId = 1;
const client = new cloudApps.Client(accessToken);

client.webHook.unSubscribe(webHookId)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Shipping

List shipping levels

Request a list of shipping levels.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);

cloudAppsClient.shipping.getLevels()
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

List shipping countries

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

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);

cloudAppsClient.shipping.getCountries()
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

List shipping states

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

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const countryReference = 'US';

cloudAppsClient.shipping.getStates(countryReference)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

User

Get info

Request detail user information.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);

cloudAppsClient.user.getInfo()
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Price

Lookup

Request detailed info about the price of a product and shipping in a specific region.

const CloudApps = require('@cloudprinter/cloudapps');

const accessToken = '*';
const cloudAppsClient = new CloudApps.Client(accessToken);
const data = {
    "country": "NL",
    "items": [
        {
            "reference": "1",
            "product_reference": "brochure_pb_a5_p_fc",
            "count": 68,

            "options": [
                {
                    "option_reference": "pageblock_130mcs",
                    "count": 1
                },
                {
                    "option_reference": "cover_200mcs",
                    "count": 1
                },
                {
                    "option_reference": "total_pages",
                    "count": 100
                }
            ],
        }
    ]
};

cloudAppsClient.price.lookup(data)
    .then(function (response) {
        console.log(response);
    })
    .catch(function (error) {
        console.log(error);
    });

Getting help

If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - Issue Tracker for feature requests and bug reports

Clone this wiki locally