Revision
| Version | Date | Description |
|---|---|---|
| 0.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. |
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.