Ceci est une ancienne révision du document !

Table des matières

HUB Numérique : API Principale

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.

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

Rappel : Les Web services sont disponible dans deux version : SOAP et REST(html+json)

Version SOAP

Les WSDL des deux plateformes sont :

⇒ Voir les exemples soap

Version REST (http+json)

Cette API donne accès aux mêmes fonctionnalités que le web service SOAP. Cependant celle-ci utilise, suivant le principe REST, de simples requêtes Http et renvoie ses réponses sous forme de simples objets 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 JSON et de requêtage Http dans tous les principaux langages de programmation web (python, php, ..).

Les urls a utiliser sur les deux plateformes seront du type :

⇒ Voir les exemples REST

Description de l'API

Récupération des notices : getNotices()

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

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 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
initialization Indique une demande d'initialisation du catalogue Obligatoire, chaîne vide (non null)

⇒ Exemple SOAP

⇒ Exemple REST

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

Attention : l'option initialization a été désactivée, merci de contacter Dilicom pour plus d’informations.

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

⇒ Exemple SOAP

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

⇒ Exemple SOAP

⇒ Exemple REST

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.

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.

Actuellement au maximum 5 appels de l'option 'lastConnection” sont autorisés par période de 24h.

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

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.

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.

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

⇒ Exemples SOAP

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

⇒ Exemple SOAP

Attention : l'option initialization a été désactivée, merci de contacter Dilicom pour plus d’informations.

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)

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

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.

⇒ Exemples SOAP

Vérification des disponibilités : checkAvailability()

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

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é :

Paramètre CheckAvailabilityRequest :

glnReseller Votre GLN Obligatoire, numérique, 13 caractères
passwordReseller Votre mot de passe Obligatoire, alphanumérique, max 25 caractères
checkAvailabilityLine[] Liste d'éléments checkAvailabilityLine spécifiant les disponibilités à vérifier Obligatoire (cf ci-dessous)

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

ean13 EAN13 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

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.

⇒ Exemple SOAP

⇒ Exemple REST

Réponse du web service

Réponse CheckAvailabilityResponse :

checkAvailabilityResponseLine[] Liste des éléments à vérifier cf. ci-dessous
returnStatus Statut de la réponse cf. Codes de retour

Éléments checkAvailabilityResponseLine :

ean13 EAN13 du livre Numérique, 13 caractères
glnDistributor GLN du distributeur Numérique, 13 caractères
checkAvailabilityReturnValue Disponibilité du livre
  • AVAILABLE :disponible
  • UNAVAILABLE : non disponible
  • NOT_KNOWN : Ne sait pas – cas des distributeurs qui ne stockent pas leurs notices sur le Hub

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

⇒ Exemple SOAP

⇒ Exemple REST

Passage de commandes : sendOrder()

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

Interrogation du web service

Paramètre SendOrderRequest :

glnReseller Votre GLN Obligatoire, numérique, 13 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
glnGroup GLN groupe. Facultatif, numérique, 13 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
orderRequestLine[] Liste de lignes de commandesObligatoire, Cf. ci-dessous

Element finalBookOwner :

identifier Identifiant du destinataire final dans votre référentiel Obligatoire,alphanumérique, max 35 caractères
civility Civilité du destinataire final Obligatoire
  • M
  • MME
  • MLE
firstName Pré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
country Pays du destinataire final. Obligatoire, exemple : FR
postalCode Code postal destinataire final. Obligatoire, exemple : 94120, max 35 caractères
city Ville du destinataire final. Obligatoire, max 35 caractères

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

Elements orderRequestLine :

ean13 EAN13 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
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

Le prix est donné en centimes (12,50€ sera renseigné sous la forme 1250).

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.

En production, il ne faut pas utiliser la même adresse mail pour deux clients différents!! C'est-à-dire que pour un même GLN reseller, on ne peut pas utiliser deux fois la même adresse email pour deux customer_id différents. (Note : il n'est pas possible non plus, d'utiliser plusieurs adresses mails pour un même Customer_id)

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.

⇒ Exemple SOAP

⇒ Exemple REST

Réponse du web service

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

Réponse SendOrderResponse :

orderId Identifiant de la commande dans votre référentiel Alphanumérique, max 16 caractères.
orderLine[] Liste des éléments commandés cf. ci-dessous
returnStatus Indique si la commande a été effectuée correctement
  • OK : Toute la commande a été transmise correctement.
  • WARNING : Une ou plusieurs lignes de commande n'ont pas pu être transmises correctement. Certaines lignes ont été expédiées correctement
  • ERROR : Une erreur est survenue durant la commande, aucune ligne n'a été expédiée.

Éléments orderLine :

ean13 EAN13 de l'élément commandé Numérique, 13 caractères.
glnDistributor Distributeur du produit commandé 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.
lineReference Référence ligne dans votre référenciel.
returnStatus Indique si la ligne commande a été transmise correctement cf. Codes de retour
returnMessage Indique la cause d'erreur en cas de returnStatus différant de OK Non défini si returnStatus est OK

Éléments link :

url Url du lien
format Type de format Format du fichier lié, utilise le code ONIX ProductForm (cf liste 175 de la notice ONIX 3.0). Non défini si le format est inconnu.
formatDescription Description rapide du format
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. Pour le moment nous indiquons toujours l'ean principal

⇒ Exemple SOAP

⇒ Exemple REST

Récupération des détails d'une commande : getOrderDetail()

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.

Interrogation du web service

Le revendeur doit fournir son GLN, son mot de passe et la référence de sa commande.

Paramètre GetOrderDetailRequest :

glnReseller Votre GLN Obligatoire, numérique, 13 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

⇒ Exemple SOAP

⇒ Exemple REST

Réponse du web service

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 :

orderId Identifiant de la commande dans votre référentiel Alphanumérique, max 16 caractères.
orderLine[] Liste des éléments commandés | CF. ci-dessous
returnStatus Indique si la requête (getOrderDetail) a été effectuée correctement

Éléments orderLine :

ean13 EAN13 de l'élément commandé Numérique, 13 caractères.
glnDistributor Distributeur de l'élément commandé 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.
lineReference Référence ligne dans votre référentiel.
returnStatus Indique si la ligne commande a été transmise correctement cf. Codes de retour
returnMessage Indique la cause d'erreur en cas de returnStatus différent de OK Non défini si returnStatus est OK

Éléments link :

url Url du lien
format Type de format Format du fichier lié, utilise le code ONIX ProductForm (cf liste 175 de la spec ONIX 3.0). Non défini si le format est inconnu
formatDescription Description rapide du format
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.

⇒ Exemple SOAP

⇒ Exemple REST

Obtention des versions numériques associées à des EAN13 physiques : getDigitalVersions()

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

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.

Paramètre GetDigitalVersionsRequest :

glnReseller Votre GLN Obligatoire, numérique, 13 caractères
passwordReseller Votre mot de passe Obligatoire, alphanumérique, max 25 caractères
physicalEan[] Liste des EAN13 physiques Obligatoire, 12 EAN13 maximum

⇒ Exemple SOAP

⇒ Exemple REST

Réponse du web service

Réponse GetDigitalVersionsResponse :

physicalVersion[] Listes des correspondances pour chaque EAN13 physique cf. ci-dessous
returnStatus Statut de la réponse cf. Codes de retour

Éléments physicalVersion :

physicalEan EAN13 du livre physique 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
noDigitalVersion Retourné uniquement lorsque aucun livre numérique ne correspond à cet EAN13 physique

Éléments digitalVersion :

ean13 EAN13 du livre numérique Numérique, 13 caractères
glnDistributor GLN distributeur du livre numérique Numérique, 13 caractères

⇒ Exemple SOAP

⇒ Exemple REST

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

L'API Rest propose aussi une URL (HTTP) permettant de charger directement la notice ONIX d'un produit sans passer par SOAP ou JSON. Détails

Interrogation du web service

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.

Paramètre GetDetailNoticesRequest :

glnReseller Votre GLN Obligatoire, numérique, 13 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)

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

ean13 EAN13 du livre à vérifier Obligatoire, numérique, 13 caractères
glnDistributor Distributeur du livre à vérifier Obligatoire, numérique, 13 caractères

⇒ Exemple SOAP

⇒ Exemple REST

Réponse du web service

Réponse GetDetailNoticesResponse :

detailNotice[] Liste des notices demandées cf. ci-dessous
returnStatus Statut de la réponse cf. Codes de retour

Éléments detailNotice :

ean13 EAN13 du livre Numérique, 13 caractères
glnDistributor GLN du distributeur Numérique, 13 caractères
onixProduct Chaine de caractères contenant la notice de ce livre numérique au format ONIX 3.0 Si la notice de ce livre n'existe pas une balise <noNotice/> est retournée
noNotice N'est défini que lorsque la notice demandée n'est pas trouvée.

⇒ Exemple SOAP

⇒ Exemple REST