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. :: The following errors were detected: {{Detailed Error Message}} The Detailed Error Message possibilities are described with the API endpoints. Purchase Endpoint ----------------- .. function:: /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 :doc:`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** :: 3151A4feAA 1232234 14943 https://mybookstore.redshelf.com **Error Messages** :: The san parameter has not been provided or is malformed The token parameter has not been provided or is malformed The partner_transact_id parameter has not been provided or is malformed The book_id parameter has not been provided or is malformed SAN does not conform to SAN specifications The store is not registered on RedShelf Invalid Authorization Token The submitted partner_transact_id has already been submitted for this store The submitted book_id cannot be found in system The submitted book_id is not available for fulfillment at this time The submitted email is incorrectly formatted **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** :: 1232234 14943 https://mybookstore.redshelf.com **Error Messages** :: The san parameter has not been provided or is malformed The token parameter has not been provided or is malformed The partner_transact_id parameter has not been provided or is malformed The book_id parameter has not been provided or is malformed SAN does not conform to SAN specifications The store is not registered on RedShelf Invalid Authorization Token The submitted partner_transact_id has already been submitted for this store The submitted book_id cannot be found in system The submitted book_id is not available for fulfillment at this time Refund Endpoint --------------- .. function:: /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** :: 1232234 14944 2008-05-20 01:29:22 **Error Messages** :: The san parameter has not been provided or is malformed The token parameter has not been provided or is malformed The partner_transact_id parameter has not been provided or is malformed The purchase_transact_id parameter has not been provided or is malformed SAN does not conform to SAN specifications The store is not registered on RedShelf Invalid Authorization Token The submitted partner_transact_id has already been submitted for this store. The partner_transact_id value needs to be unique for each store The submitted purchase_transact_id cannot be found for this store The access code created by this purchase transaction has already been redeemed The order created by this purchase transaction is over the time limit allowed for refunds({time_limit} days) The order created by this purchase transaction is over the usage limit allowed for refunds({percent_usage_limit}% viewed) The submitted purchase_transact_id has already been voided RedShelf Code Redemption API ---------------------------- .. function:: /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** :: my.email@example.com 1234asdf5678 1234567 1234800 9780123456789 19.99 2020-8-30 00:00:00 **Error Messages** :: No Redshelf account exists for the provided email address No Redshelf code exists for the code provided to this API Code has already been redeemed or has been marked inactive