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

1.1 Synchronisation complète

1.2 Synchronisation différentielle

1.3 Synchronisation d'une publication

2. Vente et téléchargement d'une publication

2.1 Simulation de vente

2.2 Vente d'une publication

2.3 Téléchargement d'une publication

2.4 Annulation d'une vente

2.5 Précommande

2.6 Obtenir l'état d'un téléchargement

2.7 Obtenir la table des matières d'une publication

3. Organisations

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 :

1. L’API de synchronisation complète du catalogue, qui retourne les métadonnées complètes de toutes les publications.

2. 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.

3. 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

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:

1. Simuler la vente d'une publication : afin d'en vérifier la validité

2. Déclarer la vente d'une publication

3. 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

1. 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.

2. 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 :

1. L'utilisateur clique sur le lien qui lui a été fourni pour télécharger son livre;

2. 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;

3. 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;

4. 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 :

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) :

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 Obenir 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éclaraton

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:

Notes

La balise <fulfillment> vous indique l'état du téléchargement du fichier par le client:

1. 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
2. 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 :

Format JSON :

 

---

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