4) Bookshelf workflow - Assign Content

Let us imagine a user who has complete the search pictured below. As an e-commerce vendor, you will first process the financial transaction, then you will wish to fetch the content from VitalSource and place it in the user's account. We call this assigning content, and this section of the guide will take you through the various endpoints needed to perform this action.

Catalog Results

Region_capture_89.png

It is presumed that before you attempt to perform the next steps you will first possess complete and verified user credentials. If you need guidance on this, you can go to the verify credentials section of the e-commerce workflow. 

 Assigning content combines many elements of our service and thus requires multiple endpoints. These steps are as follows:

  • Get a license
  • Create a redeemable code for the content
  • Redeem the code and assign the content to user

Get License

When the user clicks on a product you will use their credentials to attempt to GET v3/licenses - Read to ensure the user does not already have this product.

  • To successfully work with this endpoint you will need: 

    • A valid API key
    • User access token
    • SKU of the product the user selected (optional, inserted into the header)

Below is curl statement that can be pasted into a command line:

curl -X GET \https://api.vitalsource.com/v3/licenses.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

Successful response will include:

  • All licenses associated with this user access token
  • Details of the SKU, Imprint, etc.
<?xml version="1.0" encoding="UTF-8"?>
<licenses>
   <summary distributable_products="1" total_products="1"/>
   <license imprint="VitalSource Technologies" publisher="VitalSource Technologies"     name="Bookshelf Tutorial Updated" sku="BOOKSHELF-TUTORIAL" isbn="BOOKSHELF-TUTORIAL" part_of="" type="online" term="" expiration="never" code-use="code-api"/>
</licenses>

A valid license means that the user already has access to the content and it's in their account. Conversely, absence of a license means that you must redeem (and likely create) a code for this content so that they are then granted a license.

Create Code

Using the v3/codes - Create endpoint, you will generate a unique code that can either be given to users or you can redeem it on their behalf as part of a workflow. It should be stressed that creating codes is usually a billable event, depending on your agreement with VitalSource.

Codes combine multiple properties in the body of the request and our servers place these elements in the license file of the content upon redemption of the code. The definable elements are:

  • License type: There are multiple choices available (perpetual, numdays, absdate, default, noaccess)
  • Price: Should you wish not to use the standard price from your agreement

The required fields in the body of the request are:

  • If you chose absdate, then you will need day/month/year of expiration
  • If your chose numdays, then you will need the number of days for expiration

To succeed with this endpoint you will need:

Below is a curl statement to work with this endpoint

curl -X GET \https://api.vitalsource.com/v3/licenses.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="BOOKSHELF-TUTORIAL" license-type="default" num-codes="1"/>Successful response will include:

Successful response will include:

      • The requested codes
<?xml version="1.0" encoding="UTF-8"?>
<codes>
  <code>HHTTJMPTEDFYYYMRH5K</code>
</codes>

Users with full accounts will be accustomed to redeeming codes themselves within the application or online product. Codes can also be disseminated to users as you see fit in an institutional setting, but wherever possible we encourage you to redeem the code on behalf of users to streamline the experience and minimize errors.

Redeem Code

Having created a new code(s) you can redeem it using the v3/redemptions - redeem code endpoint and place the content, via a license, in the users VitalSource account  You will need:

  • A valid API key
  • User access token
  • Code that you just created for this user

Below is a curl statement to work with this endpoint

curl -X GET \https://api.vitalsource.com/v3/redemptions.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<?xml version="1.0" encoding="UTF-8"?>
<redemption>
   <code>4VJB7GGGG33P1111WN</code>
</redemption> 

Successful response will include:

  • The SKU details
<?xml version="1.0" encoding="UTF-8"?>
<library>
      <item href="vbk:BOOKSHELF-TUTORIAL" author="VSM" title="Bookshelf Tutorial Updated">
  </item>
</library>

The endpoint will respond with all redeemed items within a library tag, marked as items. This structure is designed around the fact that the v3/redemptions - redeem code endpoint accepts both single and bulk transactions. From an efficiency perspective we recommend collecting codes and grouping them into bulk requests per user whenever possible.  

This completes the workflow of assigning content and the next step in an e-commerce workflow is to Redirect SSO

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.