Différences

Cette page vous donne les différences entre la révision choisie et la version actuelle de la page.

hub_principal:start [2014/11/03 12:56]
Dilicom
hub_principal:start [2018/04/23 11:22] (version actuelle)
Ligne 3: Ligne 3:
-L'API principale du hub numérique propose trois grandes fonctionnalités : La récupération des notices, la transmission de commandes et la vérification du chaînage entre livre physique et livre numérique.+L'API principale du hub numérique propose trois grandes fonctionnalités : la récupération des notices, la transmission de commandes et la vérification du chaînage entre livre physique et livre numérique.
  *Concernant la récupération des **notices**, 2 possibilités sont offertes :   *Concernant la récupération des **notices**, 2 possibilités sont offertes :
-    * Récupérer toutes les notices créées ou modifiées depuis une date donnée.+    * Récupérer toutes les notices créées ou modifiées depuis une date donnée,
    * Récupérer toutes les notices créées ou modifiées depuis la dernière connexion au service.     * Récupérer toutes les notices créées ou modifiées depuis la dernière connexion au service.
Ligne 12: Ligne 12:
  *Le passage de **commandes** se passe en 3 étapes (la première étant facultative) :   *Le passage de **commandes** se passe en 3 étapes (la première étant facultative) :
-    * Vérifier la disponibilité à l’instant T des livres commandés par le consommateur. +    * Vérifier la disponibilité à l’instant T des livres commandés par le consommateur, 
-    * Commander les livres.+    * Commander les livres,
    * Récupérer les liens pour les livres commandés.     * Récupérer les liens pour les livres commandés.
  *La vérification du **chaînage** se déroule en 2 étapes   *La vérification du **chaînage** se déroule en 2 étapes
-    * Vérifier le chaînage entre livre physique et livre numérique +    * Vérifier le chaînage entre livre physique et livre numérique, 
-    * Obtenir la (les) notices du livre numérique +    * Obtenir la (les) notices du livre numérique.
 //Rappel : Les Web services sont disponible dans deux version : SOAP et REST(html+json) //  //Rappel : Les Web services sont disponible dans deux version : SOAP et REST(html+json) //
-===== Version SOAP ===== 
-Les WSDL des deux plateformes sont : 
-  * Plateforme de **test** : https://hub-test.centprod.com/v1/hub-numerique/hub-numerique-services.wsdl 
-  * Plateforme de **production** : https://hub-dilicom.centprod.com/v1/hub-numerique/hub-numerique-services.wsdl 
 +===== Gestion des versions de l'API HUB =====
 +A chaque évolution importante de l'API HUB (par exemple la modification du WSDL : ajout de nouveaux services, ...), le service passe de la version N à la version N+1. Le numéro de version commence par le numéro 1. Ce numéro est visible dans les URL(s) des services. La syntaxe est la suivante :
-=> [[examples_soap|Voir les exemples soap]]+**[ [[:start#les_differentes_plateformes_gerees_par_le_hub|Nom de la plateforme]]]/v[ [[[hub_principal:start#versions_de_l_api_hub|numéro de version]] ]/hub-numerique/[nom de service]**
-===== Version REST (http+json) ===== +==== Versions de l'API HUB ==== 
-Cette API donne accès aux mêmes fonctionnalités que le web service SOAP. Cependant celle-ci utilise, suivant le principe [[http://fr.wikipedia.org/wiki/Representational_State_Transfer|REST]], de simples requêtes [[http://fr.wikipedia.org/wiki/HTTP|Http]] et renvoie ses réponses sous forme de simples objets [[http://fr.wikipedia.org/wiki/JSON|Json]]. Selon la technologie utilisée, et même si elle ne fournie pas un cadre aussi serré que le WSDL, l'API REST peut être plus simple à utiliser que le web service SOAP. Il existe en effet des librairies de parsing [[http://fr.wikipedia.org/wiki/JSON|JSON]] et de requêtage [[http://fr.wikipedia.org/wiki/HTTP|Http]] dans tous les principaux langages de programmation web (python, php, ..). +^Numéro de version^Statut^URL WSDL^Date de mise en production^Date de désactivation de la version^Modifications^ 
 +|1|Actif|v1|  01-06-2010  | 30-06-2015  | [[historique_des_modifications_hub_principal:v1|historiques de modification v1]]
 +|2|Actif|v2| 13-01-2014   |  30-06-2015  | [[historique_des_modifications_hub_principal:v2|historiques de modification v2]]
 +|3|Actif|v3|  05-02-2015  |  | [[historique_des_modifications_hub_principal:v3|historiques de modification v3]]|
-Les urls a utiliser sur les deux plateformes seront du type :  +==== Adresses de l'API HUB ====
-  * Plateforme de **test** : <html><strong>https://hub-test.centprod.com/v1/hub-numerique-api/json/<em>[SERVICE]</em></strong></html> +
-  * Plateforme de **production** : <html><strong>https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/<em>[SERVICE]</em></strong></html>+
 +**Version SOAP :** le WSDL est disponible via l'URL suivant :
-=> [[examples_api_json|Voir les exemples REST]]+  * plateforme de test: https://hub-test.centprod.com/v[ [[[hub_principal:start#versions_de_l_api_hub|numéro de version]] ]/hub-numerique/hub-numerique-services.wsdl 
 +  * plateforme de production: https://hub-dilicom.centprod.com/v[ [[[hub_principal:start#versions_de_l_api_hub|numéro de version]] ]/hub-numerique/hub-numerique-services.wsdl
 +Exemple :
 +    * version n°3 (Plateforme de production) : https://hub-dilicom.centprod.com/v3/hub-numerique/hub-numerique-services.wsdl
 +    * version n°3 (Plateforme de test) : https://hub-test.centprod.com/v3/hub-numerique/hub-numerique-services.wsdl
-====== Description de l'API =====+**Version REST :**  les différents services sont disponibles aux URL suivantes : 
 +       * plateforme de test: https://hub-test.centprod.com/v[ [[[hub_principal:start#versions_de_l_api_hub|numéro de version]] ]/hub-numerique-api/json/[nom de service] 
 +       * plateforme de production: https://hub-dilicom.centprod.com/v[ [[[hub_principal:start#versions_de_l_api_hub|numéro de version]] ]/hub-numerique-api/json/[nom de service]
-===== Récupération des notices : getNotices() ===== +===== Authentification =====
-==== Horaires de mise à disposition ==== +
-Les mises à jour catalogue sont mises à disposition sur le HUB chaque matin entre 5h55 et 9h environ, en fonction du nombre de mises à jour déposées par les plateformes, à l'exception des mises à jour de la plateforme Interforum Editis qui sont mises à disposition entre 22h50 et 23h30.+
-Il est recommandé de récupérer les mises à jour au moins quotidiennement, et si possible plusieurs fois par jour en utilisant le paramètre "LastConnection" (voir cas 3).+Pour utiliser le Web service vous avez besoin pour chaque méthode de renseigner votre code d'accès //(glnReseller)// ainsi que le mot de passe  //(passwordReseller)// qui vous a été fourni par Dilicom.
-==== EAN13 ==== 
-Un EAN 13 n'est pas forcément unique dans la base de donnée Hub Dilicom, un même article pouvant être distribué par plusieurs plateformes. 
-Cependant le couple EAN13/GLN Supplier sera toujours unique. 
-==== Interrogation du web service ==== +  * En **Rest** vous devez fournir vos éléments d'authentification en utilisant l'authentification [[http://fr.wikipedia.org/wiki/HTTP_Authentification|HTTP Basic]]. 
-=== Paramètres communs === +  * En **Soap** vous devez renseigner les deux éléments **glnReseller** et **passwordReseller** :<code xml> 
-Le revendeur a trois possibilités pour interroger ce service. Cependant il existe des informations communes pour ces trois messages. +<xxxxRequest> 
-Il doit nous fournir son GLN, son mot de passe et éventuellement un GLN de groupe. Pour la suite, il a donc le choix entre les 3 cas suivants:+ <glnReseller>3026900001000</glnReseller> 
 + <passwordReseller>3x59ftmdmdEds</passwordReseller> 
 + ... 
 +</xxxxRequest> 
 +</code> 
 +\\
-=== Cas 1 – Initialisation du catalogue (service désactivé) ===  +En cas d'erreur d'authentification (code d'accès ou mot de passe invalide) le service retourne un message avec comme ''returnValue'' **AUTHENTICATION_ERROR** //(cf [[start#Gestion des erreurs et codes de retour|Gestion des erreurs et codes de retour]] )//
-Pour préciser un tel choix vous devez indiquer le paramètre ''initialization'' sans contenu particulier. +
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       | +
-^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | +
-^ initialization    | Indique une demande d'initialisation du catalogue        | Obligatoire, chaîne vide (non null)      | +
- => [[examples_soap#cas_1_initialisation_du_catalogue|Exemple SOAP]] +
- +
 +===== Gestion des erreurs et codes de retour =====
 +Une erreur peut se produire lors de l’interrogation du Web service si le code d'accès indiqué est erroné, le mot de passe est invalide, l’EAN13 commandé est inconnu, etc. Dans ce cas, le serveur renvoie une réponse contenant les champs **''returnStatus''** et **''returnMessage''** précisant l'erreur rencontrée.
 +Le champ <returnStatus> exprime le statut de traitement interne du HUB. Si tout s'est bien passé au niveau du HUB, le champ ''<returnStatus>'' contiendra la valeur "OK", même si la plateforme interrogée a renvoyé une erreur.
-=> [[examples_api_json#cas_1_initialisation_du_catalogue|Exemple REST]] 
-Ce service a été désactivé, les catalogues complets sont mis à disposition à la demande sur un compte FTP.+  * Exemple SOAP : <code xml> 
 +<xxxxResponse> 
 + <returnStatus>AUTHENTICATION_ERROR</returnStatus> 
 + <returnMessage>Bad login</returnMessage > 
 +</xxxxResponse> 
 +</code> 
 +  * Exemple REST :<code javascript> 
 +
 + returnStatus:"INVALID_ARGUMENTS", 
 + returnMessage:["The content of element getNotices request is not complete. A valid 'sinceDate', 'lastConnection' or 'initialization' parameter is expected."] 
 +
 +</code>
-<note important> 
-Attention : l'option initialization a été désactivée, merci de contacter Dilicom pour plus d’informations. 
-</note> 
-=== Cas 2 – Récupération depuis une date donnée === +==== Codes de retour (returnStatus) ====
-Ici, c’est le paramètre ''sinceDate'' contenant la date souhaitée qui doit être présent. Cette fonctionnalité est limitée à une période de 8 jours. +
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       | +
-^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | +
-^ sinceDate    | Récupération des notices publiées depuis cette date.      | Obligatoire, au format ISO 8601  (AAAA-MM-JJTHH:MM:SS), ne doit pas être antérieur à 8 jours.         | +
-=> [[examples_soap#cas_2_recuperation_depuis_un_instant_t|Exemple SOAP]]+
 +Les codes de retours HUB sont résumés dans le tableau ci-dessous:
 +^ Code      ^ Description       ^
 +|OK |Aucune erreur, le service a répondu normalement. |
 +|ERROR |Une erreur non spécifiée a eu lieu. |
 +|WARNING  |Certains éléments sont en erreur (par exemple certaines lignes de commandes).|
 +|INVALID_ARGUMENTS | Les argument indiqués sont erronés, ou bien certains paramètres obligatoires ne sont pas renseignés.|
 +|DUPLICATED | Un élément est en doublon (Ligne de commande, orderId). Pour plus d'information se référer aux détails des retours. |
 +|UNKNOWN_GLN  | Le GLN distributeur indiqué est inconnu. |
 +|ORDERID_NOT_FOUND   |l'orderId indiqué n'existe pas. |
 +|EAN_NOT_FOUND   |l'EAN13 indiqué n'existe pas.  |
 +|EAN_NOT_AVAILABLE   | Vous n'avez pas accès, ou pas le droit de commander cet EAN13.|
 +|PLATFORM_ACCES_DENIED  | Vous n'êtes pas abonné à ce distributeur. |
 +|AUTHENTICATION_ERROR  | Erreur d'authentification sur le Hub, votre code d'accès ou mot de passe est probablement erroné. |
 +|CANCELLED|Une ligne de commande est annulée avec succès.|
 +|PRODUCT_NOT_IN_ORDER|La ligne de commande à annuler n'existe pas.|
 +|ALREADY_DOWNLOADED| Un des liens de téléchargement de l’article a déjà été utilisé, la ligne de commande ne peut donc plus être annulée.|
 +|SERVICE_NOT_PROVIDED| Erreur survenue  si le distributeur ne fournit pas le service d’annulation ou si le revendeur demande l’annulation des lignes de commande pour un distributeur qui n’accepte que l’annulation de commande complète, et que les lignes de la commande à annuler ne représentent pas l’intégralité de la commande.|
-=> [[examples_api_json#cas_2_recuperation_depuis_un_instant_t|Exemple REST]] 
-=== Cas 3 – Récupération depuis la dernière connexion === 
-Ici, c’est le paramètre ''lastConnection'' qui doit être présent. Il ne nécessite pas de contenu. 
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       | 
-^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | 
-^ lastConnection    | Indique une récupération des fiches publiées depuis la dernière connexion       | Obligatoire, chaine vide (non null)     | 
-=> [[examples_soap#cas_3_recuperation_depuis_la_derniere_connexion|Exemple SOAP]] 
-=> [[examples_api_json#cas_3_recuperation_depuis_la_derniere_connexion|Exemple REST]] 
-<note important>Attention : Pour utiliser l'option 'lastConnection' il est nécessaire de s'être connecté au moins une fois avec le paramètre 'SinceDate' au préalable, afin que le serveur puisse dater la dernière connexion.</note> 
-<note important>Si la dernière connexion s'est produite plus de 8 jours avant la date de la requête, le fichier de mise à jour ne pourra pas être fourni.</note> 
-<note important>Actuellement au maximum 5 appels de l'option 'lastConnection" sont autorisés par période de 24h.</note> 
-==== Réponse du Web Service ==== 
-Réponse ''GetNoticesResponse'' :  
-^ returnStatus | ''OK'' indique que l'appel au service s'est bien passé.|''OK'' | 
-^ onixFileUrl[] | Liste d'éléments onixFileUrl pour les notices correspondant à la requête. |//cf. ci-dessous// | 
-^ noNotice  | Indique qu'il n'y a aucune fiche à diffuser. Si cet élément est présent alors la réponse ne comporte pas d'éléments onixFileUrl | Chaine vide (non null) | 
-Éléments ''onixFileUrl'' :  
-^ httpLink  | Lien http vers un fichier ONIX | 
-Le réponse du web service en cas de succès comporte un élément ''returnStatus'' positionné a 'OK' ainsi qu'une liste d'éléments du type ''onixFileUrl'' Chaque élément ''onixFileUrl'' contenant lui même l'url http d'un fichier ONIX :''httpLink''.   (ces liens http seront prochainement accompagnés de liens ftp)  
-Si éventuellement il n’y avait aucune fiche à diffuser, on renvoie un message contenant ''returnStatus'' positioné à ''OK'', ainsi qu'un élément ''noNotice'' vide (mais non null). 
-<note> 
-Les liens retournés pointent vers des fichier XML content les notices ONIX. Vous devez donc, suite à l'appel du web service, télécharger le ou les liens proposés afin d'en intégrer le contenu dans votre base. 
-</note> 
-<note important> 
-Actuellement le web service renvoie toujours un seul lien, cependant il est possible qu'à terme il soit nécessaire de renvoyer plusieurs liens et le cas est donc prévu. 
-</note> 
-<note important> 
-Lors de grosses mises à jour le temps de réponse de ce service peut être de l'ordre de 5 minutes. Il est donc conseillé d'augmenter la valeur de timeout de cette méthode (par exemple 10 minutes). 
-</note> 
-=> [[examples_soap#reponse_du_web_service|Exemples SOAP]]+====== Description de l'API =====
-=> [[examples_api_json#reponse_du_web_service|Exemples REST]] 
-===== Récupération des notices pour un seul distributeur : getNoticesForDistributor() ===== 
-==== Interrogation du web service ==== 
-=== Paramètres communs === 
-Le revendeur a trois possibilités pour interroger ce service. Cependant il existe des informations communes pour ces trois messages. 
-Il doit nous fournir son GLN, son mot de passe et éventuellement un GLN de groupe. Pour la suite, il a donc le choix entre les 3 cas suivants: 
-=== Cas 1 – Initialisation du catalogue (service désactivé) === 
-Pour préciser un tel choix vous devez indiquer le paramètre ''initialization'' sans contenu particulier. 
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       | 
-^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | 
-^ glnDistributor  | Gln du distributeur dont on veut obtenir le catalogue | Obligatoire, numérique, 13 caractères              | 
-^ initialization    | Indique une demande d'initialisation du catalogue        | Obligatoire, chaîne vide (non null)      | 
- => [[examples_soap#cas_1_initialisation_du_catalogue_pour_un_distributeur|Exemple SOAP]] 
-<note important>Attention : l'option initialization a été désactivée, merci de contacter Dilicom pour plus d’informations.</note> 
-  
Ligne 160: Ligne 138:
-=== Cas 2 – Récupération depuis une date donnée === 
-Ici, c’est le paramètre ''sinceDate'' contenant la date souhaitée qui doit être présent. 
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       | 
-^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | 
-^ glnDistributor  | Gln du distributeur dont on veut obtenir le catalogue | Obligatoire, numérique, 13 caractères              | 
-^ sinceDate    | Récupération des notices publiées depuis cette date       | Obligatoire, au format ISO 8601  (AAAA-MM-JJTHH:MM:SS)         | 
-=> [[examples_soap#cas_2_recuperation_depuis_un_instant_t_pour_un_distributeur|Exemple SOAP]] 
-==== Réponse du Web Service ==== 
- 
-Réponse ''GetNoticesResponse'' :  
-^ returnStatus | ''OK'' indique que l'appel au service s'est bien passé.|''OK'' | 
-^ onixFileUrl[] | Liste d'éléments onixFileUrl pour les notices correspondant à la requête. |//cf. ci-dessous// | 
-^ noNotice  | Indique qu'il n'y a aucune fiche à diffuser. Si cet élément est présent alors la réponse ne comporte pas d'éléments onixFileUrl | Chaine vide (non null) | 
- 
-Éléments ''onixFileUrl'' :  
- 
-^ httpLink  | Lien http vers un fichier ONIX | 
- 
-Le réponse du web service en cas de succès comporte un élément ''returnStatus'' positionné a 'OK' ainsi qu'une liste d'éléments du type ''onixFileUrl''. Chaque élément ''onixFileUrl'' contenant lui même l'url http d'un fichier ONIX :''httpLink''.   (ces liens http seront prochainement accompagnés de liens ftp)  
-Si éventuellement il n’y avait aucune fiche à diffuser, on renvoie un message contenant ''returnStatus'' positioné à OK, ainsi qu'un élément ''noNotice'' vide (mais non null). 
- 
-<note> 
-Les liens retournés pointent vers des fichier XML contenant les notices ONIX. Vous devez donc, suite à l'appel du web service, télécharger le ou les liens proposés afin d'en intégrer le contenu dans votre base. 
-</note> 
-=> [[examples_soap#reponse_du_web_service1|Exemples SOAP]] 
===== Vérification des disponibilités : checkAvailability() ===== ===== Vérification des disponibilités : checkAvailability() =====
Ligne 193: Ligne 146:
Ce service permet aux revendeurs de vérifier avant d’encaisser le paiement que le livre numérique est bien disponible au moment du passage de la commande. Ce service permet aux revendeurs de vérifier avant d’encaisser le paiement que le livre numérique est bien disponible au moment du passage de la commande.
-<note important>//Ce service n’est implémenté que pour les distributeurs Editis, Eden et Harmathèque. Pour les autres plateformes, si un produit existe et est disponible et actif dans la base du Hub, il est alors available//</note>+<note important>//Ce service n’est implémenté que pour les distributeurs Editis, Eden et Harmathèque. Pour les autres plateformes, si un produit existe et est disponible et actif dans la base du Hub, il est alors available.//</note>
==== Interrogation du web service ==== ==== Interrogation du web service ====
-Le revendeur doit fournir son GLN, son mot de passe ainsi que la liste d’articles qu’il souhaite vérifier. Chaque ligne contient l’EAN13, le GLN distributeur et éventuellement le prix unitaire. Si le prix est fourni, on vérifie que l’article existe bien avec le prix demandé :+Le revendeur doit fournir son code d'accès, son mot de passe ainsi que la liste d’articles qu’il souhaite vérifier. Chaque ligne contient l’EAN13, le GLN distributeur et éventuellement le prix unitaire.  
 +Ce service vérifie la disponibilité des articles fournis : d'abord leur existence dans la base du HUB, puis leur disponibilité chez le distributeur lorsque celui-ci dispose d'un service dédié. 
 +Remarque : le prix n'est pas vérifié 
Paramètre ''CheckAvailabilityRequest'' : Paramètre ''CheckAvailabilityRequest'' :
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       |+^ glnReseller    | Votre code d'accès  | Obligatoire, numérique, 13 caractères       |
^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | ^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^country  |Pays du revendeur |Facultatif, [[http://www.iso.org/iso/fr/home/standards/country_codes/iso-3166-1_decoding_table.htm|ISO 3166-1 (liste 91 dans Onix)]]|
^ checkAvailabilityLine[]    | Liste d'éléments ''checkAvailabilityLine'' spécifiant les  disponibilités à vérifier  | Obligatoire   //(cf ci-dessous)//   | ^ checkAvailabilityLine[]    | Liste d'éléments ''checkAvailabilityLine'' spécifiant les  disponibilités à vérifier  | Obligatoire   //(cf ci-dessous)//   |
Ligne 211: Ligne 169:
^ glnDistributor  | Distributeur du livre à vérifier | Obligatoire, numérique, 13 caractères              | ^ glnDistributor  | Distributeur du livre à vérifier | Obligatoire, numérique, 13 caractères              |
^ unitPrice    | Prix unitaire en centimes du livre à vérifier  | Facultatif, nombre entier du prix en centimes    | ^ unitPrice    | Prix unitaire en centimes du livre à vérifier  | Facultatif, nombre entier du prix en centimes    |
 +^unitPriceExcludingTax  |Prix unitaire HT utilisé par le revendeur. Exprimé en centimes. Entier non négatif. 1250 = 12,50|Facultatif, nombre entier|
 +^currency  | Devise utilisée pour le prix. |Conditionnel. Obligatoire dans le cadre des échanges avec Eden. [[http://www.iso.org/iso/fr/home/standards/currency_codes.htm|ISO 4217(Liste 96 Onix)]] |
<note important>Le prix unitaire est facultatif mais il est à noter que pour la plateforme Eden le prix est validé lors de la requête checkAvailability, dans ce cas si le prix est incorrect ou non indiqué, la ligne correspondante retournera une erreur. </note> <note important>Le prix unitaire est facultatif mais il est à noter que pour la plateforme Eden le prix est validé lors de la requête checkAvailability, dans ce cas si le prix est incorrect ou non indiqué, la ligne correspondante retournera une erreur. </note>
-=> [[examples_soap#interrogation_du_web_service2|Exemple SOAP]]+=> [[examples_soap#interrogation_du_web_service|Exemple SOAP]]
-=> [[examples_api_json#interrogation_du_web_service1|Exemple REST]]+=> [[examples_api_json#interrogation_du_web_service|Exemple REST]]
==== Réponse du web service ==== ==== Réponse du web service ====
Réponse ''CheckAvailabilityResponse'' : Réponse ''CheckAvailabilityResponse'' :
-^ checkAvailabilityResponseLine[]  | Liste des éléments à vérifier| //cf. ci-dessous // |  +^requestId  | Identifiant de la requête | Facultatif, alphanumérique | 
-^ returnStatus  | Statut de la réponse |//cf. [[:start#codes_de_retour_returnstatus|Codes de retour]] // |+^ checkAvailabilityResponseLine[]  |Liste des éléments à vérifier| Facultatif, //cf. ci-dessous // |  
 +^ returnStatus  | Statut de la réponse | Obligatoire, // cf. [[hub_principal:start#codes_de_retour_returnstatus|Codes de retour]] //
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
Éléments ''checkAvailabilityResponseLine'' : Éléments ''checkAvailabilityResponseLine'' :
-^ ean13    | EAN13 du livre          | Numérique, 13 caractères       | +^ ean13    | EAN13 du livre          | Obligatoire, Numérique, 13 caractères       | 
-^ glnDistributor  | GLN du distributeur | Numérique, 13 caractères             | +^ glnDistributor  | GLN du distributeur |Obligatoire, Numérique, 13 caractères             | 
-^ checkAvailabilityReturnValue    | Disponibilité du livre        |<html><ul>+^ checkAvailabilityReturnValue    |Disponibilité du livre        |Obligatoire, <html><ul>
<li> <code>AVAILABLE</code> :disponible</li> <li> <code>AVAILABLE</code> :disponible</li>
<li> <code>UNAVAILABLE</code> : non disponible</li> <li> <code>UNAVAILABLE</code> : non disponible</li>
<li> <code>NOT_KNOWN</code> : Ne sait pas – <em>cas des distributeurs qui ne stockent pas leurs notices sur le Hub</em></li> <li> <code>NOT_KNOWN</code> : Ne sait pas – <em>cas des distributeurs qui ne stockent pas leurs notices sur le Hub</em></li>
</ul></html>| </ul></html>|
 +^ returnStatus  | Statut de la réponse |Obligatoire, //cf. [[hub_principal:start#codes_de_retour_returnstatus|Codes de retour]]// |
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
 +
<note important>Attention : la valeur ''returnStatus OK'', n'indique **en aucun cas** que tous les éléments sont "AVAILABLE", cela indique simplement que la requête web service s'est bien passée. La valeur importante en réponse d'un checkAvailability est la valeur ''checkAvailabilityReturnValue''  qui donne le statut "UNAVAILABLE" ou  "AVAILABLE" de chaque élément vérifié. </note> <note important>Attention : la valeur ''returnStatus OK'', n'indique **en aucun cas** que tous les éléments sont "AVAILABLE", cela indique simplement que la requête web service s'est bien passée. La valeur importante en réponse d'un checkAvailability est la valeur ''checkAvailabilityReturnValue''  qui donne le statut "UNAVAILABLE" ou  "AVAILABLE" de chaque élément vérifié. </note>
-=> [[examples_soap#reponse_du_web_service2|Exemple SOAP]]+=> [[examples_soap#reponse_du_web_service|Exemple SOAP]]
-=> [[examples_api_json#reponse_du_web_service1|Exemple REST]]+=> [[examples_api_json#reponse_du_web_service|Exemple REST]]
===== Passage de commandes : sendOrder() ===== ===== Passage de commandes : sendOrder() =====
Ligne 245: Ligne 210:
==== Interrogation du web service ==== ==== Interrogation du web service ====
Paramètre  ''SendOrderRequest'' : Paramètre  ''SendOrderRequest'' :
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       |+^ glnReseller    | Votre code d'accès | Obligatoire, numérique, 13 caractères       |
^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | ^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
^ orderId  |Numéro de commande dans votre référentiel de commandes. |Obligatoire, alphanumérique, max 16 caractères  | ^ orderId  |Numéro de commande dans votre référentiel de commandes. |Obligatoire, alphanumérique, max 16 caractères  |
-^ glnGroup  | GLN groupe.  | Facultatif, numérique, 13 caractères  | +^ glnGroup  | GLN groupe.  | Facultatif, numérique, 13 caractères  
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       | 
 +^glnDelivery  |Gln du "Livré à" dans le cas ou le glnReseller est un grossiste| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
^ customerId  | Identifiant du client passant la commande dans votre référentiel.| Obligatoire, alphanumérique, max 35 caractères  | ^ customerId  | Identifiant du client passant la commande dans votre référentiel.| Obligatoire, alphanumérique, max 35 caractères  |
^ finalBookOwner  |Informations sur la personne à qui est destinée le produit commandé. | Obligatoire,  //Cf. ci-dessous //| ^ finalBookOwner  |Informations sur la personne à qui est destinée le produit commandé. | Obligatoire,  //Cf. ci-dessous //|
Ligne 256: Ligne 223:
^ identifier    | Identifiant du destinataire final dans votre référentiel | Obligatoire,alphanumérique, max 35 caractères        | ^ identifier    | Identifiant du destinataire final dans votre référentiel | Obligatoire,alphanumérique, max 35 caractères        |
^ civility  | Civilité du destinataire final | Obligatoire<html><ul><li><code>M</code></li><li><code>MME</code></li><li><code>MLE</code></li></ul></html>              | ^ civility  | Civilité du destinataire final | Obligatoire<html><ul><li><code>M</code></li><li><code>MME</code></li><li><code>MLE</code></li></ul></html>              |
-^ firstName  |Prénom du destinataire final. | Obligatoire, max 35 caractères  |+^ firstName  |Prénom du destinataire final. | Facultatif, max 35 caractères  |
^ lastName  |Nom du destinataire final.| Obligatoire, max 35 caractères | ^ lastName  |Nom du destinataire final.| Obligatoire, max 35 caractères |
^ email  |Adresse e-mail du destinataire final. | Obligatoire, max 138 caractères | ^ email  |Adresse e-mail du destinataire final. | Obligatoire, max 138 caractères |
-^ country  | Pays du destinataire final.  | Obligatoire,  exemple : FR|+^ country  | Pays du destinataire final.  | Obligatoire,  [[http://www.iso.org/iso/fr/home/standards/country_codes/iso-3166-1_decoding_table.htm|ISO 3166-1 (liste 91 dans Onix)]]|
^ postalCode  | Code postal destinataire final.  | Obligatoire,  exemple :  94120, max 35 caractères| ^ postalCode  | Code postal destinataire final.  | Obligatoire,  exemple :  94120, max 35 caractères|
^ city  | Ville du destinataire final.  | Obligatoire, max 35 caractères| ^ city  | Ville du destinataire final.  | Obligatoire, max 35 caractères|
<note tip> <note tip>
-Bien que les valeurs ''firstName'' et ''email'' soient facultatives il est fortement recommandé de les indiquer. En effet ces valeurs peuvent être nécessaires aux plateformes en particulier lors de l'utilisation de watermarking. Il faut aussi rajouter un contrôle pour vérifier que l'émail est de type (xxx@yyy.zz) s'il est renseigné.+Les valeurs firstName et email sont être nécessaires aux plateformes en particulier lors de  
 +l'utilisation de watermarking. Il convient de rajouter un contrôle pour vérifier que l’email est de type (xxx@yyy.zz). 
</note> </note>
Ligne 271: Ligne 240:
^ glnDistributor  | GLN du distributeur du livre | Obligatoire, numérique sur 13 caractères | ^ glnDistributor  | GLN du distributeur du livre | Obligatoire, numérique sur 13 caractères |
^ unitPrice  |Prix unitaire |Obligatoire, nombre entier correspondant au prix en centimes | ^ unitPrice  |Prix unitaire |Obligatoire, nombre entier correspondant au prix en centimes |
-^ quantity  |Quantité à commander. | Obligatoire, nombre entier. // Pour le moment nous ne gérons que la quantité 1, quelle que soit la quantité indiquée.// | +^unitPriceExcludingTax  |Prix unitaire HT utilisé par le revendeur. Exprimé en centimes. Entier non négatif. 1250 = 12,50|Conditionnel, nombre entier| 
-^ lineReference  |Référence ligne dans votre référentiel. | Facultatif,  alphanumérique, max 16 caractères |+^currency  | Devise utilisée pour le prix. |Conditionnel. [[http://www.iso.org/iso/fr/home/standards/currency_codes.htm|ISO 4217(Liste 96 Onix)]] | 
 +^quantity  |Quantité à commander. | Obligatoire, nombre entier. // Pour le moment nous ne gérons que la quantité 1, quelle que soit la quantité indiquée.// | 
 +^lineReference  |Référence ligne dans votre référentiel. | Facultatif,  alphanumérique, max 16 caractères | 
 +^specialCode  |Référence opération. | Facultatif,  alphanumérique, max 25 caractères |
<note tip> <note tip>
Le prix est donné en centimes (12,50€ sera renseigné sous la forme 1250). Le prix est donné en centimes (12,50€ sera renseigné sous la forme 1250).
</note> </note>
 +
 +<note tip>
 +Le champ currency doit impérativement être présent :
 +  * si la commande concerne un achat hors zone euro pour une ressource hébergée sur la plateforme IMMATERIEL.
 +  * **À partir du 1er septembre 2016** : si la commande concerne un achat sur la plateforme EDITIS.
 +  * si la commande concerne un achat sur la plateforme EDEN.
 +
 +</note>
 +
 +<note important>
 +**À partir du 1er septembre 2016** : Le champ unitPriceExcludingTax doit impérativement être renseigné si la commande concerne un achat sur la plateforme EDITIS.
 +</note>
 +
<note important>Pour l’instant, quelle que soit la quantité renseignée, nous considérons que la quantité est à 1 en attendant que toutes les plateformes soient en mesure de la gérer.</note> <note important>Pour l’instant, quelle que soit la quantité renseignée, nous considérons que la quantité est à 1 en attendant que toutes les plateformes soient en mesure de la gérer.</note>
Ligne 283: Ligne 268:
<note important>Pour les commandes très longues envoyées sur l'API REST, il convient de passer les paramètres de la commande dans le body, afin de ne pas rencontrer l'erreur "414 - URI too large". Dans ce cas l'appel HTTP doit être fait en POST.</note> <note important>Pour les commandes très longues envoyées sur l'API REST, il convient de passer les paramètres de la commande dans le body, afin de ne pas rencontrer l'erreur "414 - URI too large". Dans ce cas l'appel HTTP doit être fait en POST.</note>
-=> [[examples_soap#interrogation_du_web_service3|Exemple SOAP]]+=> [[examples_soap#interrogation_du_web_service1|Exemple SOAP]]
-=> [[examples_api_json#interrogation_du_web_service2|Exemple REST]]+=> [[examples_api_json#interrogation_du_web_service1|Exemple REST]]
==== Réponse du web service ==== ==== Réponse du web service ====
Ligne 294: Ligne 279:
Réponse ''SendOrderResponse'' : Réponse ''SendOrderResponse'' :
-^ orderId  | Identifiant de la commande dans votre référentiel | Alphanumérique, max 16 caractères.| +^requestId  | Identifiant de la requête | Facultatif, alphanumérique | 
-^ orderLine[]  |Liste des éléments commandés | //cf. ci-dessous // | +^ orderId  | Identifiant de la commande dans votre référentiel |Facultatif,  Alphanumérique, max 16 caractères.| 
-^ returnStatus  | Indique si la commande a été effectuée correctement | <html><ul>+^ orderLine[]  |Liste des éléments commandés | Facultatif , //cf. ci-dessous // | 
 +^ returnStatus  | Indique si la commande a été effectuée correctement |Obligatoire   , <html><ul>
<li><code>OK</code> : Toute la commande a été transmise correctement.</li> <li><code>OK</code> : Toute la commande a été transmise correctement.</li>
<li><code>WARNING</code> : Une ou plusieurs lignes de commande n'ont pas pu être transmises correctement. Certaines lignes ont été expédiées correctement</li> <li><code>WARNING</code> : Une ou plusieurs lignes de commande n'ont pas pu être transmises correctement. Certaines lignes ont été expédiées correctement</li>
<li><code>ERROR</code> : Une erreur est survenue durant la commande, aucune ligne n'a été expédiée.</li> <li><code>ERROR</code> : Une erreur est survenue durant la commande, aucune ligne n'a été expédiée.</li>
</ul></html>| </ul></html>|
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
Éléments ''orderLine'' : Éléments ''orderLine'' :
-^ ean13  | EAN13 de l'élément commandé| Numérique, 13 caractères.| +^ ean13  | EAN13 de l'élément commandé|Obligatoire, Numérique, 13 caractères.| 
-^ glnDistributor   | Distributeur du produit commandé| Numérique, 13 caractères.+^ glnDistributor   | Distributeur du produit commandé|Obligatoire,  Numérique, 13 caractères.| 
-^ link[]  | Liens associé au produit commandé.| +^ orderLineId  | Id de la ligne de commande dans le référentiel du HUB.|Obligatoire, numérique, 20 caractères    
-^ orderLineId  | Id unique de la ligne de commande dans le référentiel du HUB.| | +^ lineReference  |Référence ligne dans votre référenciel. |Obligatoire    | 
-^ lineReference  |Référence ligne dans votre référenciel. | | +^currency  | Devise utilisée pour le prix. |Facultatif, [[http://www.iso.org/iso/fr/home/standards/currency_codes.htm|ISO 4217(Liste 96 Onix)]] | 
-^ returnStatus   | Indique si la ligne commande a été transmise correctement | //cf. [[:start#codes_de_retour_returnstatus|Codes de retour]] // | +^ link[]  | Liens associé au produit commandé.|Facultatif  
-^ returnMessage   | Indique la cause d'erreur en cas de ''returnStatus'' différant de ''OK''  | Non défini si ''returnStatus'' est ''OK''|+^ returnStatus   | Indique si la ligne commande a été transmise correctement | Obligatoire, //cf. [[hub_principal:start#codes_de_retour_returnstatus|Codes de retour]] // | 
 +^ returnMessage   | Indique la cause d'erreur en cas de ''returnStatus'' différant de ''OK''  | Facultatif, Non défini si ''returnStatus'' est ''OK''|
Éléments ''link'' : Éléments ''link'' :
-^ url  | Url du lien | +^ url  | Url du lien | Facultatif  
-^ format  | Type de format | Format du fichier lié, utilise le code ONIX ProductForm (cf {{:onix-codelist-175.xls|liste 175}}  de la notice ONIX 3.0). Non défini si le format est inconnu. | +^ format  | Type de format | Obligatoire, Format du fichier lié, utilise le code ONIX ProductForm (cf {{:onix-codelist-175.xls|liste 175}}  de la notice ONIX 3.0). Non défini si le format est inconnu. | 
-^ formatDescription  | Description rapide du format | +^ formatDescription  | Description rapide du format |Obligatoire
-^ mimeType  | Lorsqu'il est disponible le type mime du fichier lié | Non défini si inconnu +^ ean13  | Lorsque l'on est dans le cas d'un multi-produit, indiquer l'EAN13 du composé lorsque l'information est disponible, sinon l'EAN13 du produit principal. |Obligatoire, //''Pour le moment nous indiquons toujours l'ean principal''//
-^ ean13  | Lorsque l'on est dans le cas d'un multi-produit, indiquer l'EAN13 du composé lorsque l'information est disponible, sinon l'EAN13 du produit principal. | //''Pour le moment nous indiquons toujours l'ean principal''// |+^ mimeType  | Lorsqu'il est disponible le type mime du fichier lié |Facultatif, Non défini si inconnu |
 +=> [[examples_soap#reponse_du_web_service1|Exemple SOAP]]
-=> [[examples_soap#reponse_du_web_service3|Exemple SOAP]]+ 
 + 
 +=> [[examples_api_json#reponse_du_web_service1|Exemple REST]] 
 + 
 +===== Annulation d'une commande : cancelOrder() ===== 
 + 
 + 
 + 
 +Ce service permet aux revendeurs l'annulation complète ou partielle d'une commande. 
 + 
 +<note important>Ce service n’est pas  implémenté pour les distributeurs: IKIOSQUE, HARMATHEQUE, OLF et IZNEO</note> 
 +<note tip>Les distributeurs qui acceptent l'annulation partielle d'une commande :   EDEN et  DE MARQUE 
 +</note> 
 +<note tip>Les distributeurs qui  n’acceptent pas l’annulation partielle d'une commande : EDITIS , DIALOGUES</note> 
 + 
 + 
 + 
 +==== Interrogation du web service ==== 
 + 
 +Paramètres ''CancelOrderRequest'' : 
 + 
 +^glnReseller    | Votre code d'accès | Obligatoire, numérique, 13 caractères       | 
 +^passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | 
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       | 
 +^orderId  |La référence de commande à annuler| Obligatoire, alphanumérique, max 16 caractères             | 
 +^reason  | La raison d'annulation| Facultatif, chaine de caractères           | 
 +^cancelOrderLines[]    | Liste d'éléments ''cancelOrderLine'' spécifiant les  lignes de commande à annuler  | Obligatoire   //(cf ci-dessous)//   | 
 + 
 +Les éléments ''cancelOrderLine'' devront contenir les paramètres suivants :  
 + 
 +^ ean13    | EAN13 du livre à annuler| Obligatoire, numérique, 13 caractères        | 
 +^ glnDistributor  | Distributeur du livre  | Obligatoire, numérique, 13 caractères              | 
 + 
 +=> [[examples_soap#interrogation_du_web_service2|Exemple SOAP]] 
 + 
 + 
 + 
 +=> [[examples_api_json#interrogation_du_web_service2|Exemple REST]] 
 + 
 + 
 +==== Réponse du web service ==== 
 +Réponse ''CancelOrderResponse'' :  
 +^orderId  |La référence de commande à annuler| Facultatif, alphanumérique, max 16 caractères             | 
 +^ cancelOrderResponseLine[]  | Liste des lignes de commande à annuler|Facultatif, //cf. ci-dessous // |  
 +^ returnStatus  | Statut de la réponse |Obligatoire, //cf. [[:start#codes_de_retour_returnstatus|Codes de retour]] // | 
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif | 
 + 
 +Éléments ''cancelOrderResponseLine'' :  
 +^ ean13    | EAN13 du livre          |Facultatif, Numérique, 13 caractères       | 
 +^ glnDistributor  | GLN du distributeur |Facultatif, Numérique, 13 caractères             | 
 +^ returnStatus   | Indique si la ligne commande a été annulée correctement |Obligatoire, //cf. [[hub_principal:start#codes_de_retour_returnstatus|Codes de retour]] // | 
 +^ returnMessage   |Message d'erreur   | Facultatif, Non défini si ''returnStatus'' est ''CANCELLED''| 
 + 
 +=> [[examples_soap#reponse_du_web_service2|Exemple SOAP]]
=> [[examples_api_json#reponse_du_web_service2|Exemple REST]] => [[examples_api_json#reponse_du_web_service2|Exemple REST]]
 +
 +
 +
Ligne 334: Ligne 378:
==== Interrogation du web service ==== ==== Interrogation du web service ====
-Le revendeur doit fournir son GLN, son mot de passe et la référence de sa commande.+Le revendeur doit fournir son code d'accès, son mot de passe et la référence de sa commande.
Paramètre  ''GetOrderDetailRequest'' : Paramètre  ''GetOrderDetailRequest'' :
-^glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       |+^glnReseller    | Votre code d'accès  | Obligatoire, numérique, 13 caractères       |
^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | ^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
^ orderId  |Numéro de commande dans votre référentiel de commandes. |Obligatoire, alphanumérique, max 16 caractères  | ^ orderId  |Numéro de commande dans votre référentiel de commandes. |Obligatoire, alphanumérique, max 16 caractères  |
- +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       | 
-=> [[examples_soap#interrogation_du_web_service4|Exemple SOAP]]+=> [[examples_soap#interrogation_du_web_service3|Exemple SOAP]]
Ligne 352: Ligne 396:
Réponse GetOrderDetailResponse : Réponse GetOrderDetailResponse :
-^ orderId  | Identifiant de la commande dans votre référentiel | Alphanumérique, max 16 caractères.| +^requestId  | Identifiant de la requête | Facultatif, alphanumérique | 
-^ orderLine[]  | //Liste des éléments commandés | //CF. ci-dessous | | +^ orderId  | Identifiant de la commande dans votre référentiel |Facultatif  , Alphanumérique, max 16 caractères.| 
-^ returnStatus  | Indique si la requête (getOrderDetail) a été effectuée correctement |  | +^ orderLine[]  | //Liste des éléments commandés | //CF. ci-dessous |Facultatif  
 +^ returnStatus  | Indique si la requête (getOrderDetail) a été effectuée correctement |Obligatoire
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
Éléments ''orderLine'' : Éléments ''orderLine'' :
-^ ean13  | EAN13 de l'élément commandé| Numérique, 13 caractères.| +^ ean13  | EAN13 de l'élément commandé| Obligatoire, Numérique, 13 caractères.| 
-^ glnDistributor   | Distributeur de l'élément commandé| Numérique, 13 caractères.+^ glnDistributor   | Distributeur de l'élément commandé|Obligatoire,  Numérique, 13 caractères.| 
-^ link[]  | Liens associé au produit commandé.| +^ orderLineId  | Id unique de la ligne de commande dans le référentiel du HUB.|Obligatoire
-^ orderLineId  | Id unique de la ligne de commande dans le référentiel du HUB.| | +^ lineReference  |Référence ligne dans votre référentiel. |Obligatoire
-^ lineReference  |Référence ligne dans votre référentiel. |  | +^currency  | Devise utilisée pour le prix. |Facultatif, [[http://www.iso.org/iso/fr/home/standards/currency_codes.htm|ISO 4217(Liste 96 Onix)]] | 
-^ returnStatus   | Indique si la ligne commande a été transmise correctement | //cf. [[:start#codes_de_retour_returnstatus|Codes de retour]] // | +^ link[]  | Liens associé au produit commandé.| Facultatif
-^ returnMessage   | Indique la cause d'erreur en cas de ''returnStatus'' différent de ''OK''  | Non défini si ''returnStatus'' est ''OK''|+^ returnStatus   | Indique si la ligne commande a été transmise correctement | Obligatoire  , //cf.[[hub_principal:start#codes_de_retour_returnstatus|Codes de retour]] // | 
 +^ returnMessage   | Indique la cause d'erreur en cas de ''returnStatus'' différent de ''OK''  | Facultatif, Non défini si ''returnStatus'' est ''OK''|
Éléments ''link'' : Éléments ''link'' :
-^ url  | Url du lien | | +^ url  | Url du lien |Facultatif  
-^ format  | Type de format | Format du fichier lié, utilise le code ONIX ProductForm (cf {{:onix-codelist-175.xls|liste 175}}  de la spec ONIX 3.0). Non défini si le format est inconnu | +^ format  | Type de format | Obligatoire, Format du fichier lié, utilise le code ONIX ProductForm (cf {{:onix-codelist-175.xls|liste 175}}  de la spec ONIX 3.0). Non défini si le format est inconnu | 
-^ formatDescription  | Description rapide du format | +^ formatDescription  | Description rapide du format |Obligatoire
-^ mimeType  | Lorsqu'il est disponible le type mime du fichier lié | Non défini si inconnu +^ ean13  | Lorsque l'on est dans le cas d'un multi produit, indiquer l'EAN13 du composé lorsque l'information est disponible, sinon l'EAN13 du produit principal. | Obligatoire | 
-^ ean13  | Lorsque l'on est dans le cas d'un multi produit, indiquer l'EAN13 du composé lorsque l'information est disponible, sinon l'EAN13 du produit principal. |  |+^ mimeType | Lorsqu'il est disponible le type mime du fichier lié |Facultatif |
-=> [[examples_soap#reponse_du_web_service4|Exemple SOAP]]+=> [[examples_soap#reponse_du_web_service3|Exemple SOAP]]
Ligne 387: Ligne 433:
==== Interrogation du web service ==== ==== Interrogation du web service ====
-Le revendeur doit fournir son GLN, son mot de passe ainsi que la liste des EAN13 physiques dont il souhaite obtenir les équivalents numériques.+Le revendeur doit fournir son code d'accès, son mot de passe ainsi que la liste des EAN13 physiques dont il souhaite obtenir les équivalents numériques.
Paramètre ''GetDigitalVersionsRequest'' : Paramètre ''GetDigitalVersionsRequest'' :
-^ glnReseller    | Votre GLN         | Obligatoire, numérique, 13 caractères       |+^ glnReseller    | Votre code d'accès         | Obligatoire, numérique, 13 caractères       |
^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | ^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
^ physicalEan[]    | Liste des EAN13 physiques   | Obligatoire, 12 EAN13 maximum   | ^ physicalEan[]    | Liste des EAN13 physiques   | Obligatoire, 12 EAN13 maximum   |
-=> [[examples_soap#interrogation_du_web_service5|Exemple SOAP]]+=> [[examples_soap#interrogation_du_web_service4|Exemple SOAP]]
Ligne 405: Ligne 452:
==== Réponse du web service ==== ==== Réponse du web service ====
Réponse ''GetDigitalVersionsResponse'' : Réponse ''GetDigitalVersionsResponse'' :
-^ physicalVersion[]  | Listes des correspondances pour chaque EAN13 physique| //cf. ci-dessous // |  +^requestId  | Identifiant de la requête | Facultatif, alphanumérique | 
-^ returnStatus  | Statut de la réponse |//cf. [[:start#codes_de_retour_returnstatus|Codes de retour]] // |+^ physicalVersion[]  | Listes des correspondances pour chaque EAN13 physique|Facultatif,  //cf. ci-dessous // |  
 +^ returnStatus  | Statut de la réponse |Obligatoire, //cf. [[hub_principal:start#codes_de_retour_returnstatus|Codes de retour]] //
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
Éléments ''physicalVersion'' : Éléments ''physicalVersion'' :
-^ physicalEan    | EAN13 du livre physique         | Numérique, 13 caractères       | +^ physicalEan    | EAN13 du livre physique         | Obligatoire, Numérique, 13 caractères       | 
-^ digitalVersion[]  | Liste d'identifiants des livres numériques associés. Si aucune version numérique n'est disponible pour cet EAN un élément <noDigitalVersion/> est retourné.| //cf. ci-dessous //              | +^ digitalVersion[]  | Liste d'identifiants des livres numériques associés. Si aucune version numérique n'est disponible pour cet EAN un élément <noDigitalVersion/> est retourné.|Facultatif, //cf. ci-dessous //              | 
-^ noDigitalVersion  | Retourné uniquement lorsque aucun livre numérique ne correspond à cet EAN13 physique | |+^ noDigitalVersion  | Retourné uniquement lorsque aucun livre numérique ne correspond à cet EAN13 physique |Facultatif  |
Éléments ''digitalVersion'' : Éléments ''digitalVersion'' :
-^ ean13  | EAN13 du livre numérique  | Numérique, 13 caractères       | +^ ean13  | EAN13 du livre numérique  |Obligatoire, Numérique, 13 caractères       | 
-^ glnDistributor  | GLN distributeur du livre numérique   | Numérique, 13 caractères       |+^ glnDistributor  | GLN distributeur du livre numérique   |Obligatoire, Numérique, 13 caractères       |
-=> [[examples_soap#reponse_du_web_service5|Exemple SOAP]]+=> [[examples_soap#reponse_du_web_service4|Exemple SOAP]]
-=> [[examples_api_json#reponse_du_web_service5|Exemple REST]]+=> [[examples_api_json#reponse_du_web_service4|Exemple REST]]
 +===== Récupération des notices : getNotices() =====
 +Ce service permet aux clients de synchroniser leurs catalogues HUB.
 +
 +==== Horaires de mise à disposition ====
 +Les mises à jour catalogue sont mises à disposition sur le HUB chaque matin entre 5h55 et 9h environ, en fonction du nombre de mises à jour déposées par les plateformes, à l'exception des mises à jour de la plateforme Interforum Editis qui sont mises à disposition entre 22h50 et 23h30.
 +
 +Il est recommandé de récupérer les mises à jour au moins quotidiennement, et si possible plusieurs fois par jour en utilisant le paramètre "LastConnection" ( [[hub_principal:start#cas_3_recuperation_depuis_la_derniere_connexion|voir Cas 3 – Récupération depuis la dernière connexion]]).
 +
 +==== EAN13 ====
 +Un EAN 13 n'est pas forcément unique dans la base de donnée Hub Dilicom, un même article pouvant être distribué par plusieurs plateformes.
 +Cependant le couple EAN13/GLN Supplier sera toujours unique.
 +
 +==== Interrogation du web service ====
 +=== Paramètres communs ===
 +Le revendeur a trois possibilités pour interroger ce service. Cependant il existe des informations communes pour ces trois messages.
 +Il doit nous fournir son code d'accès, son mot de passe et éventuellement un GLN de groupe. Pour la suite, il a donc le choix entre les 3 cas suivants:
 +
 +=== Cas 1 – Initialisation du catalogue (service désactivé) ===
 +Pour préciser un tel choix vous devez indiquer le paramètre ''initialization'' sans contenu particulier.
 +^ glnReseller    | Votre code d'accès          | Obligatoire, numérique, 13 caractères       |
 +^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^ glnGroup  |GLN de groupe  | Facultatif ,  numérique, 13 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^ initialization    | Indique une demande d'initialisation du catalogue        | Obligatoire, chaîne vide (non null)      |
 + => [[examples_soap#cas_1_initialisation_du_catalogue_service_desactive_le_catalogue_d_initialisation_est_fourni_par_ftp|Exemple SOAP]]
 + 
 +
 +
 +
 +
 +
 +=> [[examples_api_json#cas_1_initialisation_du_catalogue_service_desactive_le_catalogue_d_initialisation_est_fourni_par_ftp|Exemple REST]]
 +
 +Ce service a été désactivé, les catalogues complets sont mis à disposition à la demande sur un compte FTP.
 +
 +<note important>
 +Attention : l'option initialization a été désactivée, merci de contacter Dilicom pour plus d’informations.
 +</note>
 +
 +=== Cas 2 – Récupération depuis une date donnée ===
 +Ici, c’est le paramètre ''sinceDate'' contenant la date souhaitée qui doit être présent. Cette fonctionnalité est limitée à une période de 8 jours.
 +^ glnReseller    | Votre code d'accès          | Obligatoire, numérique, 13 caractères       |
 +^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^ glnGroup  |GLN de groupe  | Facultatif ,  numérique, 13 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^ sinceDate    | Récupération des notices publiées depuis cette date.      | Obligatoire, au format ISO 8601  (AAAA-MM-JJTHH:MM:SS), ne doit pas être antérieur à 8 jours.         |
 +=> [[examples_soap#cas_2_recuperation_depuis_un_instant_t|Exemple SOAP]]
 +
 +
 +
 +=> [[examples_api_json#cas_2_-_recuperation_depuis_un_instant_t|Exemple REST]]
 +
 +=== Cas 3 – Récupération depuis la dernière connexion ===
 +Ici, c’est le paramètre ''lastConnection'' qui doit être présent. Il ne nécessite pas de contenu.
 +^ glnReseller    | Votre code d'accès | Obligatoire, numérique, 13 caractères       |
 +^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^ glnGroup  |GLN de groupe  | Facultatif ,  numérique, 13 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^ lastConnection    | Indique une récupération des fiches publiées depuis la dernière connexion       | Obligatoire, chaine vide (non null)     |
 +=> [[examples_soap#cas_3_recuperation_depuis_la_derniere_connexion|Exemple SOAP]]
 +
 +
 +
 +=> [[examples_api_json#cas_3_-_recuperation_depuis_la_derniere_connexion|Exemple REST]]
 +
 +<note important>Attention : Pour utiliser l'option 'lastConnection' il est nécessaire de s'être connecté au moins une fois avec le paramètre 'SinceDate' au préalable, afin que le serveur puisse dater la dernière connexion.</note>
 +<note important>Si la dernière connexion s'est produite plus de 8 jours avant la date de la requête, le fichier de mise à jour ne pourra pas être fourni.</note>
 +<note important>Actuellement au maximum 5 appels de l'option 'lastConnection" sont autorisés par période de 24h.</note>
 +
 +==== Réponse du Web Service ====
 +
 +Réponse ''GetNoticesResponse'' :
 +^requestId  | Identifiant de la requête | Facultatif, alphanumérique |
 +^returnStatus  | ''OK'' indique que l'appel au service s'est bien passé.|Obligatoire |
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
 +^onixFileUrl[]  | Liste d'éléments onixFileUrl pour les notices correspondant à la requête. |Facultatif , //cf. ci-dessous// |
 +^noNotice  | Indique qu'il n'y a aucune fiche à diffuser. Si cet élément est présent alors la réponse ne comporte pas d'éléments onixFileUrl |Facultatif, Chaine vide (non null) |
 +
 +Éléments ''onixFileUrl'' :
 +
 +^ httpLink  | Lien http vers un fichier ONIX |
 +
 +Le réponse du web service en cas de succès comporte un élément ''returnStatus'' positionné a 'OK' ainsi qu'une liste d'éléments du type ''onixFileUrl'' Chaque élément ''onixFileUrl'' contenant lui même l'url http d'un fichier ONIX :''httpLink''.   (ces liens http seront prochainement accompagnés de liens ftp)
 +Si éventuellement il n’y avait aucune fiche à diffuser, on renvoie un message contenant ''returnStatus'' positioné à ''OK'', ainsi qu'un élément ''noNotice'' vide (mais non null).
 +
 +<note>
 +Les liens retournés pointent vers des fichier XML content les notices ONIX. Vous devez donc, suite à l'appel du web service, télécharger le ou les liens proposés afin d'en intégrer le contenu dans votre base.
 +</note>
 +<note important>
 +Actuellement le web service renvoie toujours un seul lien, cependant il est possible qu'à terme il soit nécessaire de renvoyer plusieurs liens et le cas est donc prévu.
 +</note>
 +<note important>
 +Lors de grosses mises à jour le temps de réponse de ce service peut être de l'ordre de 5 minutes. Il est donc conseillé d'augmenter la valeur de timeout de cette méthode (par exemple 10 minutes).
 +</note>
 +
 +<note important>
 +Les liens de téléchargement sont accessibles pendant 10 jours sur le serveur HUB.
 +</note>
 +
 +=> [[examples_soap#reponse_du_web_service5|Exemples SOAP]]
 +
 +
 +
 +=> [[examples_api_json#reponse_du_web_service5|Exemples REST]]
 +
 +===== Récupération des notices pour un seul distributeur : getNoticesForDistributor() =====
 +Ce service permet de synchroniser le catalogue HUB spécifique d'un distributeur.
 +<note important> Ce service est disponible uniquement en version SOAP, la version REST n'est pas encore implémentée. </note>
 +
 +==== Interrogation du web service ====
 +=== Paramètres communs ===
 +Le revendeur a trois possibilités pour interroger ce service. Cependant il existe des informations communes pour ces trois messages.
 +Il doit nous fournir son code d'accès, son mot de passe et éventuellement un GLN de groupe. Pour la suite, il a donc le choix entre les 3 cas suivants:
 +
 +=== Cas 1 – Initialisation du catalogue (service désactivé) ===
 +Pour préciser un tel choix vous devez indiquer le paramètre ''initialization'' sans contenu particulier.
 +^ glnReseller    | Votre code d'accès          | Obligatoire, numérique, 13 caractères       |
 +^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^ glnDistributor  | Gln du distributeur dont on veut obtenir le catalogue | Obligatoire, numérique, 13 caractères              |
 +^ glnGroup  |GLN de groupe  | Facultatif ,  numérique, 13 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^ initialization    | Indique une demande d'initialisation du catalogue        | Obligatoire, chaîne vide (non null)      |
 + => [[examples_soap#cas_1_initialisation_du_catalogue_pour_un_distributeur_service_desactive_le_catalogue_d_initialisation_est_fourni_par_ftp|Exemple SOAP]]
 +
 +<note important>Attention : l'option initialization a été désactivée, merci de contacter Dilicom pour plus d’informations.</note>
 + 
 +
 +
 +
 +
 +
 +=== Cas 2 – Récupération depuis une date donnée ===
 +Ici, c’est le paramètre ''sinceDate'' contenant la date souhaitée qui doit être présent.
 +^ glnReseller    | Votre code d'accès | Obligatoire, numérique, 13 caractères       |
 +^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^ glnDistributor  | Gln du distributeur dont on veut obtenir le catalogue | Obligatoire, numérique, 13 caractères              |
 +^ glnGroup  |GLN de groupe  | Facultatif ,  numérique, 13 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^ sinceDate    | Récupération des notices publiées depuis cette date       | Obligatoire, au format ISO 8601  (AAAA-MM-JJTHH:MM:SS)         |
 +=> [[examples_soap#cas_2_recuperation_depuis_un_instant_t_pour_un_distributeur|Exemple SOAP]]
 +
 +==== Réponse du Web Service ====
 +
 +Réponse ''GetNoticesResponse'' :
 +^requestId  | Identifiant de la requête | Facultatif, alphanumérique |
 +^returnStatus  | ''OK'' indique que l'appel au service s'est bien passé.|Obligatoire |
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
 +^onixFileUrl[]  | Liste d'éléments onixFileUrl pour les notices correspondant à la requête. |Facultatif, //cf. ci-dessous// |
 +^noNotice  | Indique qu'il n'y a aucune fiche à diffuser. Si cet élément est présent alors la réponse ne comporte pas d'éléments onixFileUrl |Facultatif, Chaine vide (non null) |
 +
 +Éléments ''onixFileUrl'' :
 +
 +^ httpLink  | Lien http vers un fichier ONIX |
 +
 +Le réponse du web service en cas de succès comporte un élément ''returnStatus'' positionné a 'OK' ainsi qu'une liste d'éléments du type ''onixFileUrl''. Chaque élément ''onixFileUrl'' contenant lui même l'url http d'un fichier ONIX :''httpLink''.   (ces liens http seront prochainement accompagnés de liens ftp)
 +Si éventuellement il n’y avait aucune fiche à diffuser, on renvoie un message contenant ''returnStatus'' positioné à OK, ainsi qu'un élément ''noNotice'' vide (mais non null).
 +
 +<note>
 +Les liens retournés pointent vers des fichier XML contenant les notices ONIX. Vous devez donc, suite à l'appel du web service, télécharger le ou les liens proposés afin d'en intégrer le contenu dans votre base.
 +</note>
 +
 +<note important>
 +Les liens de téléchargement sont accessibles pendant 10 jours sur le serveur HUB.
 +</note>
 +=> [[examples_soap#reponse_du_web_service6|Exemples SOAP]]
===== Obtention de notices ONIX d'une liste d'EAN13/distributeur  : getDetailNotices() ===== ===== Obtention de notices ONIX d'une liste d'EAN13/distributeur  : getDetailNotices() =====
-Ce service permet aux revendeurs de récupérer les notices ONIX d’un ou plusieurs livres numériques, à partir de leurs identifiants (EAN13, GLN distributeur).+Ce service permet aux revendeurs de récupérer les notices ONIX(la notice ONIX est encapsulée dans un champ <![CDATA[...]]) d’un ou plusieurs livres numériques, à partir de leurs identifiants (EAN13, GLN distributeur).
<note tip> <note tip>
Ligne 436: Ligne 650:
-Le revendeur doit fournir son GLN, son mot de passe ainsi que la liste d’articles dont il souhaite obtenir les notices. Chaque ligne contient l’EAN13 et le GLN. +Le revendeur doit fournir son code d'accès, son mot de passe ainsi que la liste d’articles dont il souhaite obtenir les notices. Chaque ligne contient l’EAN13 et le GLN.
Paramètre ''GetDetailNoticesRequest'' : Paramètre ''GetDetailNoticesRequest'' :
-^ glnReseller    | Votre GLN          | Obligatoire, numérique, 13 caractères       |+^ glnReseller    | Votre code d'accès | Obligatoire, numérique, 13 caractères       |
^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            | ^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
-^ notice[]    | Liste d'éléments ''notice'' spécifiant les  notices à retourner  | Obligatoire   //(cf ci dessous)//   |+^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       | 
 +^ notice[]    | Liste d'éléments ''notice'' spécifiant les  notices à retourner  | Obligatoire   //(cf ci dessous)//, max 12 éléments  |
Les éléments ''notice'' devront contenir les paramètres suivants : Les éléments ''notice'' devront contenir les paramètres suivants :
Ligne 449: Ligne 664:
^ glnDistributor  | Distributeur du livre à vérifier | Obligatoire, numérique, 13 caractères              | ^ glnDistributor  | Distributeur du livre à vérifier | Obligatoire, numérique, 13 caractères              |
-=> [[examples_soap#interrogation_du_web_service6|Exemple SOAP]]+=> [[examples_soap#interrogation_du_web_service7|Exemple SOAP]]
-=> [[examples_api_json#interrogation_du_web_service5|Exemple REST]]+=> [[examples_api_json#interrogation_du_web_service6|Exemple REST]]
==== Réponse du web service ==== ==== Réponse du web service ====
Réponse ''GetDetailNoticesResponse'' : Réponse ''GetDetailNoticesResponse'' :
 +^requestId  | Identifiant de la requête | Facultatif, alphanumérique |
^ detailNotice[]  | Liste des notices demandées| //cf. ci-dessous // | ^ detailNotice[]  | Liste des notices demandées| //cf. ci-dessous // |
-^ returnStatus  | Statut de la réponse |//cf. [[:start#codes_de_retour_returnstatus|Codes de retour]] // |+^ returnStatus  | Statut de la réponse |//cf. [[hub_principal:start#codes_de_retour_returnstatus|Codes de retour]]//
 +^returnMessage[]  |Message(s) d'erreur(s) |Facultatif |
Éléments ''detailNotice'' : Éléments ''detailNotice'' :
Ligne 466: Ligne 683:
^ noNotice  | N'est défini que lorsque la notice demandée n'est pas trouvée. | | ^ noNotice  | N'est défini que lorsque la notice demandée n'est pas trouvée. | |
-=> [[examples_soap#reponse_du_web_service6|Exemple SOAP]]+=> [[examples_soap#reponse_du_web_service7|Exemple SOAP]]
-=> [[examples_api_json#reponse_du_web_service5|Exemple REST]]+=> [[examples_api_json#reponse_du_web_service6|Exemple REST]]
 +
 +===== Chargement de la notices d'un produit directement au format ONIX : getNotice() =====
 +Ce service permet de récupérer directement la notice ONIX.
 +<note tip>Service disponible uniquement en version REST</note>
 +
 +==== Interrogation du web service ====
 +
 +
 +
 +
 +Les paramètres paramètres :
 +
 +^ glnReseller    | Votre code d'accès | Obligatoire, numérique, 13 caractères       |
 +^ passwordReseller  | Votre mot de passe | Obligatoire, alphanumérique, max 25 caractères            |
 +^glnContractor  |Gln du prestatataire| Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 caractères       |
 +^ ean13    | EAN13           | Obligatoire, numérique, 13 caractères        |
 +^ glnDistributor  | GLN Distributeur| Obligatoire, numérique, 13 caractères              |
 +
 +
 +
 +
 +
 +=> [[examples_api_json#interrogation_du_web_service6|Exemple REST]]
 +
 +==== Réponse du web service ====
 +Ce service ne retourne pas du JSON mais directement un message ONIX, donc au format XML.
 +=> [[examples_api_json#reponse_du_web_service7|Exemple REST]]