4) Bookshelf workflow - Fulfillment

What is fulfillment?

Fulfillment of content at VitalSource requires foreknowledge of the following items:

• The SKU or asset
• User credentials
• Licensing outcomes

The v4/fulfillment API combines three existing APIs into one request so you can accomplish the workflow below in just one step:

1. Check a user license at GET v3/licenses - Read
2. Make a code at POST v3/codes- Create
3. Redeem the code into the user account at POST v3/redemptions - Redeem

SKU

The VitalBookID (VBID) for the title. To determine your available catalog make the GET v4/products/ request. Payload from that endpoint will contain "vbid", "sku" and "eisbn_canonical". Along with "fpid" from legacy integrations, all of these options are acceptable as sku="L-999-70461"

If we are using the example of an online store you would want the cover image of the title. Within the payload of v4/products you will find "resource_links" and then you could make a secondary request to this URL (that actually does not need an API key, it is an open URL.)

"cover_image": "https://covers.vitalbook.com/vbid/L-999-70461/width/480"

This would allow you to render the cover image for your title:

Fulfillment API

For a complete explanation of the logic structures that support the fulfillment API please go to the documentation here. 

The primary value of the fulfillment API is that it will prevent creation of duplicate codes (where a user already owns the title) and can be used to ensure minimum terms of access as well. When used fully the fulfillment API logic is outcome based. I.e. We want users to have access to this title for 365 days from issue, or until this date (end of the semester), or forever, or even not at all. The API will first check against your desired minimum outcome and secondarily it will then issue a code and redeem it into the user account should it be needed. 

Receiving a failure from an API is in most cases a sign of something going wrong, but with the fulfillment API the error codes, 422 in particular, are sign that your (ensure) logic has prevented issuance of a duplicate code and the billing and support problem that this would cause.

Example Fulfillment

Below is an example we will examine

POST https://api.vitalsource.com/v4/fulfillments

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS
X-VitalSource-Access-Token: lowercaseandnumbers
Content-Type: application/json

Request body

{
   "fulfillment": {
      "sku": "L-999-70461",
      "term": "2021-06-30 23:59:59",
      "online_term" : "2021-06-30 23:59:59", 
      "ensure_days": "180",
      "tag": "Bookshelf_workflow_test_001"
   }
}

In the request above we are asking the VitalSource fulfillment API to perform the following action:

1. API key - defines area of logical separation for content and users
2. Access token - defines the specific Bookshelf user whose account you wish to add content into
3. sku - the specific title to be added into the user account
4. term - expiration, in UTC, for the title in the installed applications
5. online_term - expiration, in UTC, for the title in online use of Bookshelf
6. ensure - the minimum number of days that your organization wishes to use as a base level of access for licensing. 
   • I.e. You grant licenses until the end of the semester (end of June) but also pass an ensure of 180 days) which means that late joining students, etc. will get 180 day licenses while most others will get end of semester licenses. 
7. tag - an informational field used by your to track your activity within VitalSource 

Response body

{
   "code": "LETTERSANDNUMBERS",
   "sku": "L-999-70461",
   "download_license": {
     "details": "Expires at 2021-06-30 23:59:59 UTC",
     "duration": "Until 2021-06-30 23:59:59 UTC"
   },
   "online_license": {
     "details": "Expires at 2021-06-30 23:59:59 UTC",
     "duration": "Until 2021-06-30 23:59:59 UTC"
   },
   "title": "A Christmas Carol",
   "vbid": "L-999-70461",
   "author": "Charles Dickens",
   "imprint": "Originals",
   "publisher": "Hayes Barton Press"
}

What will happen if you resend the same payload again to the fulfillment API?

Request body

{
   "fulfillment": {
      "sku": "L-999-70461",
      "term": "2021-06-30 23:59:59",
      "online_term" : "2021-06-30 23:59:59", 
      "ensure_days": "180",
      "tag": "Bookshelf_workflow_test_001"
   }
}

Response body

HTTP 422 
{
   "errors": [
   "user guid LETTERSANDNUMBERS already has at least 180 days of access to product L-999-70461 "
   ]
}

As you can see the API protects against the issuance of additional codes and instead will generate a 422 + payload that informs you of what has happened.

This completes the workflow of assigning content and the next step in the Bookshelf workflow is to Redirect SSO