Service Web revendeur

Un article de DocuWiki.

Sommaire

Introduction

Requête et réponse

Les requêtes se font via une commande HTTP GET ou POST. La réponse est retournée via un flux XML.

Différence entre ID immatériel et ID revendeur

L'ID immatériel est l'ID fournit par immatériel.fr pour une entité donnée. L'ID revendeur quant à elle est l'ID définie par le revendeur dans sa propre base.

Processus

Le processus de commande se compose en trois étapes :

  • création de l'ID client
  • création de la commande
  • récupération des URL d'accès

Codes d'erreur communs

  • InvalidKey : la clé d'API est invalide
  • UnknownReseller : le revendeur spécifié est inconnu
  • Forbidden : l'accès à cette requête est interdite
  • InternalError : une erreur indéterminée est survenue
  • DataMissing : des arguments obligatoires n'ont pas été renseignés

Récupération des métadonnées

Trouver un ou plusieurs titres (Vocabulaire XML : immatériel.fr)

https://ws.immateriel.fr/fr/web_service/book_query

Arguments

Commun
  • api_key : Clé d'identification
  • reseller_id : ID revendeur immatériel.fr ou reseller_dilicom_gencod : ID revendeur dilicom
Argument de recherche
  • isbn : ISBN de l'ouvrage
  • publisher_id : ID immatériel.fr de l'éditeur ou publisher_dilicom_gencod : ID dilicom de l'éditeur
  • since : titres ajoutés/modifiés depuis cette date format AAAA-MM-JJ
  • q : champ de recherche libre "Indisponible"

Si aucun argument de recherche n'est spécifié, tous les titres disponibles à la vente pour le revendeur sont retournés

Réponse

La réponse renvoyée est un flux xml validable à l'aide d'un schéma Relax NG (voir aussi la version human-friendly en syntaxe compacte et la version du W3C).

<response>
 <result type="Books">
  <book isbn="ISBN">
   <title>TITRE</title>
   <edition>EDITION</edition>
   <publisher>EDITEUR</publisher>
   <published_at>DATE_PUBLICATION</published_at>
   <author>AUTEUR</author>
   <summary>
    RESUME COURT
   </summary>
   <label>LIBELE</label>
   <price>PRIX</price>
   <products>
    <product label="Numérique" isbn="ISBN" price="PRIX" available="true">
     <resources>
      <resource support="immateriel" name="PDF" mimetype="application/pdf" protection="watermark"/>
     </resources>
    </product>
     ...
   </products>
  </book>
  <subscription isbn="ISBN">
    <title>TITRE</title>
    <publisher>EDITEUR</publisher>
    <summary>
     RESUME COURT
    </summary>
    <price>PRIX</price>
    <includes>
      <book isbn="ISBN">
        <resources>
          ...
        </resources>
      </book>
    </includes>
  </subscription>
 </result>
</response>
A propos de la réponse

Une œuvre (book) est associée à 1 ou plusieurs offres (product), une offre est composée de 1 ou plusieurs ressources (resource). Toutes les offres associées à une œuvre partagent les mêmes métadonnées ; les seules différences sont le prix, les ressources et l'isbn.

Notez que c'est l'ISBN de l'offre (product) qu'il faut utiliser pour passer commande.

Codes d'erreur

Codes communs uniquement

(OBSOLÈTE) Trouver un ou plusieurs titres (vocabulaire ONIX)

https://ws.immateriel.fr/fr/web_service/book_query_onix

Mêmes arguments que pour le XML immatériel.fr, mais résultats sous la forme ONIX 2.1

Trouver un ou plusieurs titres (vocabulaire ONIX 3.0)

https://ws.immateriel.fr/fr/web_service/book_query_onix_3_dilicom

Mêmes arguments que pour le XML immatériel.fr, mais résultats sous la forme ONIX 3.0

Trouver un ou plusieurs titres (format Unimarc)

https://ws.immateriel.fr/fr/web_service/book_query_unimarc

(Incomplet) Mêmes arguments que pour le XML immatériel.fr, mais résultats sous la forme Unimarc

Processus de commande

Créer un ID pour un client

https://ws.immateriel.fr/fr/web_service/push_customer

Arguments

Obligatoire
  • api_key : Clé d'identification
  • reseller_id : ID revendeur immatériel.fr ou reseller_dilicom_gencod : ID revendeur dilicom
  • customer_uid : ID client revendeur
  • email : email client
  • firstname : prénom client
  • lastname : nom client
  • country : pays adresse client (ISO-3166)
Facultatif
  • company : nom société
  • street : rue adresse client
  • complement : complement adresse client
  • zipcode : code postal adresse client
  • city : ville adresse client

Réponse

<response>
  <result id="ID_immateriel" customer_uid="UID_revendeur" type="CustomerCreated" login="email@client.fr" password="MDP">OK</result>
</response>
  • id : ID du client dans la base immatériel.fr
  • customer_uid : ID du client dans la base du revendeur
  • login : identifiant du client
  • password : mot de passe du client

Codes d'erreur

  • ExistingCustomer : le client a déjà été ajouté dans la base

Créer une nouvelle commande

https://ws.immateriel.fr/fr/web_service/push_order

Si vous agissez au nom de plusieurs libraires, il est nécessaire de commencer par s'assurer que le libraire responsable de la commande existe dans notre base. Pour cela, rendez-vous à la section concernant les agrégateurs de librairies.

Arguments

Obligatoire
  • api_key : Clé d'identification
  • reseller_id : ID revendeur immatériel.fr ou reseller_dilicom_gencod : ID revendeur dilicom
  • order_uid : ID commande revendeur
  • customer_uid : ID client revendeur
  • (OBSOLÈTE, ne plus utiliser) books : liste ISBN des produits sous la forme &books[]=ISBN1&books[]=ISBN2&books[]=ISBN3
  • order_lines : table de hachage des lignes de commandes ayant pour chaque produit :
    • price : prix en centimes
    • currency (facultatif, EUR par défaut) : devise
    • qty : quantité commandée

order_lines doit être sous la forme &order_lines[ISBN1][price]=PRIX1&order_lines[ISBN1][qty]=QUANTITE1&order_lines[ISBN2][price]=PRIX2&order_lines[ISBN2][qty]=QUANTITE2 Le prix doit être renseigné en centimes (4,99 euros doit être indiqué 499). Pour nos partenaires hors UE, il est également possible d'indiquer la devise via order_lines[ISBN1][currency]=CAD

Renseigner une liste de titres pour une même commande permet d'économiser sur les E/S réseaux et ainsi d'accélérer le passage de commande lorsque plusieurs titres sont commandés.

Réponse

<response>
  <result type="OrderCreated" download_key="CLETELECHARGEMENT" tax="xxx" amount="yyy" id="ID_immateriel" order_uid="UID_revendeur">OK</result>
</response>
  • id : ID de la commande dans la base immatériel.fr
  • order_uid : ID de la commande dans la base du revendeur
  • download_key : clé de téléchargement pour la commande
  • amount : montant total de la commande
  • tax : montant total des taxes

Codes d'erreur

  • ExistingOrder : la commande existe déjà dans la base
  • SellForbidden : vous n'êtes pas autorisé à commander un ou plusieurs des titres demandés
  • UnknownCustomer : le client n'existe pas dans la base : commencez par le créer via la commande push_customer

Vérifier la capacité de retour

https://ws.immateriel.fr/fr/web_service/voidable_order

Il est possible pour le revendeur d'effectuer des retours dans certaines conditions, par défaut un titre qui n'a pas été téléchargé, ou dont le DRM n'a pas été activé, peut être retourner. Afin d'effectuer un retour, il faut d'abord vérifier si le retour est possible.

Arguments

Obligatoire
  • api_key : Clé d'identification
  • reseller_id : ID revendeur immatériel.fr ou reseller_dilicom_gencod : ID revendeur dilicom
  • order_uid : ID commande revendeur
  • customer_uid : ID client revendeur
Facultatif
  • books : liste ISBN des produits à tester sous la forme &books[]=ISBN1&books[]=ISBN2&books[]=ISBN3. Par défaut toute la commande sera testée

Réponse

Si un des produits ne peut pas être annulés, une liste des téléchargements/activations DRM est renvoyé

<response>
 <result type="OrderNotVoidable" order_uid="UID">
  <product isbn="ISBN">
     <downloaded name="PDF" mimetype="application/pdf" last_download=""/>
  </product>
 </result>
</response>

Sinon

<response>
 <result type="OrderVoidable" id="ID" order_uid="UID">OK</result>
</response>

Effectuer un retour

https://ws.immateriel.fr/fr/web_service/cancel_order Attention, un seul retour est possible par commande.

Arguments

Obligatoire
  • api_key : Clé d'identification
  • reseller_id : ID revendeur immatériel.fr ou reseller_dilicom_gencod : ID revendeur dilicom
  • order_uid : ID commande revendeur
  • customer_uid : ID client revendeur
Facultatif
  • books : liste ISBN des produits à annuler sous la forme &books[]=ISBN1&books[]=ISBN2&books[]=ISBN3. Par défaut toute la commande sera annulée

Réponse

<response>
 <result type="OrderCanceled" id="ID" return_id="IDRETOUR" order_uid="UID">OK</result>
</response>

Liste des téléchargements disponible pour une commande

https://ws.immateriel.fr/fr/web_service/order_download_list

Arguments

Obligatoire
  • api_key : Clé d'identification
  • reseller_id : ID revendeur immatériel.fr ou reseller_dilicom_gencod : ID revendeur dilicom
  • order_uid : ID commande revendeur

Réponse

<response>
 <result type="DownloadList" order_uid="UID">
  <product isbn="ISBN">
   <link url="http://ws.immateriel.fr/fr/web_service/download?resource_id=ID&download_key=DLKEY" 
        name="PDF" format_key="pdf" mimetype="application/pdf"/>
  </product>
 </result>
</response>
  • url : lien vers la ressource
  • name : nom de la ressource
  • mimetype : type MIME de la ressource
  • format_key : clé du format de la ressource

Codes d'erreur

  • UnknownOrder : la commande n'existe pas dans la base

Liste des téléchargements disponibles pour un client donné

https://ws.immateriel.fr/fr/web_service/customer_download_list

Arguments

Obligatoire
  • api_key : Clé d'identification
  • reseller_id : ID revendeur immatériel.fr ou reseller_dilicom_gencod : ID revendeur dilicom
  • customer_uid : ID client revendeur

Réponse

voir liste pour une commande

Codes d'erreur

  • UnknownCustomer : le client n'existe pas dans la base

Ajouter un revendeur (accès limité distributeurs)

https://ws.immateriel.fr/fr/web_service/push_reseller

Arguments

Obligatoire
  • api_key : Clé d'identification
  • dilicom_gencod : ID revendeur dilicom
  • company_name : nom revendeur
  • country : pays adresse revendeur (ISO-3166)
Facultatif
  • street : rue adresse revendeur
  • complement : complement adresse revendeur
  • zipcode : code postal adresse revendeur
  • city : ville adresse revendeur

Réponse

<response>
  <result id='ID_immateriel' reseller_dilicom_gencod="UID" type="ResellerCreated">OK</result>
</response>
  • id : ID du revendeur dans la base immatériel.fr
  • reseller_dilicom_gencod : gencod dilicom du revendeur
Outils personnels