Webservice DigitalProductRentalService
- Wilma Valkis - Temminck
Revision
| Date | Description |
|---|---|
 | 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. |
| E | EBS-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) |
Protection | The security that needs to be included in the delivery of the digital order product. | Mandatory | 00 (no protection)
|
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-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 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.