Webservice DigitalProductOrderService
- Wilma Valkis - Temminck
Revision
| Date | Description |
|---|---|
 | 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:
| 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 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) |
| 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. 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
| 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:
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.