Revision
Version | Date | Description |
---|---|---|
0.1 |
| Initial document |
Introduction Afbeelding nog vervangen
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. |
Test environment
For information about the test environment and the available test titles see:
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." }} |
*********************************
For testing the following data is available (other data will result in an error response):
Invalid Vitalsource account credentials (UserId/UserPassword) | Tester@cb-logistics.nl / bookshelf |
Valid Vitalsource account credentials (UserId/UserPassword) | bookshelf@cb-logistics.nl / bookshelf |
Accessible EAN | 9789084999912 |
Inaccessible EAN | 8711000287941 |
Operation: checkAccess
This operation gives as answer if the supplied Bookshelf/VitalSource user has access to the supplied product (purchased on Bookshelf/VitalSource).
It can be used for example on a publisher website for checking if the user should be granted access to specific digital content that is only available for users who purchased the related product.
Request
- EAN : The EAN of the product/title that has to be checked (required)
- UserId : Identifier of the Bookshelf/VitalSource user (required)
- UserPassword : Password of the Bookshelf/VitalSource user (required)
Response
- Accessable : Indication (Y/N) if the user has access tot he specified product.
Examples
Situation | valid Bookshelf/VitalSource user and inaccessible product |
---|---|
Request { "EAN": "9789084999912", "UserId": "bookshelf@cb-logistics.nl", "UserPassword": "bookshelf" } | |
Response { "Access": { "Accessable": "Y" } } |
Situation | unknown Bookshelf/VitalSource user |
---|---|
Request { "EAN": "8711000287941", "UserId": "bookshelf@cb-logistics.nl", "UserPassword": "bookshelf" } | |
Response { "Access": { "Accessable": "N" } } |
Situation | unknown Bookshelf/VitalSource user |
---|---|
Request { "EAN": "9789084999912", "UserId": "Tester@cb-logistics.nl", "UserPassword": "bookshelf" } | |
Response { "Message": { "MessageType": "I", "MessageCode": "EBS-10038", "MessageText": "Vitalsource user account unknown." }, "Access": { "Accessable": "N" } } |
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.