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 :
  • 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.

Le catalogue complet (initialisation) est mis à disposition sur un compte FTP lorsque nécessaire.

• 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,
  • Commander les livres,
  • Récupérer les liens pour les livres commandés.

• La vérification du chaînage se déroule en 2 étapes
  • Vérifier le chaînage entre livre physique et 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)

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 :

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique/[nom de service]

Version SOAP : le WSDL est disponible via l'URL suivant :

• plateforme de test: https://hub-test.centprod.com/v[ numéro de version ]/hub-numerique/hub-numerique-services.wsdl
• plateforme de production: https://hub-dilicom.centprod.com/v[ 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

Version REST : les différents services sont disponibles aux URL suivantes :

• plateforme de test: https://hub-test.centprod.com/v[ numéro de version ]/hub-numerique-api/json/[nom de service]
• plateforme de production: https://hub-dilicom.centprod.com/v[ numéro de version ]/hub-numerique-api/json/[nom de service]

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.

• En Rest vous devez fournir vos éléments d'authentification en utilisant l'authentification HTTP Basic.
• En Soap vous devez renseigner les deux éléments glnReseller et passwordReseller :

  <xxxxRequest>
  	<glnReseller>3026900001000</glnReseller>
  	<passwordReseller>3x59ftmdmdEds</passwordReseller>
  	...
  </xxxxRequest>

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 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.

• Exemple SOAP :

  <xxxxResponse>
  	<returnStatus>AUTHENTICATION_ERROR</returnStatus>
  	<returnMessage>Bad login</returnMessage >
  </xxxxResponse>

• Exemple REST :

  {
  	returnStatus:"INVALID_ARGUMENTS",
  	returnMessage:["The content of element getNotices request is not complete. A valid 'sinceDate', 'lastConnection' or 'initialization' parameter is expected."]
  }

Les codes de retours HUB sont résumés dans le tableau ci-dessous:

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.

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 :

Les éléments checkAvailabilityLine devront contenir les paramètres suivants :

⇒ Exemple REST

Réponse CheckAvailabilityResponse :

Éléments checkAvailabilityResponseLine :

⇒ Exemple REST

Ce service permet aux revendeurs de passer une commande après vérification de celle-ci.

Paramètre SendOrderRequest :

Element finalBookOwner :

Elements orderRequestLine :

⇒ Exemple SOAP

⇒ Exemple REST

En réponse, le revendeur reçoit le statut de la commande pour chacun des articles contenus dans la requête.

Réponse SendOrderResponse :

Éléments orderLine :

Éléments link :

⇒ Exemple SOAP

⇒ Exemple REST

Ce service permet aux revendeurs l'annulation complète ou partielle d'une commande.

Paramètres CancelOrderRequest :

Les éléments cancelOrderLine devront contenir les paramètres suivants :

⇒ Exemple SOAP

⇒ Exemple REST

Réponse CancelOrderResponse :

Éléments cancelOrderResponseLine :

⇒ Exemple SOAP

⇒ Exemple REST

Ce service permet aux libraires-revendeurs de récupérer le détail d'une commande qu'ils ont effectuée via le hub. Cette méthode permet en particulier de récupérer les liens vers les livres numériques.

Le revendeur doit fournir son code d'accès, son mot de passe et la référence de sa commande.

Paramètre GetOrderDetailRequest :

⇒ Exemple SOAP

⇒ Exemple REST

En réponse, le revendeur reçoit le détail de la commande d'une façon similaire à la réponse du service sendOrder.

Réponse GetOrderDetailResponse :

Éléments orderLine :

Éléments link :

⇒ Exemple SOAP

⇒ Exemple REST

Ce service permet aux libraires-revendeurs de récupérer les identifiants des livres numériques associés à un ou plusieurs EAN13 physiques.

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 :

⇒ Exemple SOAP

⇒ Exemple REST

Réponse GetDigitalVersionsResponse :

Éléments physicalVersion :

Éléments digitalVersion :

⇒ Exemple SOAP

⇒ Exemple REST

Ce service permet aux clients de synchroniser leurs catalogues HUB.

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 – Récupération depuis la dernière connexion).

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.

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:

Pour préciser un tel choix vous devez indiquer le paramètre initialization sans contenu particulier.

⇒ Exemple SOAP

⇒ Exemple REST

Ce service a été désactivé, les catalogues complets sont mis à disposition à la demande sur un compte FTP.

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.

⇒ Exemple SOAP

⇒ Exemple REST

Ici, c’est le paramètre lastConnection qui doit être présent. Il ne nécessite pas de contenu.

⇒ Exemple SOAP

⇒ Exemple REST

Réponse GetNoticesResponse :

Éléments onixFileUrl :

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).

⇒ Exemples SOAP

⇒ Exemples REST

Ce service permet de synchroniser le catalogue HUB spécifique d'un distributeur.

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:

Pour préciser un tel choix vous devez indiquer le paramètre initialization sans contenu particulier.

⇒ Exemple SOAP

Ici, c’est le paramètre sinceDate contenant la date souhaitée qui doit être présent.

⇒ Exemple SOAP

Réponse GetNoticesResponse :

Éléments onixFileUrl :

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).

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).

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 :

Les éléments notice devront contenir les paramètres suivants :

⇒ Exemple SOAP

⇒ Exemple REST

Réponse GetDetailNoticesResponse :

Éléments detailNotice :

⇒ Exemple SOAP

⇒ Exemple REST

Ce service permet de récupérer directement la notice ONIX.

Les paramètres paramètres :

⇒ Exemple REST

Ce service ne retourne pas du JSON mais directement un message ONIX, donc au format XML.

⇒ Exemple REST