Introduction
Ce document s'adresse aux libraires, éditeurs, ou tout autre marchand qui souhaite offrir la vente et le téléchargement de livres numériques sur son site Web.
Liste des API
1. Synchronisation du catalogue
2. Vente et téléchargement d'une publication
2.3 Téléchargement d'une publication
1. Synchronisation du catalogue
Il est possible de mettre à jour le catalogue de livres numériques à partir des métadonnées obtenues par l’intermédiaire des API suivants :
L’API de synchronisation complète du catalogue, qui retourne les métadonnées complètes de toutes les publications.
L’API de synchronisation différentielle du catalogue, qui retourne les métadonnées complètes des publications modifiées depuis la dernière synchronisation ou depuis une date précise.
L’API de synchronisation d’une publication, qui retourne les métadonnées complètes de la publication demandée.
Les métadonnées retournées sont divisées en fichiers (ONIX ou XML) qui contiennent chacun les métadonnées de 50 publications au maximum.
1.1 Synchronisation complète
Cet API permet de recevoir les métadonnées complètes de toutes les publications du catalogue.
Il retourne le premier fichier de métadonnées. Pour accéder aux fichiers suivants, il faut suivre l’URL indiqué dans le champ Link de l’en-tête de réponse HTTP jusqu’à obtenir un code HTTP “404 Not Found”.
Déclaration
Adresse : /api/organisations/[organisation_id]/publications/full[.format]
Formats : onix, xml
Méthode : GET
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id (Obligatoire)
Numéro d'organisation fourni à l'inscription.
format (Optionnel)
Format des fichiers, onix ou xml. La valeur par défaut est onix.
Réponses
200 : OK
Le fichier a été créé avec succès. Le champ Link de l’en-tête de réponse HTTP contient un URL (Link: ; rel=next) permettant d’accéder au fichier suivant. On arrive à la fin de la liste des fichiers lorsqu’on obtient un code HTTP “404 Not Found”.
401 : access_denied
Accès refusé à la ressource.
404 : not_found
L'organisation n'a pu être trouvée.
415 : invalid_format
Le format demandé n'est pas supporté.
1.2 Synchronisation différentielle
Avertissement : Il s’agit du nouvel API de synchronisation différentielle (qui utilise la méthode GET). L’ancien API de synchronisation (avec la méthode POST) est toujours fonctionnel et sa documentation se trouve ici : Ancien API de synchronisation différentielle
S’il est toujours possible d’utiliser l’ancien API, nous encourageons les usagers à privilégier le nouvel API, présenté ci-dessous.
Cet API permet de recevoir les métadonnées complètes des publications modifiées depuis la dernière synchronisation (complète ou différentielle) ou une date spécifique. Il sert à effectuer des mises à jour régulières.
Si le nombre de modifications apportées aux publications est trop grand (code HTTP 400), il faut utiliser l’API de synchronisation complète du catalogue.
Il retourne le premier fichier de métadonnées. Pour accéder aux fichiers suivants, il faut suivre l’URL indiqué dans le champ Link de l’en-tête de réponse HTTP jusqu’à obtenir un code HTTP “404 Not Found”.
Déclaration
Adresse : /api/organisations/[organisation_id]/publications/delta[.format]
Formats : onix, xml
Méthode : GET
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id (Obligatoire)
Numéro d'organisation fourni à l'inscription.
format (Optionnel)
Format des fichiers, onix ou xml. La valeur par défaut est onix.
from (Optionnel)
Date et heure, au format ISO 8601 Basic. Si paramètre absent : retourne les métadonnées des publications modifiées depuis la dernière synchronisation complète ou différentielle. Si paramètre présent : retourne les métadonnées des publications modifiées depuis cette date et heure.
Attention : la date passée doit être égale ou antérieure à la date de début de la précédente synchronisation (réception de l'appel initial pour la première page de résultats).
Réponses
200 : OK
Le fichier a été créé avec succès. Le champ Link de l’en-tête de réponse HTTP contient un URL (Link: ; rel=next) permettant d’accéder au fichier suivant. On arrive à la fin de la liste des fichiers lorsqu’on obtient un code HTTP “404 Not Found”.
400 : too_many_results
Le nombre de modifications est trop important. Utiliser plutôt l’API de synchronisation complète du catalogue.
401 : access_denied
Accès refusé à la ressource.
404 : not_found
L'organisation n'a pu être trouvée ou il n’y a pas eu de modifications depuis la dernière synchronisation.
415 : invalid_format
Le format demandé n'est pas supporté.
1.3 Synchronisation d'une publication
Cet API permet de recevoir les métadonnées complètes d'une publication en particulier.
Déclaration
Adresse : /api/organisations/[organisation_id]/publications/[isbn].[format]
Formats : onix, xml
Méthode : GET
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id (Obligatoire)
Numéro d'organisation fourni lors de l'inscription.
isbn (Obligatoire)
ISBN/EAN de la publication.
format (Obligatoire)
Format des fichiers, onix ou xml.
Réponses
200 : OK
Les métadonnées de la publication en format ONIX ou XML.
401 : access_denied
Accès refusé à la ressource.
404 : not_found
La publication ou l'organisation n'a pu être trouvée.
2. Vente et téléchargement de publications
Les services Web de vente et de téléchargement de publications de Cantook répondent à trois besoins:
Simuler la vente d'une publication : afin d'en vérifier la validité
Déclarer la vente d'une publication
Obtenir le lien de téléchargement d'une publication
2.1 Simulation de vente
Étant donné que le catalogue du libraire n'est pas synchronisé en temps réel avec celui de la plateforme Cantook, il est possible que certaines différences existent entre les deux catalogues au moment précis de la vente d'un livre. Ce service Web permet au libraire de vérifier que tous les paramètres requis pour déclarer une vente sont toujours valides, ce qui lui confirmera que la vente est toujours possible.
Lors de cette simulation, la vente n'est pas enregistrée sur la Plateforme. La vente doit être déclarée via le service Vente d'une publication.
Déclaration
Adresse : /api/organisations/[organisation_id]/publications/[isbn]/sales/new
Méthode : GET
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id : (Obligatoire)
Numéro d'organisation. Fourni lors de l'inscription.
isbn (Obligatoire)
ISBN de la publication.
format (Obligatoire)
Format de la publication vendue (pdf/epub/mobi/audio/proof).
cost (Obligatoire)
Prix de vente en centime (Ex. 19,99 $ => 1999).
protection : (Obligatoire)
Type de protection de la publication vendue (open/watermark/acs4/acs4_timelimited/drm/drm_timelimited).
drm_type : (Optionnel)
Type de DRM de la publication vendue (acs/lcp/urms).
country : (Obligatoire)
Pays qui sera considéré pour valider le prix de la publication. Format ISO 3166-1 Alpha-3 (can, fra, ita) ou Alpha-2 (CA, FR, IT).
cost_without_taxes : (Optionnel / Obligatoire sur Eden Livres)
Prix hors taxes, dans le pays du client, en centimes (ex. : 19,99$ => 1999)
price_type : (Optionnel)
Le type de prix ONIX qui sera utilisé pour la validation du prix de la publication. Valeurs acceptées de la liste 58 : 01, 02, 03, 04, 41 et 42.
currency : (Obligatoire)
La devise qui sera utilisée pour la validation du prix de la publication. Codes à 3 lettres ISO-4217.
Réponses
200 : valid
La simulation a été exécutée avec succès.
400 : cannot_sell
L'organisation ne peut pas vendre cette publication.
400 : missing_format
Le format est absent de la requête.
400 : invalid_format
Le format fourni n'est pas disponible pour cette publication.
400 : missing_cost
Le prix est absent de la requête.
400 : invalid_sale_parameters
Soit le cost, country, currency ou price_type est invalide.
400 : missing_protection
Le type de protection est absent de la requête.
400 : invalid_protection
Cette protection n'est pas disponible dans ce form
400 : invalid_country
Le code de pays n'est pas valide
400 : invalid_price_type
Le type de prix est invalide.
401 : access_denied
Accès refusé à la ressource.
404 : not_found
L'organisation ou l'ISBN n'ont pu être trouvés.
503 : service_unavailable
Le serveur a des difficultés à se connecter.
Notes
Dans le cas d'une erreur de type 400, le détail de l'erreur est fourni dans un vecteur.
2.2 Vente d'une publication
Ce service Web permet de déclarer une vente dans la plateforme Cantook. La vente ainsi enregistrée associe, pour une transaction à une date précise, le marchand, l'utilisateur et un fichier numérique d'un livre dans la plateforme. L’éditeur pourra consulter le détail de la vente dans les statistiques.
Seule la réponse 201 (created) confirme que la vente a bien été enregistrée, et qu'il est possible de passer à l'étape suivante du processus d'achat.
Note : Plusieurs des paramètres utilisés lors de la déclaration de la vente sont requis dans le service de téléchargement de la publication. Étant donné que les deux services peuvent être appelés à des moments distincts, les valeurs doivent demeurer accessibles afin de les utiliser ultérieurement.
Déclaration
Adresse : /api/organisations/[organisation_id]/publications/[isbn]/sales
Méthode : POST
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id : (Obligatoire)
Numéro d'organisation. Fourni lors de l'inscription.
isbn : (Obligatoire)
ISBN de la publication.
format : (Obligatoire)
Format de la publication vendue (pdf/epub/mobi/audio/proof).
cost : (Obligatoire)
Prix de vente en centime (Ex. 19,99 $ => 1999).
protection : (Obligatoire)
Type de protection de la publication vendue (open/watermark/acs4/acs4_timelimited/drm/drm_timelimited).
drm_type : (Optionnel)
Type de DRM de la publication vendue (acs/lcp/urms).
customer_id: (Obligatoire)
Numéro unique du client. Caractères alphanumériques seulement («-» et «_» aussi acceptés).
transaction_id : (Obligatoire)
Numéro unique de la transaction / du panier d'achat. Plusieurs ventes avec le même numéro de transaction sont possibles, tant qu'il s'agit du même panier d'achat. Caractères alphanumériques seulement («-» et «_» aussi acceptés).
credit_card_prefix : (Optionnel)
4 premiers numéros de la carte de crédit utilisée par le client. Ceci permet à l'éditeur de valider si le territoire de vente (déterminé par ces 4 premiers caractères) est respecté.
sale_state : (Optionnel)
Statut de la vente. Par défaut, une vente est toujours en statut "active". Valeur possible: active, test, customer_service
country : (Obligatoire)
Pays qui sera considéré pour valider le prix de la publication. Valeur par défaut: le pays de l'organisation. Format ISO 3166-1 Alpha-3 (can, fra, ita) ou Alpha-2 (CA, FR, IT).
cost_without_taxes : (Obligatoire)
Prix hors taxes, dans le pays du client, en centimes (ex. : 19,99$ => 1999)
price_type : (Optionnel)
Le type de prix ONIX qui sera utilisé pour la validation du prix de la publication. Valeurs acceptées de la liste 58 : 01, 02, 03, 04, 41 et 42.
currency : (Optionnel)
La devise qui sera utilisée pour la validation du prix de la publication. Codes à 3 lettres ISO-4217.
aggregator : (Optionnel)
Lorsqu'un revendeur parent vend une publication pour un de ses revendeurs enfants, ce champ représente l'id du parent, ou agrégateur.
uname : (Obligatoire seulement si la protection est watermark)
Prénom et nom de l'utilisateur. La valeur de ce paramètre apparaîtra dans le texte du filigrane qui sera apposé sur le fichier. Si ce paramètre est fourni lors de la vente, le délai de génération de la copie filigranée par la plateforme sera plus court au moment où le client voudra télécharger son fichier.
Réponses
201 : created
La vente a été ajoutée avec succès.
400 : cannot_sell
L'organisation ne peut pas vendre cette publication.
400 : duplicate
La vente existe déjà dans la plateforme.
400 : missing_format
Le format était absent de la requête.
400 : invalid_format
Le format fourni n'est pas disponible pour cette publication.
400 : invalid_sale_parameters
Soit le cost, country, currency ou price_type est invalide.
400 : missing_cost
Le prix était absent de la requête.
400 : missing_customer_id
Le numéro unique du client était absent de la requête.
400 : missing_transaction_id
Le numéro unique de la transaction était absent de la requête.
400 : missing_protection
Le type de protection était absent de la requête.
400 : invalid_protection
Cette protection n'est pas disponible dans ce format.
400 : invalid_sale_state
L'état de vente n'est pas valide
400 : invalid_country
Le code de pays est invalide.
400 : invalid_price_type
Le type de prix est invalide.
401 : access_denied
Accès refusé à la ressource.
404 : not_found
L'organisation ou l'ISBN n'ont pu être trouvés.
503 : service_unavailable
Le serveur a des difficultés à se connecter.
Notes
Les ventes déclarées via cet API sont facturables. Cependant, afin d'effectuer une vente de test (par exemple, lors du développement de la connexion à ce service Web), le paramètre sale_state=test peut être ajouté; la vente ne sera ainsi pas comptabilisée.
Dans le cas d'une erreur de type 400, le détail de l'erreur est fourni dans un vecteur.
2.3 Obtenir le lien de téléchargement d'une publication
Afin de protéger le fichier du client, le lien de téléchargement ne peut pas être généré d'avance et fourni tel quel au client. Les liens de téléchargement sont chrono-dégradables, et ne peuvent être obtenus que par le vendeur de la publication. Le vendeur offre donc son propre lien de téléchargement à son client, et lorsque le client utilise ce lien, le vendeur utilise le service Web ci-bas afin de rediriger son client vers le fichier.
Étapes lors de la demande de téléchargement :
L'utilisateur clique sur le lien qui lui a été fourni pour télécharger son livre;
La page du site Web reçoit la demande de téléchargement, retrace les informations afin de construire l'URL du service Web Obtention du lien de téléchargement d'une publication, et utilise ce service Web. Elle reçoit en retour une URL de téléchargement chronodégradable;
La page intermédiaire du site Web redirige automatiquement et instantanément l'utilisateur vers l'URL de téléchargement chronodégradable reçue;
Le téléchargement démarre.
Declaration
Adresse :
/api/organisations/[organisation_id]/customers/[customer_id]
/transactions/[transaction_id]/publications/[isbn]/download_links/[format]
Méthode : GET
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id : (Obligatoire)
Numéro d'organisation. Fourni lors de l'inscription.
customer_id : (Obligatoire)
Le numéro du client.
transaction_id : (Obligatoire)
Le numéro unique de la transaction / du panier d'achat.
isbn : (Obligatoire)
L'ISBN de la publication.
format : (Obligatoire)
Le format de la publication vendue (pdf/epub/mobi/audio/proof).
uname : (Obligatoire)
Prénom et nom de l'utilisateur. La valeur de ce paramètre apparaîtra dans le texte du filigrane qui sera apposé sur le fichier.
Réponses
200 : OK
URL chronodégradable du fichier à télécharger (expiration : 1 minute). Redirigez l'utilisateur vers cette
400 : missing_transaction_id
Le numéro de transaction était absent de la requête.
401 : access_denied
Accès refusé à la ressource.
404 : not_found
L'organisation n'a pu être trouvée.
2.4 Annulation de vente
Les libraires peuvent utiliser un service web pour annuler une vente. Pour que la vente puisse être annulée, le libraire doit identifier la vente en fournissant les mêmes valeurs dans les paramètres que la vente originale. Seule les ventes dont le fichier n'a pas été téléchargé (le fichier filigrané ou le fichier de licence .acsm n'a pas été téléchargé) peuvent être annulées.
Déclaration
Adresse : /api/organisations/[organisation_id]/publications/[publication_id]/sales/cancel
Méthode : POST
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id : (Obligatoire)
Id de l'organisation qui a fait la vente
publication_id : (Obligatoire)
Identifiant (ISBN, EAN ou clé interne) de la publication
customer_id : (Obligatoire)
Le customer_id de la vente à rembourser
transaction_id : (Obligatoire)
Le transaction_id de la vente à rembourser
amount : (Obligatoire)
Le montant du remboursement, qui doit correspondre au "cost" de la vente originale
reason : (Optionnel)
La raison du remboursement, optionnelle. Elle sera affichée à l'éditeur.
Réponses
200 : OK
Token. Le remboursement a été enregistré et un token est donné comme référence.
400 : refund_unauthorized
Le remboursement n'est pas autorisé car le contenu a été téléchargé par l'utilisateur.
400 : already_refunded
Cette vente a déjà été remboursée.
400 : cost_mismatch
Le montant ne correspond pas à celui de la vente originale.
401
Problème d'authentification utilisateur, ou l'utilisateur n'a pas le droit d'effectuer un remboursement.
404
La vente n'a pas été trouvée.
2.5 Pré-vente
Les libraires peuvent offrir la possibilité à leurs clients d'acheter à l'avance les publications qui sont offertes en pré-vente. Lorsqu'une pré-vente est enregistrée, le libraire doit la déclarer en utilisant l'API de pré-vente. Dès que la publication devient disponible à la vente, une vente correspondant à chaque pré-vente doit être déclarée via l'API de vente. L'identifiant de client (customer_id) doit correspondre à celui qui a été utilisé pour faire la pré-commande. Le téléchargement de la publication sera disponible dès que la vente aura été déclarée, via le service web Téléchargement d'une publication.
Publications disponibles en pré-vente
Les règles suivantes peuvent être appliquées afin de déterminer quels sont les publications qui sont disponibles en pré-vente :
État : <ProductAvailability>40</ProductAvailability> (non disponible à la vente)
Date à partir de laquelle il est possible de faire des pré-commandes :
<PublishingDate>
<PublishingDateRole>09</PublishingDateRole>
<DateFormat>14</DateFormat>
<Date>20131107T000000-0500</Date>
</PublishingDate>
La date de disponibilité prévue est indiquée dans le flux ONIX de la façon suivante (cette date doit donc être dans le futur) :
<SupplyDate>
<SupplyDateRole>02</SupplyDateRole>
<DateFormat>14</DateFormat>
<Date>2012-10-25T00:00:00-04:00</Date>
</SupplyDate>
Déclaration
Adresse : /api/organisations/[organisation_id]/publications/[publication_id]/preorders
Méthode : POST
Sécurité : HTTP/BASIC (Nom d'utilisateur et mot de passe)
Paramètres
organisation_id : (Obligatoire)
Id de l'organisation qui a fait la vente
publication_id : (Obligatoire)
Identifiant (ISBN, EAN ou clé interne) de la publication
for : (Obligatoire)
epub ou pdf
customer_id : (Obligatoire)
Le customer_id de la précommande
Réponses
200 : created
La pré-vente a été enregistrée.
401
Problème d'authentification utilisateur.
404
La publication n'a pas été trouvée.
2.6 Obtenir l'état d'un téléchargement
Ce service permet d'obtenir une confirmation de la bonne réception d'un téléchargement par le client.
Déclaration
Adresse : /api/organisations/{organisation_id}/customers/{customer_id}/transactions/{transaction_id}/publications/{isbn}/formats/{format}/status
Paramètres
L'ensemble des paramètres de l'appel sont les mêmes que ceux des services Web de ventes.
Réponse
La réponse prendra la forme suivante:<transaction></status><id>transaction_id</id></transaction>
<customer>
<id>customer_id</id></customer>
<publications><publication></publication><format><fulfillment>complete</fulfillment><nature>epub</nature></format>
<keytype>isbn</keytype>
<value>9782896157181</value>
<protectiontype>watermark</protectiontype>
<refundable>false</refundable>
</publications>
Notes
La balise <fulfillment> vous indique l'état du téléchargement du fichier par le client:- dans le cas d'une protection par filigrane (watermark): complete et incomplete font référence au démarrage du téléchargement du fichier
- dans le cas d'une protection par DRM (ACS4): complete et incomplete font référence à l'activation de la licence du livre dans Adobe Digital Edition ou dans un autre logiciel compatible.
Les autres balises correspondent aux informations fournies lors de l'appel au service.
2.7 Obtenir la table des matières d'une publication
Ce service Web retourne la table des matières d’une publication, sous la forme d’un fichier XML ou JSON.
Déclaration
Adresse : /api/publications/[isbn]/toc.[xml|js]
Formats : XML ou JSON
Méthode : GET
Security : HTTP/BASIC (Utilisez votre identifiant et mot de passe)
Paramètres
isbn : (Obligatoire)
L'isbn de la publication
Réponse
Format XML :
<chapters>
<chapter>
<page>1</page>
<title>Couverture</title>
</chapter>
<chapter>
<page>7</page>
<title>Table des matières</title>
</chapter>
<chapter>
<page>13</page>
<title>Chapitre 1</title>
</chapter>
<chapter>
<page>24</page>
<title>Chapitre 2</title>
</chapter>
...
</chapters>
Format JSON :
[{"page":1,"title":"Couverture"},{"page":7,"title":"Table des matières"},{"page":13,"title":"Chapitre 1"},{"page":24, "title":"Chapter 2"}...
3. Organisations
L'API /api/organisations/{id}/publishers.json fournit la liste des organisations avec qui un libraire a une entente, organisées de la façon suivante :
1. liste des éditeurs ayant une entente directe (sous publishers)
2. liste des diffusions ayant une entente (sous distributors), incluant, pour chacun, la liste des éditeurs pour qui cette entente s'applique (les éditeurs ayant délégué la gestion de leur Marché à leur diffuseur)
Chaque organisation est décrite de la façon suivante :
- id (ID numérique d'Eden)
- name (nom de l'organisation)
- identifier (Identifiant ou GLN)
- website (site web de l'éditeur)
- logo (lien vers le logo hébergé sur l'entrepôt)
Déclaration
Adresse : /api/organisations/{id}/publishers.json]
Formats : JSON
Méthode : GET
Securité : HTTP/BASIC (Utilisez votre identifiant et mot de passe)
Paramètres
id : (Obligatoire)
L'identifiant de l'organisation
Format JSON :
{"publishers":[{"id":"ENQC7","name":"Première organisation Inc.","identifier":"7","website":"http:www.example.com","logo":"http://assets.example.com/logo.jpg"}],"distributors":[{"id":"ENQC1","name":"Un grand distributeur","identifier":"1","website":"http://www.example.com","logo":"http://assets.example.com/logo2.jpg","publishers":[{"id":"ENQC2","name":"Un éditeur sous un distributeur","identifier":"2","website":"http://www.example.com","logo":"http://assets.example.com/logo3.jpg"}]}]}