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 |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Réponses |
|
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]"}}
|