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. |
Current error code | Current error message | New error code | New error message |
EBS-10063 | The field EAN is mandatory. | WMS-00008 | [object has missing required properties ([\"EAN\"])] |
EBS-10064 | The field ReadingMethod is mandatory. | WMS-00008 | [object has missing required properties ([\"ReadingMethod\"])] |
EBS-10065 | The field Protection is mandatory. | WMS-00008 | [object has missing required properties ([\"Protection \"])] |
EBS-10066 | The field RentalUnit is mandatory. | WMS-00008 | [object has missing required properties ([\"RentalUnit \"])] |
EBS-10067 | The field RentalNumberOfUnits is mandatory. | WMS-00008 | [object has missing required properties ([\"RentalNumberOfUnits \"])] |
EBS-10068 | The field OrderReference is mandatory. | WMS-00008 | [object has missing required properties ([\"OrderReference \"])] |
EBS-10069 | The field UserId is mandatory. | WMS-00008 | [object has missing required properties ([\"UserId \"])] |
EBS-10070 | Invalid value for ReadingMethod. | WMS-00008 | [instance value (\"<onjuiste waarde>\") not found in enum (possible values: [\"D\",\"CR\"])] |
EBS-10071 | Invalid value for Protection. | WMS-00008 | [instance value (\"<onjuiste waarde>\") not found in enum (possible values: [\"00\",\"02\",\"03\"])] |
EBS-10072 | Invalid value for RentalUnit. | WMS-00008 | [instance value (\"<onjuiste waarde>\") not found in enum (possible values: [\"DAG\"])] |
EBS-10073 | The field EAN must be 13 long. | WMS-00008 | [ECMA 262 regex \"^([0-9]{13})$\" does not match input string \"<onjuiste waarde>\"] |
EBS-10074 | The field RentalNumberOfUnits must be numeric (1-99999). | WMS-00008 | [ECMA 262 regex \"^(2[01]|1[0-9]|[1-9])$\" does not match input string \"<onjuiste waarde>\"] |
EBS-10075 | The field OrderReference must be maximum 100 long. | WMS-00008 | [string \"<onjuiste waarde>\" is too long (length: 168, maximum allowed: 100)] |
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.
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.