1. Introduction
This document is for booksellers who sell books to be lent out by libraries. It contains information about three topics:
- getting a catalog of publications available for loan;
- selling a publication for the purpose of lending;
- lending out a publication (action done in the library by its management system).
Prerequisite: this document is complementary to the document entitled API Guide, which must be fully mastered before using the digital lending services. Make sure to especially to read sections 1, 2.1, 2.2 and 3.
2. Getting a catalog of publications available for loan
The web service providing a catalog of publications available for loan works identically to the service providing the products available to the general public, which is described in Section 1 of the API Guide. However, the content returned by the platform must be processed distinctly because the offer to libraries has certain special features.
Type of feed |
How to know if a book is available for loan? |
Onix |
If the tag <SalesRestrictionType> is present and contains the value 09, the book is not available for loan. If the tag <SalesRestrictionType> is absent or does not contain the value 09, the product is available for loan. |
3. Selling a publication for the purpose of lending
Declaring the sale of a publication for purposes of lending is very much like the procedure of selling products to the general public, which is described in Section 2.2 of the API Guide. Therefore, refer to this document, but make sure to take into account the settings that follow, which may differ depending on how you use Variant 1 or 2 in the previous steps.Name |
Mandatory |
Description |
isbn |
Yes |
Identifier of the library product (ISBN or custom key) |
protection |
No – do not use |
Do not use – this will be the chronodegradable Adobe DRM in any case. |
loan |
No |
This setting is not required. |
output |
Yes |
Indicates the format the information about the lending link will be returned in. Possible values: xml, json. |
The content and the use of the response are still different than a sale of a product for the general public. The service sends back a link that states a loan for the resource. This link must be retained in your system (bookseller), and must be sent to the lending system that is used by the library that is purchasing the book (see the specifications for the lending system for this step). This is a permanent link.
The response takes the following form:Format | Description |
---|---|
XML | <?xml version="1.0" encoding="UTF-8"?> <sale> <loan-url>[loan_url]</loan-url> <status>created</status> </sale> </xml> |
json | {"loan_url":"[loan_url]","status":"created"} |
The link [loan_url] takes the following form:
https://domaine/api/loans/UGV60GNogpXRcS3UtHAkZcHPOlDTIlnaJ3Z1uFYuf0DQfmgAEnzSUdY3rQY1vRxI/activate
All return HTTP codes apply, in addition to:Code | Content | Description |
---|---|---|
400 | cannot_loan | The publication cannot be lent out. |
4. Lending out a publication – refer to the lending system
To lend out a publication, the library’s lending system must use the URL of the loan obtained when the publication is purchased (this URL being sent by the bookseller that sold the resource to the library). Using this URL, with certain specific settings, will forward to another URL that will lead to the resource.Address |
The [loan_url] recieved when purchasing the publication. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Method |
POST |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settings |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses |
|
Note: If you have generate a download link again for an existing loan (for instance, for a user who has lost the file), simply use this service again, using the same values for the borrower_id and transaction_id setting and leave out the expire_at setting.
The notification URL ([notify_url]) can be specific to each loan, like this: "http://www.pret.com/api/notify/loan/transaction_id/12345/" or generic (the same link for every loan, for instance “http://www.pret.com/api/notify") because the platform already sends the lending information in the request made to the notification URL (see next step).5. Returning a loan before its expiration date – for platforms making the loan
The system of the entity making the loan must be adapted so that when this offer is made, it can find the loan in its system, consider it as returned and that the copy becomes available for a new loan.
When the platform is informed about an early return of a loan, it calls upon the notification URL that the entity making the loan will have provided, as follows:Address |
The notify_url provided by the entity making the loan. |
||||||||||||||
Method |
POST |
||||||||||||||
Certification |
None |
||||||||||||||
Content |
A JSON document that provides the information about the loan from the platform in the form of: {"type": "[notification_type]", "time": "[return_time]", "data": {"loan": "[loan_id]", "borrower": "[borrower_id]", "transaction": "[transaction_id]", "time_before_expire": "[time_in_seconds]", , "expire_at": "[expiration_date]"}}
|