1. Introduction

Ce document s'adresse aux libraires qui vendent des livres destinés à être prêtés en bibliothèques. Il contient des informations sur trois actions utiles dans ce contexte:

  • obtenir un catalogue de publications disponibles pour le prêt;
  • vendre une publication pour des fins de prêts;
  • prêter une publication (action réalisée dans la bibliothèque, par le système de gestion de cette dernière).

Préalable: ce document est complémentaire au document « Guide : Les services web », qui doit être maîtrisé avant d'utiliser les services relatifs au prêt numérique. Assurez-vous en particulier d'en lire les sections 1, 2.1, 2.2 et 3.

Les deux premières actions sont typiquement réalisées par le système libraire, alors que la troisième l'est par le système de bibliothèque.

2. Obtenir le catalogue des publications disponibles pour le prêt

Le service web permettant d'obtenir un catalogue de publications disponibles pour le prêt fonctionne de façon identique à celui permettant d'obtenir les produits offerts au grand public, qui est décrit à la section 1 du « Guide : Les services web ». Cependant, le contenu retourné par la plateforme doit être traité de façon distincte, car l'offre aux bibliothèques possède quelques particularités.

Dans les plateformes Cantook, les produits bibliothèque sont des produits (fiches ONIX) distinctes, puisque chaque produit bibliothèque décrit sa licence (ses restrictions d'utilisation). Cela fait en sorte que le produit bibliothèque a un identifiant qui lui est propre. Il s'agit parfois d'un ISBN/EAN, ou d'une clé interne générée automatiquement.

Veuillez consulter le guide d'interprétation des licences bibliothèques et le guide Onix 3.0 décrivant les particularités des produits offerts aux bibliothèques pour savoir de quelle manière interpréter ces produits et leurs particularités techniques.


Pour identifier les livres qui sont disponibles pour le prêt, utilisez les balises suivantes :

Type de flux Comment déterminer si un livre est disponible pour le prêt?
ONIX 3.0

Si la balise <SalesRestrictionType> est présente et contient la valeur 09, le livre n'est pas disponible pour le prêt.

Si la balise <SalesRestrictionType> est absente ou ne contient pas la valeur 09, le produit est disponible pour le prêt.

3. Vendre une publication pour des fins de prêts

La déclaration de la vente d'une publication pour des fins de prêts est très semblable à la procédure de vente de produits pour le grand public, décrite à la section 2.2 du « Guide : Les services web ». Vous pouvez donc vous référer à cette documentation, en prenant soin de tenir compte des quelques paramètres suivants, dont l'utilisation diffère.

Nom Obligatoire Description
isbn Oui

Identifiant du produit bibliothèque reçu dans le flux ONIX (et non l'ISBN/EAN du produit grand public).

protection Non Contrairement à l'API de vente pour produits grand public, le paramètre protection n'est pas requis pour vendre un produit bibliothèque. La DRM Adobe chronodégradable sera automatiquement appliquée sur chaque prêt.
loan

Non

Ce paramètre est désuet; il n'est plus requis pour la vente de produits bibliothèques.

output Oui

Indique sous quel format les informations sur le lien de prêt seront retournées. Valeurs possibles: xml, json.

Dans le cas d'une vente d'un produit bibliothèque, un lien, qui permet de déclarer un prêt sur cet exemplaire, vous est retourné, soit en XML ou en JSON (voir le paramètre "output" ci-haut). Ce lien doit être conservé dans votre système (libraire), et doit être transmis au système de prêt qu'utilise la bibliothèque qui a fait l'achat du livre (référez-vous aux spécifications du système de prêts pour cette étape). Il s'agit d'un lien pérenne.

La réponse prend la forme suivante:

Format Réponse
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"}

Le lien [loan_url] prend la forme suivante:

https://domaine/api/loans/UGV60GNogpXRcS3UtHAkZcHPOlDTIlnaJ3Z1uFYuf0DQfmgAEnzSUdY3rQY1vRxI/activate

Les mêmes codes HTTP de retour que pour l'API de vente pour les produits grand public s'appliquent, en plus du suivant:

Code Contenu Description
400 cannot_loan La publication ne peut pas être louée.

4. Prêter une publication - s'adresse au système de prêt

Pour prêter une publication, le système de prêt de la bibliothèque doit utiliser l'URL de prêt obtenu lors de l'achat de la publication (cet URL lui a été transmis par le libraire qui a vendu la ressource à la bibliothèque). Un appel à cet URL, avec certains paramètres spécifiques, retournera un second URL qui permet d'accéder à la ressource.

Adresse Le [loan_url] obtenu lors de l'achat de la publication.
Méthode POST
Paramètres
Nom Obligatoire Description
borrower_id Oui Permet d'identifier l'utilisateur final (qui bénéficie du prêt). Passer un identifiant alphanumérique unique de moins de 255 caractères.
transaction_id Oui Numéro de référence du prêt. Passer un identifiant alphanumérique unique de moins de 255 caractères.
expire_at

Oui


Date de fin du prêt, au format ISO-8601 basic (AAAAMMJJ ou AAAAMMJJTHHMMSS). La date de fin du prêt doit être située à moins de 59 jours après le début du prêt.

duration Non

Nombre de jours que la ressource sera accessible, à partir du moment du téléchargement (dans le cas d'un téléchargement chronodégradable).

Si expire_at et duration sont omis, le nombre par défaut sera la durée maximale acceptée par l'éditeur.

medium Non

Indique quel type d'accès est demandé.

Valeurs possibles :

- download : Accès par téléchargement

- streaming : Accès par consultation en ligne

Défaut : download

localisation Non

Dans le cas d'un accès par consultation (medium=streaming), ce paramètre devient obligatoire et indique à partir d'où se fait l'accès. Valeurs possibles :

- on-site : L'accès se fait à partir de l'intérieur des murs de la bibliothèque

- off-site : L'accès se fait hors des murs de la bibliothèque

ip_address Non Ce paramètre est requis lorsque medium=streaming et que localization=on-site.

Si vous souhaitez être informé lorsqu'un utilisateur retourne le livre avant l'expiration du prêt, de façon à rendre le titre de nouveau disponible, ajoutez le paramètre notify_url :

notify_url Non Paramètre que doit fournir l'entité qui opère le prêt. L'URL doit être correctement encodé. Ex.: "http://www.pret.com/api/notify/loan/transaction_id/12345/".
bill_drm_to Non Paramètre que doit fournir l'entité qui opère le prêt. La valeur de ce paramètre doit être l'identifiant alphanumérique du système de prêt obtenu auprès de la plateforme. Permet à la plateforme de générer un rapport de facturation des frais de DRM personnalisé pour chaque source de prêts.
Réponses
Code Contenu Description
201 URL URL du fichier chronodégradable à télécharger. Redirigez l'utilisateur vers cette URL.
400 Un tableau avec les codes d'erreur Les codes d'erreurs sont décrits ci-dessous.
  invalid_expiration_date La date d'expiration n'est pas valide.
  missing_borrower_id Le paramètre borrower_id n'a pas été spécifié.
  missing_transaction_id Le paramètre transaction_id n'a pas été spécifié.
  no_loan_available Le lien n'est pas valide ou le livre est déjà prêté.
  maximum_loans_q
ty_reached
La publication ne peut pas être empruntée car la limite du nombre de prêts est atteinte.
  medium_parameter_required Le paramètre medium n'a pas été spécifié.
  medium_parameter_invalid Le paramètre medium n'est pas valide.
  localisation_parameter_required Le paramètre localisation n'a pas été spécifié.
  localisation_parameter_invalid Le paramètre localisation n'est pas valide.
  ip_address_parameter_required Le paramètre ip_address n'a pas été spécifié.
  ip_address_parameter_invalid Le paramètre ip_address n'est pas valide.
  loan_term_limit_reached Cette ressource ne peut plus être prêtée car sa durée de vie a expiré.
  loan_duration_over_maximum La durée du prêt est plus grande que le maximum autorisé.
  maximum_simultaneous_downloads_reached Le nombre maximal de prêts simultanés a été atteint.
  maximum_simultaneous_onsite_streamings_reached Le nombre maximal de consultations sur site a été atteint.
  maximum_simultaneous_offsite_streamings_reached Le nombre maximal de consultations hors site a été atteint.

Note: si vous devez générer de nouveau un lien de téléchargement pour un prêt existant (par exemple, pour un utilisateur qui aurait perdu son fichier), il suffit d'utiliser ce service à nouveau, en utilisant les mêmes valeurs pour les paramètres borrower_id et transaction_id et en omettant le paramètres expire_at.

L'URL de notification ([notify_url]) peut être spéficique à chaque prêt, comme ceci : "http://www.pret.com/api/notify/loan/transaction_id/12345/" ou générique (le même lien pour chaque prêt, par exemple http://www.pret.com/api/notify") puisque la plateforme envoie déjà les informations de prêt dans la requête qui est faite à l'URL de notification (voir la prochaine étape).

5. Retour d'un prêt avant sa date d'expiration - pour les plateformes qui opèrent les prêts

Le système de l'entité qui opère le prêt devra être adapté afin que lors de cet appel, il retrouve le prêt dans son système, le considère retourné, et que la copie devienne disponible pour un nouveau prêt.

Lorsque la plateforme se fait aviser du retour anticipé d'un prêt, elle fera un appel à l'URL de notification qu'aura fourni l'entité qui opère le prêt, de la façon suivante :

Adresse Le notify_url fourni par l'entité qui opère le prêt.
Méthode POST
Authentification Aucune
Contenu

Un document JSON qui fournit les informations du prêt à partir de la plateforme sous la forme :

{"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 du prêt de la plateforme. Format : ENQC1234
borrower_id Le borrower_id (numéro de membre) du prêt
transaction_id Le transaction_id (numéro de transaction) du prêt
time_in_seconds Temps (en secondes) entre le retour anticipé et la date d'expiration du prêt
expiration_date Date (format ISO 8601 Basic) : 2012-07-14T00:00:00Z