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

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