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)

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 :

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

Versions de l'API HUB

Numéro de versionStatutURL WSDLDate de mise en productionDate de désactivation de la versionModifications
1Actifv1 01-06-2010 30-06-2015 historiques de modification v1
2Actifv2 13-01-2014 30-06-2015 historiques de modification v2
3Actifv3 05-02-2015 historiques de modification v3

Adresses de l'API HUB

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

Exemple :

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

Authentification

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

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.

Codes de retour (returnStatus)

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é.
CANCELLEDUne ligne de commande est annulée avec succès.
PRODUCT_NOT_IN_ORDERLa 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.

Description de l'API

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

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
country Pays du revendeur Facultatif, ISO 3166-1 (liste 91 dans Onix)
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
unitPriceExcludingTax Prix unitaire HT utilisé par le revendeur. Exprimé en centimes. Entier non négatif. 1250 = 12,50Facultatif, nombre entier
currency Devise utilisée pour le prix. Conditionnel. Obligatoire dans le cadre des échanges avec Eden. ISO 4217(Liste 96 Onix)

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 :

requestId Identifiant de la requête Facultatif, alphanumérique
checkAvailabilityResponseLine[] Liste des éléments à vérifier Facultatif, cf. ci-dessous
returnStatus Statut de la réponse Obligatoire, cf. Codes de retour
returnMessage[] Message(s) d'erreur(s) Facultatif

Éléments checkAvailabilityResponseLine :

ean13 EAN13 du livre Obligatoire, Numérique, 13 caractères
glnDistributor GLN du distributeur Obligatoire, Numérique, 13 caractères
checkAvailabilityReturnValue Disponibilité du livre Obligatoire,
  • AVAILABLE :disponible
  • UNAVAILABLE : non disponible
  • NOT_KNOWN : Ne sait pas – cas des distributeurs qui ne stockent pas leurs notices sur le Hub
returnStatus Statut de la réponse Obligatoire, cf. Codes de retour
returnMessage[] Message(s) d'erreur(s) Facultatif

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 code d'accès 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
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
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. Facultatif, 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, ISO 3166-1 (liste 91 dans Onix)
postalCode Code postal destinataire final. Obligatoire, exemple : 94120, max 35 caractères
city Ville du destinataire final. Obligatoire, max 35 caractères

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

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
unitPriceExcludingTax Prix unitaire HT utilisé par le revendeur. Exprimé en centimes. Entier non négatif. 1250 = 12,50Conditionnel, nombre entier
currency Devise utilisée pour le prix. Conditionnel. 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

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

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.

À partir du 1er septembre 2016 : Le champ unitPriceExcludingTax doit impérativement être renseigné si la commande concerne un achat sur la plateforme EDITIS.

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 :

requestId Identifiant de la requête Facultatif, alphanumérique
orderId Identifiant de la commande dans votre référentiel Facultatif, Alphanumérique, max 16 caractères.
orderLine[] Liste des éléments commandés Facultatif , cf. ci-dessous
returnStatus Indique si la commande a été effectuée correctement Obligatoire ,
  • 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.
returnMessage[] Message(s) d'erreur(s) Facultatif

Éléments orderLine :

ean13 EAN13 de l'élément commandéObligatoire, Numérique, 13 caractères.
glnDistributor Distributeur du produit commandéObligatoire, Numérique, 13 caractères.
orderLineId Id de la ligne de commande dans le référentiel du HUB.Obligatoire, numérique, 20 caractères
lineReference Référence ligne dans votre référenciel. Obligatoire
currency Devise utilisée pour le prix. Facultatif, ISO 4217(Liste 96 Onix)
link[] Liens associé au produit commandé.Facultatif
returnStatus Indique si la ligne commande a été transmise correctement Obligatoire, cf. 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 :

url Url du lien Facultatif
format Type de format Obligatoire, 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 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. Obligatoire, 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

Exemple SOAP

Exemple REST

Annulation d'une commande : cancelOrder()

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

Ce service n’est pas implémenté pour les distributeurs: IKIOSQUE, HARMATHEQUE, OLF et IZNEO

Les distributeurs qui acceptent l'annulation partielle d'une commande : EDEN et DE MARQUE

Les distributeurs qui n’acceptent pas l’annulation partielle d'une commande : EDITIS , DIALOGUES

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

Exemple SOAP

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 à annulerFacultatif, cf. ci-dessous
returnStatus Statut de la réponse Obligatoire, cf. 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. Codes de retour
returnMessage Message d'erreur Facultatif, Non défini si returnStatus est CANCELLED

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 code d'accès, son mot de passe et la référence de sa commande.

Paramètre GetOrderDetailRequest :

glnReseller Votre code d'accès 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
glnContractor Gln du prestatataire Facultatif jusqu'au 30 juin puis Obligatoire, numérique, 13 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 :

requestId Identifiant de la requête Facultatif, alphanumérique
orderId Identifiant de la commande dans votre référentiel Facultatif , Alphanumérique, max 16 caractères.
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 :

ean13 EAN13 de l'élément commandé Obligatoire, Numérique, 13 caractères.
glnDistributor Distributeur de l'élément commandéObligatoire, Numérique, 13 caractères.
orderLineId Id unique de la ligne de commande dans le référentiel du HUB.Obligatoire
lineReference Référence ligne dans votre référentiel. Obligatoire
currency Devise utilisée pour le prix. Facultatif, ISO 4217(Liste 96 Onix)
link[] Liens associé au produit commandé. Facultatif
returnStatus Indique si la ligne commande a été transmise correctement Obligatoire , cf.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 :

url Url du lien Facultatif
format Type de format Obligatoire, 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 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. Obligatoire
mimeType Lorsqu'il est disponible le type mime du fichier lié Facultatif

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

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
physicalEan[] Liste des EAN13 physiques Obligatoire, 12 EAN13 maximum

Exemple SOAP

Exemple REST

Réponse du web service

Réponse GetDigitalVersionsResponse :

requestId Identifiant de la requête Facultatif, alphanumérique
physicalVersion[] Listes des correspondances pour chaque EAN13 physiqueFacultatif, cf. ci-dessous
returnStatus Statut de la réponse Obligatoire, cf. Codes de retour
returnMessage[] Message(s) d'erreur(s) Facultatif

Éléments physicalVersion :

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é.Facultatif, cf. ci-dessous
noDigitalVersion Retourné uniquement lorsque aucun livre numérique ne correspond à cet EAN13 physique Facultatif

Éléments digitalVersion :

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

Exemple SOAP

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” ( 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)

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

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

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 :

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

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

Les liens de téléchargement sont accessibles pendant 10 jours sur le serveur HUB.

Exemples SOAP

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.

Ce service est disponible uniquement en version SOAP, la version REST n'est pas encore implémentée.

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)

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

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

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.

Les liens de téléchargement sont accessibles pendant 10 jours sur le serveur HUB.

Exemples SOAP

Obtention de notices ONIX d'une liste d'EAN13/distributeur : getDetailNotices()

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

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

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

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 :

requestId Identifiant de la requête Facultatif, alphanumérique
detailNotice[] Liste des notices demandées cf. ci-dessous
returnStatus Statut de la réponse cf. Codes de retour
returnMessage[] Message(s) d'erreur(s) Facultatif

É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

Chargement de la notices d'un produit directement au format ONIX : getNotice()

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

Service disponible uniquement en version REST

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

Exemple REST

Réponse du web service

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

Exemple REST