Documentation about e-lending in libraries : Technical support

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.

The first two actions are usually done by the bookseller system, but the third action is done by the library system.

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.

Distinct library products will be added to the Onix 3.0 synchronization feed with the products offered to the general public: Sometimes it's an ISBN or EAN, but it can also be a custom key generated automatically. Please see the Guide to interpreting library licenses and the Onix 3.0 guide describing the particularities of products offered to libraries to find out how to interpret these products and their technical particularities. Library products can be identified by the following tags:

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"}

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

Name	Mandatory	Description
borrower_id	Yes	Identifies the final user (making the loan). Registers a unique alphanumeric identifier of less than 255 characters.
transaction_id	Yes	Loan reference number. Registers a unique alphanumeric identifier of less than 255 characters.
expire_at	Yes	Loan end date, in ISO-8601 format. The loan end date must be less than 59 days after the beginning of the loan period.
duration	No	Number of days the resource will be accessible, starting from download (if a chronodegradable download). If expire_at and duration are left out, the number by default will be the maximum duration accepted by the publisher.
medium	No	Indicates which type of access is being requested. Possible values: - download: Access by downloading - streaming: Access by consulting online Default: download
localisation	No	If access is by online consulting (medium=streaming), this setting becomes mandatory and indicates where access is from. Possible values: - on-site: Access is coming from within the walls of the library - off-site: Access is coming from outside the walls of the library
ip_address	No	This setting is required for medium=streaming and localization=on-site.
If you’d like to be informed whenever a user returns the book before the expiration of the loan, in order to make the title available again, add the setting notify_url:
notify_url	No	Setting that the entity doing the loan must provide. The URL must be correctly encoded. Ex: "http://www.pret.com/api/notify/loan/transaction_id/12345/".
bill_drm_to	No	Setting that the entity doing the loan must provide. The value of this setting must be the alphanumerical identifier of the lending system received from the platform. Lets the platform generate a personalized DRM billing report for every lending source.

Responses

Code	Content	Description
201	URL	URL of the chronodegradable file being downloaded. Forward users to this URL.
400	A table with error codes	Errors codes are described below.
	invalid_expiration_date	The expiration date is not valid.
	missing_borrower_id	The borrower_id setting has not been specified.
	missing_transaction_id	The transaction_id setting has not been specified.
	no_loan_available	The link is not valid or the book has already been lent out.
	maximum_loans_q ty_reached	The publication cannot be borrowed because the limit number of loans has been reached.
	medium_parameter_required	The medium setting has not been specified.
	medium_parameter_invalid	The medium parameter is not valid.
	localisation_parameter_required	The localization setting has not been specified.
	localisation_parameter_invalid	The localization setting is not valid.
	ip_address_parameter_required	The ip_address setting has not been specified.
	ip_address_parameter_invalid	The ip_address setting is not valid.
	loan_term_limit_reached	This resource cannot be lent out because its term limit has expired.
	loan_duration_over_maximum	The duration of the loan is longer than the authorized maximum.
	maximum_simultaneous_downloads_reached	The maximum number of simultaneous loans has been reached.
	maximum_simultaneous_onsite_streamings_reached	The maximum number of online consultations has been reached.
	maximum_simultaneous_offsite_streamings_reached	The maximum number of off-site consultations has been reached.

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]"}}

notification_type	"return"
return_time	Date (format ISO 8601 Basic): 2012-07-03T11:23:49Z.
loan_id	Id of the loan from the platform. Format: ENQC1234
borrower_id	The borrower_id (member number) of the loan
transaction_id	The transaction_id (transaction number) of the loan
time_in_seconds	Time (in seconds) between the early return and the expiration date of the loan
expiration_date	Date (Basic ISO 8601 format): 2012-07-14T00:00:00Z

How can we help you today?

Documentation about e-lending in libraries