Vente d'une publication
Cette API permet de déclarer la vente d'une publication. La vente est requise afin de permettre l'accès à la publication (téléchargement, lecteur en ligne).
Seule la réponse 201 (created) confirme que la vente a bien été créée, et qu'il est possible de passer à l'étape suivante du processus d'achat.
Déclaration
Adresse : /api/organisations/[:organisation_id]/publications/[:publication]/sales
Méthode : POST
Sécurité : Bearer Token (jeton d'authentification) ou HTTP Basic (nom d'utilisateur et mot de passe)
Paramètres
| Paramètre | Obligatoire | Description |
|---|---|---|
| :organisation_id | Obligatoire | Numéro d'organisation. Fourni lors de l'inscription. |
| :publication | Obligatoire | Identifiant (ISBN, EAN) de la publication. |
| 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). |
| format | Obligatoire | Format de la publication vendue (pdf/epub/mobi/audio/proof). |
| protection | Obligatoire | Type de protection de la publication vendue (open/watermark/acs4/acs4_timelimited/drm/drm_timelimited). Optionnel si la vente est pour le prêt numérique en bibliothèque. |
| 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 | Obligatoire | Prix de vente en centime (Ex. 19,99 $ => 1999). |
| currency | Obligatoire | La devise qui sera utilisée pour la validation du prix de la publication. Codes à 3 lettres ISO-4217. |
| cost_without_taxes | Optionnel | 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. |
| drm_type | Optionnel | Type de verrou de la publication vendue: acs (verrou Adobe - fichier PDF ou EPUB) ou lcp (verrou LCP - fichier EPUB, PDF ou audio). Obligatoire si protection=drm. |
| sale_state | Optionnel | Statut de la vente. Valeur possible: active, test, customer_service. Par défaut : active. |
| uname | Optionnel | Requis pour l'application du filigrane (si protection=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. |
| output | Optionnel | Format de la réponse à l'appel API. Valeur possible : json. Par défaut: texte. Utiliser output=json pour obtenir les éléments status_document_url et access_token qui permettent d'accéder à la publication (téléchargement, lecteur en ligne) en passant par un Licence Status Document. |
| quantity | Optionnel | Pour les ventes pour prêt numérique en bibliothèque. Nombre d'unités (exemplaires) commandés. Nombre entier positif. Par défaut: 1. |
| passphrase | Optionnel | Pour la DRM LCP. La phrase secrète est le mot de passe qui permettra à l'utilisateur d'ouvrir le contenu dans une application de lecture compatible. Ce même mot de passe doit être fourni par le libraire à l'utilisateur final. La valeur fournie dans ce paramètre, une représentation du mot de passe, doit subir les transformations suivantes, et ce, dans cet ordre:
|
| passphrase_hint | Optionnel | Pour la DRM LCP. Indice qui sera affiché à l'utilisateur comme aide-mémoire pour retrouver son mot de passe. La valeur du paramètre doit être encodée pour URL. |
| help_url | Optionnel | Pour la DRM LCP. URL d'une page d'aide spécifique à l'ouverture de contenus protégés par LCP, fournie par le libraire. L'utilisateur sera dirigé au besoin vers cette page. La valeur du paramètre doit être encodée pour URL. (255 caractères maximum) |
| 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. |
| ||
Réponses
| Code HTTP | Valeur | Description |
|---|---|---|
| 201 | created | La vente a été créée avec succès. |
| 400 | cannot_sell | L'organisation ne peut pas vendre cette publication. |
| duplicate | La vente existe déjà. | |
| missing_format | Le format était absent de la requête. | |
| invalid_format | Le format fourni n'est pas disponible pour cette publication. | |
| invalid_sale_parameters | La valeur d'un des paramètres cost, country, currency ou price_type est invalide. | |
| missing_cost | Le prix était absent de la requête. | |
| missing_customer_id | Le numéro unique du client était absent de la requête. | |
| missing_transaction_id | Le numéro unique de la transaction était absent de la requête. | |
| missing_protection | Le type de protection était absent de la requête. | |
| invalid_protection | Cette protection n'est pas disponible dans ce format. | |
| invalid_sale_state | L'état de vente n'est pas valide | |
| invalid_country | Le code de pays est invalide. | |
| invalid_price_type | Le type de prix est invalide. | |
| invalid_drm_type | Le type de verrou est invalide. | |
| unauthorized_drm_type_for_retailer | Les paramètres du libraire ne l’autorisent pas à livrer des fichiers protégés avec ce type de verrou. | |
| unauthorized_drm_type_by_publisher | Les paramètres de l’éditeur n’autorisent pas ce type de verrou. | |
| invalid_passphrase | Le mot de passe est invalide. | |
| invalid_passphrase_url | L’URL pour la page d’aide est trop longue. | |
| invalid_quantity | La quantité fournie n'est pas valide. | |
| 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 n'est pas disponible. |
Notes
Les ventes déclarées via cette API sont facturées. Cependant, afin d'effectuer une vente de test (par exemple, lors du développement de la connexion à cette API), 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 tableau.