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.
Codes d'erreur
Codes communs uniquement
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
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
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
- books : liste ISBN des produits sous la forme &books[]=ISBN1&books[]=ISBN2&books[]=ISBN3
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
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
