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.

  1. Dans le cas d'une erreur de type 400, le détail de l'erreur est fourni dans un vecteur.