RedShelf Store API¶

The following information describes how API partners can utilize the RedShelf Store API to complete API requests. This API was designed to support Point-of-Sales Systems. Due to certain limitiatons imposed by this use case, API requests differ from the rest of the RedShelf APIs in structure and authentication methods, which are explained below.

Purchase is for giving users authorization to an eBook via an access code. Refund is for canceling a previous Purchase request and voiding the access code.

Authentication¶

Authentication is accomplished through a token that is created by RedShelf and given to the POS System. Each store that has an installation of the POS System requires a separate token.

Request Format¶

All requests in these APIs can be sent as a POST or GET. The URIs are documented below but the domain where the requests should be made is the white label of the POS System’s store e.g. https://mybookstore.redshelf.com

API Errors¶

In the event of an error occurring while processing your request, the RedShelf API will return an HTTP response code and a description of the error. The following are the possible returned HTTP response codes: 503: Indicates a general server issue 403: Indicates that you lack the authorization for the request we received 400: Indicates you sent an incorrect or malformed response

In addition to the HTTP response code, we will also provide an XML body that contains a description of the errors encountered.

<error>
    The following errors were detected:
  <message>{{Detailed Error Message}}</message>
</error>

The Detailed Error Message possibilities are described with the API endpoints.

Purchase Endpoint¶

/api/purchase/

Creates an access code for a user and book. The code is only valid for the eBook indicated in the request. The access code is redeemable at the URL provided in the response. Once redeemed, the code is no longer refundable. This endpoint is idempotent and repeated calls with the same parameters will return the same access code.

Request Parameters

san: SAN Identifier of the store
token: Authorization token provided by RedShelf
partner_transact_id: A transaction identifier that is created by the Partner. This transaction ID should be unique within a store, but does not need to be unique across all stores. This is the value that will be used when calling future Refund operations.
book_id: The title identifier of the desired eBook and duration option e.g. 079778976077. This value is normally received via the Catalogue API as sku.
email: (Optional) Add book to user account directly, without needing an access code. If supplied, no access code or access url will be in the response
first_name: (Optional) Purchaser’s first name
last_name: (Optional) Purchaser’s last name
send_email: (Optional) Boolean which specifies whether to send an email to the user specified in the email parameter above

Response Parameters

partner_transact_id: Matches the partner transaction identifier that was originally provided by the partner store
vendor_transact_id: The transaction identifier generated by RedShelf. This is included for logging and transaction auditing purposes.
access_code: The access code to be printed on the receipt to give access to the requested book. Will not exist if email is supplied in the request.
access_url: Contains the web address (URL) where the customer can enter the access_code to gain access to the requested book. Will not exist if email is supplied in the request.

Example Request

https://mybookstore.redshelf.com/api/purchase/

POST DATA

token=3ft49ki3awf7

san=1234567

partner_transact_id=878341937616

book_id=079778976077

Example Success Response

<result>
   <access_code>3151A4feAA</access_code>
   <partner_transact_id>1232234</partner_transact_id>
   <vendor_transact_id>14943</vendor_transact_id>
   <access_url>https://mybookstore.redshelf.com</access_url>
</result>

Error Messages

<message>The san parameter has not been provided or is malformed</message>
<message>The token parameter has not been provided or is malformed</message>
<message>The partner_transact_id parameter has not been provided or is malformed</message>
<message>The book_id parameter has not been provided or is malformed</message>
<message>SAN does not conform to SAN specifications</message>
<message>The store is not registered on RedShelf</message>
<message>Invalid Authorization Token</message>
<message>The submitted partner_transact_id has already been submitted for this store</message>
<message>The submitted book_id cannot be found in system</message>
<message>The submitted book_id is not available for fulfillment at this time</message>
<message>The submitted email is incorrectly formatted</message>

Example Request

https://mybookstore.redshelf.com/api/purchase/

POST Data

token=3ft49ki3awf7

san=1234567

partner_transact_id=878341937616

book_id=079778976077

email=test@redshelf.com

first_name=test_first

last_name=test_last

send_email=False

Example Success Response

<result>
   <partner_transact_id>1232234</partner_transact_id>
   <vendor_transact_id>14943</vendor_transact_id>
   <access_url>https://mybookstore.redshelf.com</access_url>
</result>

Error Messages

<message>The san parameter has not been provided or is malformed</message>
<message>The token parameter has not been provided or is malformed</message>
<message>The partner_transact_id parameter has not been provided or is malformed</message>
<message>The book_id parameter has not been provided or is malformed</message>
<message>SAN does not conform to SAN specifications</message>
<message>The store is not registered on RedShelf</message>
<message>Invalid Authorization Token</message>
<message>The submitted partner_transact_id has already been submitted for this store</message>
<message>The submitted book_id cannot be found in system</message>
<message>The submitted book_id is not available for fulfillment at this time</message>

Refund Endpoint¶

/api/refund/

Cancels a previously created Purchase transaction. This voids the access code that was created. If the user already redeemed the access code, then this will return an error response.

Request Parameters

san: The SAN Identifier for the store
token: Authorization token provided by RedShelf
partner_transact_id: The calling store’s transaction identifier. This transaction ID should be unique within a store, but does not need to be unique across all stores. This should be the transaction identifier for the void operation, not the original Purchase transaction.
purchase_transact_id: The partner transaction ID provided by the partner store associated with the original purchase transaction.

Response Parameters

partner_transact_id: Matches the transaction identifier that was originally provided by the client store
vendor_transact_id: The transaction identifier generated by eBook Vendor as proof of the void operation.
timestamp: The timestamp of when the access code was voided.

Example Request URL https://mybookstore.redshelf.com/api/refund/?token=test&san=123-4567&partner_transact_id=878341937618&purchase_transact_id=878341937616

Example Success Response

<row>
 <partner_transact_id>1232234</partner_transact_id>
 <vendor_transact_id>14944</vendor_transact_id>
 <timestamp>2008-05-20 01:29:22</timestamp>
</row>

Error Messages

<message>The san parameter has not been provided or is malformed</message>
<message>The token parameter has not been provided or is malformed</message>
<message>The partner_transact_id parameter has not been provided or is malformed</message>
<message>The purchase_transact_id parameter has not been provided or is malformed</message>
<message>SAN does not conform to SAN specifications</message>
<message>The store is not registered on RedShelf</message>
<message>Invalid Authorization Token</message>
<message>The submitted partner_transact_id has already been submitted for this store. The partner_transact_id value needs to be unique for each store</message>
<message>The submitted purchase_transact_id cannot be found for this store</message>
<message>The access code created by this purchase transaction has already been redeemed</message>
<message>The order created by this purchase transaction is over the time limit allowed for refunds({time_limit} days)</message>
<message>The order created by this purchase transaction is over the usage limit allowed for refunds({percent_usage_limit}% viewed)</message>
<message>The submitted purchase_transact_id has already been voided</message>

RedShelf Code Redemption API¶

/api/code_redemption/

Redeems a previously purchased RedShelf code (not publisher access code) for a product on the RedShelf website. The user being specified for redemption is assumed to have already been created and will yield an error if not already created on the RedShelf website whether that is through an API or typical account creation. Note: This API uses typical header signature authentication which is detailed in the API Authentication section.

Request Parameters

email: The email of the RedShelf account for which you want to redeem the code
code: The RedShelf code you want to redeem for the specified email address

Response Parameters

email: The same email specified in the request
hash: The hash id of the book or publisher product
purchased_sku: The SKU of the book or publisher product at the time of purchasing the RedShelf code
current_sku: The current, active SKU of the book or publisher product at the time of redemption of the RedShelf code
isbn: The ISBN of the book or publisher product that was redeemed
price: The price paid for the book or publisher product (coincides with purchased_sku)
expiration_date: Date of expiration for the product (for lifetime purchases ‘LIFETIME’ is returned in the response)

Example Request

https://mybookstore.redshelf.com/api/code_redemption/

POST Data

email=my.email@example.com

code=REDSHELFCODE

Example Success Response

<result>
  <email>my.email@example.com</email>
  <hash>1234asdf5678</hash>
  <purchased_sku>1234567</purchased_sku>
  <current_sku>1234800</current_sku>
  <isbn>9780123456789</isbn>
  <price>19.99</price>
  <expiration_date>2020-8-30 00:00:00</expiration_date>
</result>

Error Messages

<message>No Redshelf account exists for the provided email address</message>
<message>No Redshelf code exists for the code provided to this API</message>
<message>Code has already been redeemed or has been marked inactive</message>