API reference

peecho
about us
blog
help

Peecho API

The Peecho API uses a simple REST interface with XML responses. See the description of the interface below.

`GET /rest/offering/list`

Purpose

Display the list of available offerings for a certain merchant and application.

Parameter	Required	Explanation
applicationApiKey	yes	Unique string identifier of the application
merchantApiKey	yes	Unique string identifier of the merchant
currencies	no	Express offering prices in various currencies. ALL returns all available currencies.

Response

A list of offering details of the following structure:


<?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>

`GET /rest/offering/details`

Purpose

Display detailed information about one offering for a certain merchant and application.

Parameter	Required	Explanation
buttonKey	no	Unique string identifier of the button. Specify the button key or specify both applicationApiKey and merchantApiKey.
applicationApiKey	no	Unique string identifier of the application
merchantApiKey	no	Unique string identifier of the merchant
offeringId	yes	Unique string identifier of the offering
currencies	no	Express offering prices in various currencies. ALL returns all available currencies.

Response

The response is very similar to the response for /rest/offering/list except for the converted prices:


<?xml version="1.0"?>
<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>
	<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>

`GET /rest/offering/quote`

Purpose

Generate a quote for a given offering based on number of pages, shipping country, etc. expressed in a certain currency.

Parameter	Required	Explanation
applicationApiKey	yes	Unique string identifier of the application
merchantApiKey	yes	Unique string identifier of the merchant
offeringId	yes	Unique string identifier of the offering
currency	yes	The base currency of the quote
countryCode	yes	Two digit (ISO 3166-2) country code of the shipping address
numberOfPages	yes	The total number of pages in the source document including cover pages.
quantity	yes	The number of copies to be printed
useMerchantSecret	no	true or false (default = true) When true will use merchant secret key for order signing

Response

All required information about the new quote.


<quote>
  <rate>1.3500</rate>
  <price>135</price>
  <currency>USD</currency>
  <quantity>1</quantity>
  <vat>26</vat>
  <secret>Ip7fj1LeiyYdfiClaQNkB0MmRAs=</secret>
  <offering-id>1</offering-id>
  <price-retail>135</price-retail>
  <price-wholesale>135</price-wholesale>
  <price-shipping>0</price-shipping>
  <price-per-page>0</price-per-page>
  <extra-number-of-pages>0</extra-number-of-pages>
  <number-of-pages>10</number-of-pages>
  <vat-percentage>19</vat-percentage>
  <total-price-excluding-vat>135</total-price-excluding-vat>
  <total-price-including-vat>161</total-price-including-vat>
  <offering-width>0</offering-width>
  <offering-height>0</offering-height>
  <fixed-size>false</fixed-size>
  <merchant-name>peecho</merchant-name>
  <full-payment-url>https://an-url-to-some-payment-provider</full-payment-url>
</quote>

`POST /rest/order`

Purpose

Create a new order.

Parameter	Required	Explanation
offeringId	yes	Unique integer identifier of your offering
apiVersion	no	Minimum level of API version for which your application is known to work
emailAddress	no	Customer email address for order reference
merchantReference	no	Reference for merchant internal purposes
paymentReference	no	Reference of the payment provider
merchantApiKey	yes	Unique string identifier of the merchant
title	no	The on-screen title of the document
locale	no	The locale of the end customer

Response

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


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

`POST /rest/order/create_from_checkout_url`

Purpose

Create a new order based on some source document (either PDF or image).

Parameter	Required	Explanation
offeringId	yes	Unique integer identifier of your offering
merchantApiKey	yes	Unique string identifier of the merchant
numberOfPages	yes	The total number of pages in the source document including cover pages.
sourceUrl	yes	The full URL to the source document
filetype	no	The filetype of the source document, can be either pdf or image
sourceWidth	yes	The width in mm of the source PDF document
sourceHeight	yes	The height in mm of the source PDF document
merchantReference	no	Reference for merchant internal purposes
paymentReference	no	Reference for the payment provider
title	no	The on-screen title of the document
locale	no	The locale of the end customer

Response

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


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

`POST /rest/order/details`

Purpose

Supply additional details about an order, such as the customer shipping address and quantity. The shipping address must have the following structure:


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

Parameter	Required	Explanation
externalOrderId	yes	Unique external string identifying the order
customerName	no	Name of the customer
shippingAddressXml	yes	Xml representation of the shipping address
emailAddress	yes	Customer email address for order reference
quantity	yes	Number of copies requested

Response

If all went well this service only response with the string 'OK'.

`GET /rest/order/set_paid`

Purpose

Mark an order as PAID. This is useful for Peecho customers who handle the customer payment themselves.

Parameter	Required	Explanation
externalOrderId	yes	Unique external string identifying the order
merchantApiKey	yes	Unique string identifier of the merchant
secret	yes	Base64 encoded HMAC SHA1 Hash of merchantApiKey and externalOrderId using your merchantSecretKey as HMAC-key.

Response

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

`POST /rest/order/set_quote_and_paid`

Purpose

Use a quote to finalize an order. The parameter quoteXml must have the same XML structure as the response to /rest/offering/quote

Parameter	Required	Explanation
externalOrderId	yes	Unique external string identifying the order
merchantApiKey	yes	Unique string identifier of the merchant
secret	yes	Base64 encoded HMAC SHA1 Hash of merchantApiKey and externalOrderId using your merchantSecretKey as HMAC-key.
quoteXml	yes	The XML representation of the quote fields
useMerchantSecret	no	true or false (default = true) When true will use merchant secret key for order signing

Response

This service either returns 'OK' or an error status.

`GET /rest/order/status`

Purpose

Display the current order status.

Parameter	Required	Explanation
paymentReference	yes	Reference of the payment provider
merchantApiKey	yes	Unique string Identifier of the merchant

Response


<order-status>
  <order-id>4194</order-id>
  <payment-reference>payment reference</payment-reference>
  <merchant-reference>some reference</merchant-reference>
  <order-status>open</order-status>
  <price>0.00</price>
  <priceRetail>1.00</priceRetail>
  <priceWholesale>1.00</priceWholesale>
  <shippingRetail>0.00</shippingRetail>
  <shippingWholesale>0.00</shippingWholesale>
  <vat>0.00</vat>
  <created>2011-09-27T14:25:54.000+02:00</created>
  <quantity>1</quantity>
  <title>title</title>
  <shipping/>
  <history/>
</order-status>

API reference

Peecho API

`GET /rest/offering/list`

Purpose

Response

`GET /rest/offering/details`

Purpose

Response

`GET /rest/offering/quote`

Purpose

Response

`POST /rest/order`

Purpose

Response

`POST /rest/order/create_from_checkout_url`

Purpose

Response

`POST /rest/order/details`

Purpose

Response

`GET /rest/order/set_paid`

Purpose

Response

`POST /rest/order/set_quote_and_paid`

Purpose

Response

`GET /rest/order/status`

Purpose

Response

Product

Company

FAQ

Contact

Search this site

Oh... and we love your feedback