Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

Revision

DateDescription

 

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

Delivery channel: Bookshelf

A Bookshelf order must be seen as a request to send a specific e-book to a certain user on the Bookshelf platform. It is therefore necessary to include the information of the Bookshelf- user with the order. If the user does not already have a Bookshelf account, an account can be made through the registration form below: 

https://bookshelf.vitalsource.com/#/user/registration

Specific messages (type/code/text) for this webservice:

TypeCodeTextNew code

New text 

Date to be announced


E

EBS-10001

The field EAN is mandatoryWMS-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



EEBS-10034This product is not available for the given reading method

E

EBS-10038

Vitalsource user account unknown



EEBS-10050The field DeliveryChannel is mandatoryWMS-00008[object has missing required properties ([\"DeliveryChannel\"])]
EEBS-10056Invalid value for DeliveryChannelWMS-00008[instance value (\"<onjuiste waarde>\") not found in enum (possible values: [\"CBW\",\"BS\"])]

E

EBS-10057

UserId is mandatory for Bookshelf order



E

EBS-10060

Product ordered but no price available yet, please try again tomorrow



EEBS-10073The field EAN must be 13 longWMS-00008[ECMA 262 regex \"^([0-9]{13})$\" does not match input string \"<onjuiste waarde>\"]
EEBS-10075The field OrderReference must be maximum 100 longWMS-00008[string \"<onjuiste waarde>\" is too long (length: 168, maximum allowed: 100)]
EEBS-10076The 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).

Mandatory

CBW (CB registered web shop)
BS (BookShelf)

UserId

The identification of the end user. Is used to authenticate the end user (subscriber of the customer) upon delivery of the digital product.

Optional

Max. 50 positions

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

SituationOrderable product at CB
Request
{
  "EAN": "9789084999813",
  "DeliveryChannel": "CBW"
}
Response
{
  "Orderable": {
     "orderable": "Y" 
  }
}
SituationOrderable product at Bookshelf

Request
{
  "EAN": "9789084999813",
  "DeliveryChannel": "BS",
  "UserId": "bookshelf@cb-logistics.nl"
}
Response
{
  "Orderable": {
     "orderable": "Y" 
    }
}
SituationNon-orderable product at CB
Request
{
  "EAN": "9999999999999",
  "DeliveryChannel": "CBW"
}
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).

Mandatory

CBW (CB registered web shop)
BS (BookShelf)

UserId

The identification of the end user. Is used to authenticate the end user (subscriber of the customer) upon delivery of the digital product.

Optional

Max. 50 positions

OrderReferenceThis 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

SituationOrderable product at CB
Request
{
  "EAN": "9789084999813",
  "OrderReference" : "1423575022409",
  "DeliveryChannel": "CBW"
}
Response
{
 "placeOrder": {
    "CbOrderReference": "1669231",
    "OrderedItem": [{
       "EAN": "9789084999813",
       "URL": "https://tstep2.eboekhuis.nl/wmDwld.php?uid=58403560d6961&ean=9789084999813&r=1"
        }]
  }
}
SituationOrderable product at Bookshelf
Request
{
  "EAN": "9789084999813",
  "OrderReference" : "1423575022409",
  "DeliveryChannel": "BS",
  "UserId": "bookshelf@cb-logistics.nl"
}
Response
{
 "placeOrder": {
    "CbOrderReference": "1669231",
    "OrderedItem": [{
       "EAN": "9789084999813"
       }]
  }
}
SituationNon-orderable product at CB
Request
{
  "EAN": "9999999999999",
  "OrderReference" : "1423575022409",
  "DeliveryChannel": "CBW"
}
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

SituationValid OrderReference
Request
{
  "OrderReference": "12345"
}
Response
{
  "getContentUrl": {
    "EAN": "9789084999813",
    "CbOrderReference": "87654,
    "URL": "https://tstep2.eboekhuis.nl/wmDwld.php?uid=58403560d6961&ean=9789084999813&r=1" 
  }
}
SituationInvalid 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-Typeapplication/json

Servers

Productionhttps://services.cb.nl
Testhttps://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:
MessageTypeE or I
MessageCodeformat XXX-99999
MessageTextTextual information/reason

The following generic error (E) messages are defined:

WMS-00002Invalid username/password combination
WMS-00004Not authorized to use this service
WMS-00005No username and/or password provided by the caller
EBS-11000Something went wrong in processing the request
EBS-11001Something 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.

Unable to render {include} The included page could not be found.

Unable to render {include} The included page could not be found.


  • No labels