Revision

Date	Description
05 Mar 2025	webservice is moving to another server Digital Product Order Service (CEP)
08 Aug 2022	Delivery Channel BS (Bookshelf) is deprecated
22 Feb 2022	As of July 1, 2022, CB will no longer support Bookshelf
03 May 2021	Specific messages (type/code/text) for this webservice: Some of EBS-* error code will change to WMS-* codes
29 Apr 2021	As of May 17, 2021, CB will no longer support TLS 1.0 and 1.1
08 Apr 2021	Initial document

Introduction

This web service supports the order process for customers buying digital products.

This web service has the following operations:

checkOrderable
getContentUrl
placeOrder

Path: /rest/api/v1/DigitalProductOrderService

Specific messages (type/code/text) for this webservice:

Type	Code	Text	New code	New text Date to be announced
E	EBS-10001	The field EAN is mandatory	WMS-00008	[object has missing required properties ([\"EAN\"])]
E	EBS-10003	A product with this EAN is not available
E	EBS-10004	This product is not available for delivery
E	EBS-10005	This OrderReference has already been used, use another reference
E	EBS-10006	This product can not be ordered yet
E	EBS-10009	This product may not be ordered yet
E	EBS-10011	This audio book is no longer available via CB. Please contact the publisher for more info
E	EBS-10017	Your credit limit has been exceeded
E	EBS-10034	This product is not available for the given reading method
E	EBS-10038	Vitalsource user account unknown
E	EBS-10056	Invalid value for DeliveryChannel	WMS-00008	[instance value (\"<onjuiste waarde>\") not found in enum (possible values: [\"CBW\"])]
E	EBS-10060	Product ordered but no price available yet, please try again tomorrow
E	EBS-10073	The field EAN must be 13 long	WMS-00008	[ECMA 262 regex \"^([0-9]{13})$\" does not match input string \"<onjuiste waarde>\"]
E	EBS-10075	The field OrderReference must be maximum 100 long	WMS-00008	[string \"<onjuiste waarde>\" is too long (length: 168, maximum allowed: 100)]
E	EBS-10076	The field OrderReference is mandatory
E	EBS-10077	No order found with this OrderReference

Operation: checkOrderable

Web shops display their assortment in their windows and want to sell it to their customers. As soon as the customer wants to check-out the products in the shopping cart, the web shop requires the certainty that the article can be ordered. This moment comes ideally just before payment. If the required article cannot be ordered/delivered and the customer already paid, the web shop has additional work in correcting the payment and the customer will have a negative experience with the web shop. This method is used to make sure an e-book can be ordered/delivered. The reply indicates a Yes or No (Y or N).

Request

Parameter	Description	Optionality	Allowed values
EAN	The EAN of which availability and deliverability needs to be checked	Mandatory	13 positions
DeliveryChannel	The method the subscriber uses to read the digital product (Download or On-line reading in the Cloud).	Optional	CBW (CB registered web shop)

Response

Parameter

Description

Optionality

Allowed values

Orderable

Indicates orderability of the requested digital product through the desired channel.

Mandatory

Y (Yes = Orderable)

N (No = Not orderable)

Examples

Situation	Orderable product at CB
Request { "EAN": "9789084999813" }
Response { "Orderable": { "orderable": "Y" } }

Situation	Non-orderable product at CB
Request { "EAN": "9999999999999" }
Response { "Message": { "MessageType": "I", "MessageCode": "EBS-10003", "MessageText": "A product with this EAN is not available" }, "Orderable": { "orderable": "N" } }

Operation: placeOrder

Web shops want to deliver digital products to a customer. The web shop therefore needs to place an order with CB for the required article. CB will give feedback as to where the digital product is available. With a Bookshelf transaction, no link is returned. A Bookshelf order should be seen as a request to deliver the desired e-book to a certain Bookshelf platform-user. This makes it necessary to include the data of the Bookshelf user.

Request

Parameter	Description	Optionality	Allowed values
EAN	The EAN which is ordered	Mandatory	13 positions
DeliveryChannel	The method the subscriber uses to read the digital product (Download or On-line reading in the Cloud).	Optional	CBW (CB registered web shop)
OrderReference	This is an internal reference used by the CB-customer to identify the order. This identifier needs to be unique.	Mandatory	Max. 100 positions

Response

Parameter	Description	Optionality	Allowed values
CbOrderReference	Unique CB internal reference to identify the customer’s order.	Mandatory
EAN	The EAN of which the digital product is to be delivered.	Mandatory	13 positions
URL	URL of the address where the digital product is available for delivery. This is an URL to download digital product.	Optional

Examples

Situation

Orderable product at CB

Request

{
  "EAN": "9789084999813",
  "OrderReference" : "1423575022409"
}

Response

{
 "placeOrder": {
    "CbOrderReference": "1669231",
    "OrderedItem": [{
       "EAN": "9789084999813",
       "URL": "https://tstep2.eboekhuis.nl/wmDwld.php?uid=58403560d6961&ean=9789084999813&r=1"
        }]
  }
}

Situation	Non-orderable product at CB
Request { "EAN": "9999999999999", "OrderReference" : "1423575022409" }
Response { "Message": { "MessageType": "I", "MessageCode": "EBS-10003", "MessageText": "A product with this EAN is not available" } }

Operation: getContentUrl

This operation offers the CB-customer the possibility to retrieve the link to the content based on an existing order.

Request

Parameter	Description	Optionality	Allowed values
OrderReference	This is an internal reference used by the CB-customer to identify the order. This identifier needs to be unique.	Mandatory	Max. 100 positions

Response

Parameter	Description	Optionality	Allowed values
CbOrderReference	Unique Cbinternal reference to identify the customer’s order..	Mandatory
EAN	The EAN of which the digital product is to be delivered.	Mandatory	13 positions
URL	URL of the address where the digital product is available for delivery. This is an URL to download digital product	Mandatory

Examples

Situation	Valid OrderReference
Request { "OrderReference": "12345" }
Response { "getContentUrl": { "EAN": "9789084999813", "CbOrderReference": "87654, "URL": "https://tstep2.eboekhuis.nl/wmDwld.php?uid=58403560d6961&ean=9789084999813&r=1" } }

Situation	Invalid OrderReference

Request { "OrderReference": "4567" }
Response { "Message": { "MessageType": "I", "MessageCode": "EBS-10003", "MessageText": "A product with this EAN is not available" } }

General webservice information

Content-Type

The content/body in the request and the response has to be / will be in json format.

Content-Type

application/json

Servers
Production	https://services.cb.nl
Test	https://testservices.cb.nl

Supported SSL/TLS protocols
TLS Protocols	TLS1.0	As of May 17, 2021, CB will no longer support TLS 1.0 and 1.1
	TLS1.1
	TLS1.2
	TLS1.3

Authentication

CB uses message level authentication based on header parameters “UserName” and “Password”. These will be provided when you sign up for this service at CB.

Response messages

If a webservice is technical able to process, it will respond with a HTTP status 200. The response can contain a message with additional information. It can be an error (MessageType “E”) in case it wasn’t possible to supply a functional answer or additional explanation/information about the answer (MessageType “I”).

A message contains of:

A message contains of:
MessageType	E or I
MessageCode	format XXX-99999
MessageText	Textual information/reason

The following generic error (E) messages are defined:
WMS-00002	Invalid username/password combination
WMS-00004	Not authorized to use this service
WMS-00005	No username and/or password provided by the caller
EBS-11000	Something went wrong in processing the request
EBS-11001	Something went wrong in processing the request

Optional parameter

For any optional attribute one of the following options applies:

be filled with the correct value
be left out
be filled with “” (read empty)

An optional parameter may therefore never be filled with the value null.

Test environment

For information about the test environment and the available test titles see:

Click here for digital products for testing purposes

Verschijningsvorm	Beveiliging	EAN	*AuteurTitel**	Opmerking	Content titel
EPUB(2)	Geen DRM (00)	9789084999936	*VROUWENKIESRECHT	Alleen tekst	Zoenen met rommel
		9789491259142	VINK*FLORIS V EN DE SCHOTSE TROON	Alleen tekst	Filosofie van de bewegingswetenschappen
		9789491259104	VINK*LAATSTE DAGEN VAN FLORIS V	Alleen tekst	Filosofie van de bewegingswetenschappen
		9789078124832	VINK*DOOD VAN DANTES KEIZER	> 1000 tekens + plaatjes	Chief Thunderstruck and the big bad bear
		9789491259128	VINK*WREKER VAN FLORIS V	> 1000 tekens + plaatjes	The Lost history of 1914
		9789491259289	VIS*BARRABBAS	< 1000 tekens + plaatjes	Foto zegt meer dan 1000 woorden
		9789491259272	VIS*BRAINS	Alleen tekst	Filosofie van de bewegingswetenschappen
EPUB(2)	Watermerk (02)	9789084999820	*TESTEBOEK EPUB MET WATERMERK	Alleen tekst	Filosofie van de bewegingswetenschappen
		9789023443032	BOOGAARD*VERTICALE STRAND	Alleen tekst	Filosofie van de bewegingswetenschappen
		9789023467519	BORGART*ROOIERS	Alleen tekst	El Clasico
		9789023473411	BROUWERS*FENIKS	Alleen tekst	Filosofie van de bewegingswetenschappen
		9789023465423	CAMPERT*ALS IN EEN DROOM	Alleen tekst	Filosofie van de bewegingswetenschappen
		9789023442714	CAMPERT*AVONTUUR VAN IKS EN EI	Alleen tekst	El Clasico
		9789023466260	CAMPERT*MIJN EENMANSZAAK	Alleen tekst	Filosofie van de bewegingswetenschappen
		9789023473312	BROUWERS*CASINO	< 1000 tekens + plaatjes	Foto zegt meer dan 1000 woorden
		9789023443315	CAMPERT*LIEFDE IN PARIJS	< 1000 tekens + plaatjes	Foto zegt meer dan 1000 woorden
		9789023464921	CAMPERT*GANGSTERMEISJE	> 1000 tekens + plaatjes	Chief Thunderstruck and the big bad bear
		9789023471684	BRASSINGA*TUSSEN VIJF EN TWAALF	> 1000 tekens + plaatjes	The Lost history of 1914
		9789023467410	BORGART*VUILNISROOS	> 1000 tekens + plaatjes	Chief Thunderstruck and the big bad bear
		9789023465225	CAMPERT*GOUDEN DAGEN	> 1000 tekens + plaatjes	The Lost history of 1914
		9789084999974	GRUNBERG*EPUB2 MET VOETNOTEN EN VERWIJZINGEN	Epub2 met voetnoten en verwijzingen	The gradual acceptance of the Copernican theory of the universe
		9789084999981	GRUNBERG*EPUB2 MET TABELLEN	Epub2 met tabellen	Lectures on Stellar Statistics
EPUB(3)	Watermerk (02)	9789084999851	GRUNBERG*EPUB3 AUDIO EN VIDEO	Audio en video + tekst	EPUBTEST 0120 - Media Overlays Reflowable Tests
		9789084999868	GRUNBERG*EPUB3 FIXED LAYOUT	Fixed layout	EPUBTEST 0201 - FXL Support Tests
		9789084999875	GRUNBERG*EPUB3 FIXED LAYOUT SPREAD	Fixed layout spread	EPUBTEST 0202 - FXL Spreads (both) Tests
		9789084999882	GRUNBERG*EPUB3 REFLOWABLE CONTENT	Reflowable content	EPUBTEST 0202 - FXL Spreads (both) Tests
		9789084999905	GRUNBERG*EPUB3 MATHML EN SVG	MathML en SVG	A First Course in Linear Algebra
PDF	Geen DRM (00)	9789084999813	*TESTEBOEK PDF MET WATERMERK DRM	< 1000 tekens + plaatjes	Het Achterhuis
PDF	Watermerk (02)	9789084999813	*TESTEBOEK PDF MET WATERMERK DRM	< 1000 tekens + plaatjes	Het Achterhuis
		9789023465126	CAMPERT*SOMBERMAN'S ACTIE	< 1000 tekens + plaatjes	PDF ebook voor test doeleinden
		9789023472254	CAMPERT*VRIENDEN, VRIENDINNEN EN DE REST VAN DE	< 1000 tekens + plaatjes	PDF ebook voor test doeleinden
		9789023465324	CAMPERT*OHI, HOHO, BANG, BANG	> 1000 tekens + plaatjes	Reisgids Jordanie
		9789023450245	CAMPERT*OM VIJF UUR IN DE MIDDAG	> 1000 tekens + plaatjes	Reisgids Berlin
		9789023467304	CLAASSEN*PARK	> 1000 tekens + plaatjes	Reisgids Jordanie
		9789023442912	CAMPERT*SATIJNEN HART	> 1000 tekens + plaatjes	Professional tester issue 25
		9789023443292	CLAUS*GERUCHTEN	< 1000 tekens + plaatjes	PDF ebook voor test doeleinden
		9789023466123	CLAUS*HONDSDAGEN	< 1000 tekens + plaatjes	PDF ebook voor test doeleinden
		9789023466628	CLAUS*BELLADONNA	> 1000 tekens + plaatjes	Professional tester issue 25
		9789023465621	CHABOT*DIEPERE LAGEN	> 1000 tekens + plaatjes	Reisgids Berlin
		9789023449713	CLAUS*JAAR VAN DE KREEFT	141 MB	"De gorgel in arabisch oid"
		9789023443100	CAMPERT*VURRUKKULLUK	141 MB	"De gorgel in arabisch oid"
		9789084999929	GRUNBERG*PDF MET VOETNOTEN EN VERWIJZINGEN	PDF met voetnoten en verwijzingen	Project Gutenberg’s The Mathematical Analysis of Logic
MP3		9789058714961	DIJK*ASSERTIEF OP HET WERK		zip bestand
MP3		9789462100046	JANSEN*PADDEL AUDIOBOEK

Examples

CheckOrderable in C#

using System;
using System.Net;
using System.Web.Script.Serialization;
namespace CheckOrderable
{
    class Program
    {
        static void Main(string[] args)
        {
            var ean = "9789084999936";
            string result = getCheckOrderable(ean);
            var objectResult = new JavaScriptSerializer().DeserializeObject(result);
             
            Console.Write(result);
            Console.WriteLine(); Console.WriteLine();
            Console.WriteLine("Press a key to exit");
            Console.ReadKey();
        }
        public static string getCheckOrderable(string ean)
        {
            var webclient = new WebClient();
            webclient.Headers.Add("Accept", "application/json");
            webclient.Headers.Add("Content-Type", "application/json");
            webclient.Headers.Add("UserName", "_SNIP_");
            webclient.Headers.Add("Password", "_SNIP_");
            var url = "https://testservices.cb.nl/rest/api/v1/DigitalProductOrderService/checkOrderable";
            var data = new JavaScriptSerializer().Serialize(new { EAN = ean, DeliveryChannel = "CBW" });
            var response = webclient.UploadString(url, data);
            return response;
        }
    }
}

Volume limits and performance requirements

Volume

Webservice calls are limited to a maximum of 5 web service calls per account at the same time.

Performance

Availability: 99% measured over the last 12 months, excluding planned maintenance.
The response time is a maximum of 2000 ms in 95% of the cases, measured as an average over 10 minutes.

Browser not supported