Webservice DigitalProductOrderService

Revision

DateDescription

 

Delivery Channel BS (Bookshelf) is deprecated

 

As of July 1, 2022, CB will no longer support Bookshelf

 

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

Some of EBS-* error code will change to WMS-* codes 

 

As of May 17, 2021, CB will no longer support TLS 1.0 and 1.1

 

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:

TypeCodeTextNew code

New text 

Date to be announced


E

EBS-10001

The field EAN is mandatoryWMS-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



EEBS-10034This product is not available for the given reading method

E

EBS-10038

Vitalsource user account unknown



EEBS-10056Invalid value for DeliveryChannelWMS-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



EEBS-10073The field EAN must be 13 longWMS-00008[ECMA 262 regex \"^([0-9]{13})$\" does not match input string \"<onjuiste waarde>\"]
EEBS-10075The field OrderReference must be maximum 100 longWMS-00008[string \"<onjuiste waarde>\" is too long (length: 168, maximum allowed: 100)]
EEBS-10076The 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)
BS (BookShelf) deprecated

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

SituationOrderable product at CB
Request
{
  "EAN": "9789084999813"
}
Response
{
  "Orderable": {
     "orderable": "Y" 
  }
}
SituationNon-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 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)
BS (BookShelf)  deprecated

OrderReferenceThis 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

SituationOrderable 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"
        }]
  }
}
SituationNon-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. This operation does not support Bookshelf orders.

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

SituationValid OrderReference
Request
{
  "OrderReference": "12345"
}
Response
{
  "getContentUrl": {
    "EAN": "9789084999813",
    "CbOrderReference": "87654,
    "URL": "https://tstep2.eboekhuis.nl/wmDwld.php?uid=58403560d6961&ean=9789084999813&r=1" 
  }
}
SituationInvalid 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-Typeapplication/json

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:
MessageTypeE or I
MessageCodeformat XXX-99999
MessageTextTextual information/reason

The following generic error (E) messages are defined:

WMS-00002Invalid username/password combination
WMS-00004Not authorized to use this service
WMS-00005No username and/or password provided by the caller
EBS-11000Something went wrong in processing the request
EBS-11001Something 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

Auteur*Titel

Opmerking

Content titel

EPUB(2)






Geen DRM (00)






9789084999936*VROUWENKIESRECHTAlleen tekstZoenen met rommel
9789491259142VINK*FLORIS V EN DE SCHOTSE TROONAlleen tekstFilosofie van de bewegingswetenschappen
9789491259104VINK*LAATSTE DAGEN VAN FLORIS VAlleen tekstFilosofie van de bewegingswetenschappen
9789078124832VINK*DOOD VAN DANTES KEIZER> 1000 tekens + plaatjesChief Thunderstruck and the big bad bear
9789491259128VINK*WREKER VAN FLORIS V> 1000 tekens + plaatjesThe Lost history of 1914
9789491259289VIS*BARRABBAS< 1000 tekens + plaatjesFoto zegt meer dan 1000 woorden
9789491259272VIS*BRAINSAlleen tekstFilosofie van de bewegingswetenschappen

EPUB(2)















Watermerk (02)















9789084999820*TESTEBOEK EPUB MET WATERMERKAlleen tekstFilosofie van de bewegingswetenschappen
9789023443032

BOOGAARD*VERTICALE STRAND

Alleen tekstFilosofie van de bewegingswetenschappen
9789023467519BORGART*ROOIERSAlleen tekstEl Clasico
9789023473411BROUWERS*FENIKSAlleen tekstFilosofie van de bewegingswetenschappen
9789023465423

CAMPERT*ALS IN EEN DROOM

Alleen tekstFilosofie van de bewegingswetenschappen
9789023442714

CAMPERT*AVONTUUR VAN IKS EN EI

Alleen tekstEl Clasico
9789023466260

CAMPERT*MIJN EENMANSZAAK

Alleen tekstFilosofie van de bewegingswetenschappen
9789023473312BROUWERS*CASINO< 1000 tekens + plaatjesFoto zegt meer dan 1000 woorden
9789023443315

CAMPERT*LIEFDE IN PARIJS

< 1000 tekens + plaatjesFoto zegt meer dan 1000 woorden
9789023464921

CAMPERT*GANGSTERMEISJE

> 1000 tekens + plaatjesChief Thunderstruck and the big bad bear
9789023471684BRASSINGA*TUSSEN VIJF EN TWAALF> 1000 tekens + plaatjesThe Lost history of 1914
9789023467410BORGART*VUILNISROOS> 1000 tekens + plaatjesChief Thunderstruck and the big bad bear
9789023465225

CAMPERT*GOUDEN DAGEN

> 1000 tekens + plaatjesThe Lost history of 1914
9789084999974GRUNBERG*EPUB2 MET VOETNOTEN EN VERWIJZINGENEpub2 met voetnoten en verwijzingenThe gradual acceptance of the Copernican theory of the universe
9789084999981GRUNBERG*EPUB2 MET TABELLENEpub2 met tabellenLectures on Stellar Statistics
EPUB(3)




Watermerk (02)




9789084999851GRUNBERG*EPUB3 AUDIO EN VIDEOAudio en video + tekstEPUBTEST 0120 - Media Overlays Reflowable Tests
9789084999868GRUNBERG*EPUB3 FIXED LAYOUTFixed layoutEPUBTEST 0201 - FXL Support Tests
9789084999875GRUNBERG*EPUB3 FIXED LAYOUT SPREADFixed layout spreadEPUBTEST 0202 - FXL Spreads (both) Tests
9789084999882GRUNBERG*EPUB3 REFLOWABLE CONTENTReflowable contentEPUBTEST 0202 - FXL Spreads (both) Tests
9789084999905GRUNBERG*EPUB3 MATHML EN SVGMathML en SVGA First Course in Linear Algebra
PDFGeen DRM (00)9789084999813*TESTEBOEK PDF MET WATERMERK DRM< 1000 tekens + plaatjesHet Achterhuis

PDF














Watermerk (02)














9789084999813*TESTEBOEK PDF MET WATERMERK DRM< 1000 tekens + plaatjesHet Achterhuis
9789023465126

CAMPERT*SOMBERMAN'S ACTIE

< 1000 tekens + plaatjesPDF ebook voor test doeleinden
9789023472254CAMPERT*VRIENDEN, VRIENDINNEN EN DE REST VAN DE< 1000 tekens + plaatjesPDF ebook voor test doeleinden
9789023465324

CAMPERT*OHI, HOHO, BANG, BANG

> 1000 tekens + plaatjesReisgids Jordanie
9789023450245

CAMPERT*OM VIJF UUR IN DE MIDDAG

> 1000 tekens + plaatjesReisgids Berlin
9789023467304CLAASSEN*PARK> 1000 tekens + plaatjesReisgids Jordanie
9789023442912

CAMPERT*SATIJNEN HART

> 1000 tekens + plaatjesProfessional tester issue 25
9789023443292

CLAUS*GERUCHTEN

< 1000 tekens + plaatjesPDF ebook voor test doeleinden
9789023466123

CLAUS*HONDSDAGEN

< 1000 tekens + plaatjesPDF ebook voor test doeleinden
9789023466628

CLAUS*BELLADONNA

> 1000 tekens + plaatjesProfessional tester issue 25
9789023465621

CHABOT*DIEPERE LAGEN

> 1000 tekens + plaatjesReisgids Berlin
9789023449713

CLAUS*JAAR VAN DE KREEFT

141 MB"De gorgel in arabisch oid"
9789023443100

CAMPERT*VURRUKKULLUK

141 MB"De gorgel in arabisch oid"
9789084999929GRUNBERG*PDF MET VOETNOTEN EN VERWIJZINGENPDF met voetnoten en verwijzingenProject Gutenberg’s The Mathematical Analysis of Logic
MP3




9789058714961DIJK*ASSERTIEF OP HET WERK
zip bestand

9789462100046

JANSEN*PADDEL AUDIOBOEK



Examples

CheckOrderable in PHP with SOAP
<?php
$ean = "9789084999936";
//Create the client object
$soapclient = new SoapClient('https://testservices.cb.nl/soap/api/v1/DigitalProductOrderService/DigitalProductOrderService?wsdl');
$userNameHdr = new SoapHeader('cb.services.soap', 'UserName', '_SNIP_', false);
$passwordHdr = new SoapHeader('cb.services.soap', 'Password', '_SNIP_', false);
$soapclient->__setSoapHeaders(array($userNameHdr, $passwordHdr));
$params = array();
$params[] = new SoapVar($ean, XSD_STRING, null, null, 'EAN');
$params[] = new SoapVar("CBW", XSD_STRING, null, null, 'DeliveryChannel');
$Arg2 = new SoapVar($params, SOAP_ENC_OBJECT, null, null, 'arg2');
$response = $soapclient->checkOrderable($Arg2);
echo 'SOAP';
echo '<br><br>EAN: ' . $ean.'<br />';
echo 'Available: ' .  $response->Orderable->orderable .'<br />'; 
PlaceOrder in PHP met SOAP
 <?php
 $ean = "9789084999936";
   $orderreference = 'b5'; // iedere keer een unieke kode opgeven
   $username = "_SNAP";
   $password = "_SNAP_";
   //Create the client object
   $soapclient = new SoapClient('https://testservices.cb.nl/soap/api/v1/DigitalProductOrderService/DigitalProductOrderService?wsdl'
     );
       
   $userNameHdr = new SoapHeader('cb.services.soap', 'UserName', $username, false);
   $passwordHdr = new SoapHeader('cb.services.soap', 'Password', $password, false);
   $soapclient->__setSoapHeaders(array($userNameHdr, $passwordHdr));
   $params = array();
   $params[] = new SoapVar($ean, XSD_STRING, null, null, 'EAN');
   $params[] = new SoapVar("CBW", XSD_STRING, null, null, 'DeliveryChannel');
   $params[] = new SoapVar($orderreference, XSD_STRING, null, null, 'OrderReference');
   $Arg2 = new SoapVar($params, SOAP_ENC_OBJECT, null, null, 'arg2');
   $response = $soapclient->placeOrder($Arg2);
    
   echo 'EAN: ' . $ean.'<br />';
   echo 'URL: ' .  $response->placeOrder->OrderedItem->URL .'<br />';
   echo 'CbOrderReference: ' .  $response->placeOrder->CbOrderReference .'<br />';
   echo 'EAN: ' .  $response->placeOrder->OrderedItem->EAN .'<br />';
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.