On this page, you can read step-by-step how you can print a document, using Peecho’s print API.

Requirements

Before you can start using Peecho’s print API, you need to do two things:
    • Register

The first step is creating a Peecho account. You can create your Peecho account here.

    • Top up your balance

In order to print your products, first you have to make sure you have some credit on your account. To do this, you have to log in and go to your dashboard. Click on ”Money” in the top menu and then click on ”Deposit” in the drop down menu. When you click on the green ”+ Buy credit” button, you can top-up your balance. You can pay with MasterCard, Visa, iDeal or PayPal.

1. Choose product
To get started, you have to decide what kind of product you want to offer in print. Through the Peecho print API, you can print magazines, books and wall decoration. However, not all files are suitable for every product and option we offer. To get a filtered list of available offerings suitable for a particular document, you should call this API method specifying properties of the publication:

GET /rest/offering/list/filtered

This displays a filtered list of available offerings for a certain application.

Request 

ParameterRequiredExplanation
applicationApiKeyYesUnique string identifier of the application.
numberOfPagesYes Filters the available offerings based on the minimum and maximum number of pages needed to print the document.
fileTypeYes Should be PDF, JPG, JPEG, GIF or PNG. When specifying PDF the width and height are in mm, otherwise it is in pixels.
widthNo
heightNo
recipientCountryNoFilters the available offerings based on the recipient country. Not all products can be sent to all countries. Use this to know for sure we can send an order to the recipient country.
currenciesNoExpresses offering prices in various currencies. ALL returns all available currencies.
Curl
curl -v "http://www.peecho.com/rest/offering/list/filtered?applicationApiKey={yourApplicationApiKey}&numberOfPages=40&fileType=PDF"

 

Response

The response is exactly the same as the response for accessing an unfiltered offering list.

<?xml version="1.0"?>
<root>
   <pricingExpireDate>2011-09-13T16:00:00.000+02:00</pricingExpireDate>
   <offerings>
      <offering>
         <id>1</id>
         <price>1.00</price>
         <countryShippingPrice>0.00</countryShippingPrice>
         <regionShippingPrice>0.00</regionShippingPrice>
         <worldShippingPrice>0.00</worldShippingPrice>
         <pricePerPage>1.00</pricePerPage>
         <name>boek a5</name>
         <downloadLocation>http://cloud.peecho.com/1/</downloadLocation>
         <currency>EUR</currency>
         <priceByCurrency>
            <value amount="1.00" currency="EUR"/>
            <value amount="1.37" currency="USD"/>
         </priceByCurrency>
         <pricePerPageByCurrency>
            <value amount="0.00" currency="EUR"/>
            <value amount="0.00" currency="USD"/>
         </pricePerPageByCurrency>
         <countryShippingPriceByCurrency>
            <value amount="0.00" currency="EUR"/>
            <value amount="0.00" currency="USD"/>
         </countryShippingPriceByCurrency>
         <regionShippingPriceByCurrency>
            <value amount="0.00" currency="EUR"/>
            <value amount="0.00" currency="USD"/>
         </regionShippingPriceByCurrency>
         <worldShippingPriceByCurrency>
            <value amount="0.00" currency="EUR"/>
            <value amount="0.00" currency="USD"/>
         </worldShippingPriceByCurrency>
         <vatPercentage>19</vatPercentage>
         <defaultNumberOfPages>12</defaultNumberOfPages>
         <minNumberOfPages>0</minNumberOfPages>
         <maxNumberOfPages>100</maxNumberOfPages>
         <dimensionWidth>0</dimensionWidth>
         <dimensionHeight>0</dimensionHeight>
         <minimumQuantity>1</minimumQuantity>
         <addShipping>true</addShipping>
         <recommended>false</recommended>
         <dimensionUnit>mm</dimensionUnit>
         <elements>
            <id>1</id>
            <name>content</name>
            <url/>
         </elements>
         <elements>
            <id>2</id>
            <name>cover</name>
            <url>cover</url>
         </elements>
         <catalogueItemCode>boek a5</catalogueItemCode>
         <merchantApiKey>your-merchant-api-key</merchantApiKey>
         <applicationApiKey>your-application-api-key</applicationApiKey>
         <fixedSize>false</fixedSize>
      </offering>
   </offerings>
</root>

 

2. Create an order

Once you decided which product you want to offer in print it is time to place an order. You can do this by calling this method:

POST /rest/order/create_from_source_url

Create a new order based on the URL of a source document (either PDF or image).

 Request 

ParameterRequiredExplanation
merchantApiKeyYesUnique string identifier of the merchant.
offeringIdYesUnique integer identifier of your offering.
numberOfPagesYes Filters the available offerings based on the minimum and maximum number of pages needed to print the document.
sourceUrlYesThe full URL to the source document
sourceWidthYesThe width in mm of the source PDF document.
sourceHeightYesThe height in mm of the source PDF document.
filetypeNoShould be PDF, JPG, JPEG, GIF or PNG. When specifying PDF the width and height are in mm, otherwise it is in pixels.
merchantReferenceNoUse your own internal id as a reference to link this order to your internal systems.
paymentReferenceNoReference for the payment provider, this should be a globally unique identifier. Use a UUID.
titleNoAPI
localeNoThe locale of the end customer. E-mails sent from our systems will be in this language. Defaults to English ('en').
currencyNoThe currency used to pay with. Defaults to Euro ('EUR').
spineColorHexNoThis will give the spine of the printed book or magazine a solid color. Use hexadecimal notation (#ffffff).
textColorNoColor of text on spine.
textSizeNoSize of text on spine.
textCenterNoText in the center part spine.
textTopNoText in the top part spine.
textBottomNoText in the bottom part spine.
fontFamilyNo Font of spine text. (Arial, DarkCourier, Georgia, GochiHand, Helvetica, Tahoma, TimesNewRoman, Verdana)

Curl

curl -v -d "merchantApiKey={yourMerchantApiKey}&offeringId=70&numberOfPages=40&sourceUrl=https://s3-eu-west-1.amazonaws.com/peecho-assets/storage/images/junit-test/mediamarkt.pdf&sourceWidth=245&sourceHeight=220" "http://www.peecho.com/rest/order/create_from_source_url"

Response

An XML representation of the new order including the policy and signature to be used when sending files to the order bucket.

<?xml version="1.0"?>
<order>
  <externalOrderId>4194</externalOrderId>
  <signedPutUrl>http://peecho-test-order.s3.amazonaws.com</signedPutUrl>
  <signedPutPath>1/4194/</signedPutPath>
  <base64EncodedPolicy>encoded-policy </base64EncodedPolicy>
  <signature>3XRuQ96XNs10porjx30=</signature>
  <apiVersion>0</apiVersion>
  <id>4194</id>
  <orderState>OPEN</orderState>
  <quantity>1</quantity>
</order>

 

3. Set details

Great! You have placed your order (which you can see in your dashboard by clicking on ”orders” in the top menu). Now you have to provide the order details.

POST /rest/order/details

Supply additional details about an order, such as the customer shipping address and quantity.

Request 

ParameterRequiredExplanation
externalOrderIdYesUnique external string identifying the order.
shippingAddressXmlYesXML representation of the shipping address.
emailAddressYes Customer email address for order reference and optional customer service communication.
customerNameNoName of the customer.
quantityNoNumber of copies requested. Defaults to 1.

The shipping address must have the following structure:

<?xml version="1.0"?>
<address>
    <firstName>recipientFirstName</firstName>
    <lastName>recipientLastName</lastName>
    <addressLine1>shippingAddressLine1</addressLine1>
    <addressLine2>shippingAddressLine2</addressLine2>
    <zipCode>shippingZipCode</zipCode>
    <city>shippingCity</city>
    <state>state</state>
    <country>Netherlands</country>
    <countryCode>NL</countryCode>
</address>

Curl

curl -v -d "externalOrderId={externalOrderId}&emailAddress=marcel@peecho.com&shippingAddressXml=<?xml version='1.0'?><address><firstName>recipientFirstName</firstName><lastName>recipientLastName</lastName><addressLine1>shippingAddressLine1</addressLine1><addressLine2>shippingAddressLine2</addressLine2><zipCode>shippingZipCode</zipCode><city>shippingCity</city><country>Netherlands</country><countryCode>NL</countryCode></address>" "http://www.peecho.com/rest/order/details"

 

Response

If all went well, this service will only respond with the string 'OK'.

 

4. Confirm payment

The last step is the payment confirmation. Typically, the API method should be called after you received confirmation from the payment provider. The moment you call this API method, we will start processing your order (costs of print will be substracted from your balance).

POST /rest/order/set_paid

Set an order as paid. This is required if you use your own payment procedure.

Request 

ParameterRequiredExplanation
externalOrderIdYesUnique external string identifying the order.
merchantApiKeyYesUnique string identifier of the merchant.
secretYesBase64 encoded HMAC SHA1 Hash of merchantApiKey + externalOrderId using your merchantSecretKey as HMAC-key.

Curl

curl -v -d "externalOrderId={yourExternalOrderId}&merchantApiKey={yourMerchantApiKey}&secret={generatedSecretHash}" "http://www.peecho.com/rest/order/set_paid"

Java

String secretKey = "merchantSecretKey";
String merchantApiKey = "merchantApiKey";
String externalOrderId = "1234";
String data = merchantApiKey + externalOrderId;
Mac m = Mac.getInstance("HmacSHA1");
m.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA1"));
byte[] hash = m.doFinal(data.getBytes("UTF-8"));
String secret = new String(Base64.encodeBase64(hash));

/*
You get as result: LmzDnZGhdSI3D3aWXrQNcY0GDqI=

(using org.apache.commons.codec.binary for base64 and javax.crypto for Mac).
*/

Response

This service either returns 'ERROR' or 'OK'.

 

That’s all!

After completing these simple steps, your file will be processed, printed and sent to the address specified in the third step.

Do you need help with the integration of the print API? Email support@peecho.com