Webservice DigitalProductRentalService

Revision

DateDescription

 

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

 

Initial document

Introduction 


This web service is intended to support the order process of customers of CB for the temporary availability (renting) of digital products.

It has the following operation:

  • placeOrder

Path: /rest/api/v1/DigitalProductRentalService

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

Type

Code

Text

E

EBS-00001

Something went wrong in processing the order. Your order is not fulfilled.

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

Your credit limit has been exceeded.

E

EBS-10034

This product is not available for the given reading method.

E

EBS-10043

The combination of ReadingMethods and Protection is not allowed

E

EBS-10045

No valid license model found for this order

E

EBS-10046

For licensing models Shoulder and Tail, the rental period has to be 3 weeks

E

EBS-10053

Referenced order not found

E

EBS-10054

Referenced order is not for the same UserId

E

EBS-10060

Product ordered but no price available yet, please try again tomorrow.

EEBS-10063

The field EAN is mandatory

E

EBS-10064

The field ReadingMethod is mandatory

E

EBS-10065

The field Protection is mandatory

E

EBS-10066

The field RentalUnit is mandator

E

EBS-10067

The field RentalNumberOfUnits is mandator

E

EBS-10068

The field OrderReference is mandatory

E

EBS-10069

The field UserId is mandatory

E

EBS-10070

Invalid value for ReadingMethod

E

EBS-10071

Invalid value for Protection

E

EBS-10072

Invalid value for RentalUnit

E

EBS-10073

The field EAN must be 13 long

E

EBS-10074

The field RentalNumberOfUnits must be numeric (1-99999)

E

EBS-10075

The field OrderReference must be maximum 100 long


Operation: placeOrder

This operation is used to place orders with the purpose of renting out digital products to subscribers. The customer places an order for a title the subscriber would like to rent. The operation returns an url to where the digital product is available.

Request

Parameter

Description

Optionality

Allowed values

EAN

The EAN for which the order is placed

Mandatory

13 positions

ReadingMethod

The method the subscriber uses to read the digital product (Download or On-line reading in the Cloud).

Mandatory

D (Download)
CR (CloudReading)

Protection

The security that needs to be included in the delivery of the digital order product.

Mandatory

00 (no protection)
02 (watermark protection)
03 (Adobe DRM)

The following combinations are currently supported:

  • ReadingMethod CR en Protection 02 (on-line reading)
  • ReadingMethod  D  en  Protection 02 (reading by app on tablet and phone)
  • ReadingMethod  D  en  Protection 03 (reading by e-reader)

RentalUnit

The rental unit

Mandatory

DAG

RentalNumberOfUnits

The number of rental units

Mandatory

max 21

OrderReference

This is the internal reference of the customer to identify the order. This reference needs to be customer-unique.

Mandatory

max. 100 positions

UserId

The identification of the end user. Is used to authenticate the end user (subscriber of the customer) upon delivery of the digital product.

Mandatory

Also used to validate the addition. The addition must be for the same user

CbOrderReference

The unique value of the CbOrderReference of a previously executed order to deliver digital products.

Optional

Also used to check whether an addition may be made to a previously executed order.

Response

Parameter

Description

Optionality

Allowed values

CbOrderReference

Unique CB internal reference to identify the customer order.

Mandatory


EAN

The EAN from which the digital product is delivered.

Mandatory

13 positions

URL

URL of the address where the digital product is available for delivery. Involves a URL to download a digital product.

Mandatory


Examples


Situation

Available product

Request
{
  "EAN": "9e789084999813",
  "ReadingMethod": "D",
  "Protection": "02",
  "RentalUnit": "DAG",
  "RentalNumberOfUnits": "21",
  "OrderReference": "123abc",
  "UserId": "XYZ"
}
Response
{"placeOrder": {
   "CbOrderReference": "1669231",
   "EAN": "9789084999813",
   "URL": "https://tstep2.eboekhuis.nl/wmDwld.php?uid=58403560d6961&ean=9789084999813&r=1"
}}

Situation

Unavailable product

Request
{
  "EAN": "9999999999999",
  "ReadingMethod": "D",
  "Protection": "02",
  "RentalUnit": "DAG",
  "RentalNumberOfUnits": "21",
  "OrderReference": "123abc",
  "UserId": "XYZ"
}
Response
{"Message": {
   "MessageType": "E",
   "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 40 web service calls 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.