Le Web service de recherche permet d’interroger la base des livres numériques. Il offre deux possibilités :
Le Web service search est disponible uniquement en version SOAP.
A chaque évolution importante de l'API de recherche (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]
| Numéro de version | Statut | URL WSDL | Date de mise en production | Date de désactivation de la version | Modifications |
|---|---|---|---|---|---|
| 1 | Actif | v1 | 09-10-2012 | 30-06-2015 | historiques de modification v1 |
| 2 | Actif | v2 | 13-01-2014 | 30-06-2015 | historiques de modification v2 |
| 3 | Actif | v3 | 05-02-2015 | historiques de modification v3 |
Version SOAP : le WSDL est disponible via l'URL suivant :
Exemple :
Version REST : Cette version n'est pas implémentée.
Un seul service est disponible, il permet d'effectuer une recherche rapide ou une recherche avancée.
Requete SearchRequest :
| 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 |
| pagination | Liste d'éléments checkAvailabilityLine spécifiant les disponibilités à vérifier | Obligatoire (cf. ci-dessous) |
| catalog | Ce paramètre permet de limiter la recherche au périmètre de catalogue HUB et/ou PNB | Obligatoire, les differents valeurs possibles sont :
catalog peut être présent deux fois dans la requête |
| quickSearch | Champ de recherche rapide, cf. ci-dessous. | Obligatoire si l'élément advancedSearch n'est pas spécifié, texte, maximum 100 caractères |
| advancedSearch | Éléments de recherche avancée, cf. ci-dessous. | Obligatoire si l'élément quickSearch n'est pas spécifié |
Élément pagination :
| nbResultsPerPage | Nombre de résultats par page souhaité | Facultatif, entier entre 1 et 30, par défaut 15 |
|---|---|---|
| currentPage | Numéro de page sur laquelle on veut se positionner, commence à 1 | Facultatif, par défaut 1 |
| sortBy | Clef de tri | Facultatif
|
| sortOrder | Ordre du critère de tri | Facultatif
|
Élément includeNotice :
| includeNotice | Indique si l'on souhaite obtenir le contenu de notices ONIX en réponse, ou seulement les identifiants (ean13, glnDistributor) des fiches. | Facultatif, boolean
|
|---|
Recherche indifféremment sur tous les champs indexés (titre, auteur, EAN, distributeur, thèmes …)
Champ quickSearch :
| quickSearch | Mot(s) ou code(s) recherché(s) | Obligatoire, texte, maximum 100 caractères |
|---|
Permet une recherche détaillée par champ.
Element advancedSearch :
| availability | Permet de filtrer sur les articles disponibles ou à paraitre sur la base des valeurs (liste 65) de la balise Product availability de la notice Onix | Facultatif
|
|---|---|---|
| title | Élément(s) de titre recherché(s) | Facultatif, texte, maximum 100 caractères |
| author | Élément(s) d'auteur recherché(s) | Facultatif, texte, maximum 100 caractères |
| publisher | Élément(s) d’éditeur recherché(s) | Facultatif, texte, maximum 100 caractères |
| distributor | Élément(s) de titre recherché(s) | Facultatif, texte, maximum 100 caractères |
| ean13 | Ean recherché, si le champ est renseigné le hub répondra sur ce seul champ en ignorant les autres critères. | Facultatif, texte, maximum 100 caractères |
| publicationSince | Permet de filtrer les articles sur la base de leur date de parution transmise dans la balise PublishingDate de la notice Onix | Facultatif
|
| keywords | Recherche dans les libellés présents dans les balises <subjects/> (thèmes CLIL, mots clefs…) | Facultatif, texte, maximum 100 caractères |
Réponse SearchResponse :
| requestId | Identifiant de la requête | Facultatif, alphanumérique |
|---|---|---|
| paginationRs | Détail de pagination des résultats | cf. ci-dessous |
| returnStatus | Statut de la reponse | cf. Codes de retour |
| returnMessage[] | Message(s) d'erreur(s) | Facultatif |
| detailNotice[] | Liste des fiches correspondant à la recherche et à la page demandée. | cf. ci-dessous |
Element paginationRs:
| nbResultsPerPage | Nombre de résultats par page | Numérique |
|---|---|---|
| currentPage | Page retournée, commence à 1 | Numérique |
| sortBy | Clef de tri |
|
| sortOrder | Ordre du critère de tri |
|
| nbFoundResults | Nombre total de fiches correspondant à la recherche | Numérique |
| nbSentResults | Nombre de fiches retournées dans la page courante. | Numérique |
Elements detailNotice :
| ean13 | EAN13 de la fiche | Numérique sur 13 |
|---|---|---|
| glnDistributor | GLN13 du distributeur de la fiche | Numérique sur 13 |
| supplierName | Nom du distributeur de la fiche | Texte |
| onixProduct | Notice ONIX (XML) de la fiche sous forme d'une chaine de caractères. | Présent uniquement si l’élément includeNotice était spécifié à true dans la requête. |
| type | Le type de notice | Obligatoire, les différents valeurs possibles sont :
|
La liste des codes de retour générée par le service search est la suivante :
Le tableau ci-dessous décrit en détail les codes de retour spécifiques au service search:
| Code (returnStatus) | Message (returnMessage) | Niveau de l'erreur dans la requête | Cause |
|---|---|---|---|
| OK | Requête | La requête est traitée sans erreur | |
| ERROR | Requête | Une erreur non spécifiée a eu lieu. | |
| INVALID_ARGUMENTS | Requête | Les argument indiqués sont erronés, ou bien certains paramètres obligatoires ne sont pas renseignés | |
| AUTHENTICATION_ERROR | Bad credentials | Requête | Erreur d'authentification |
| ACCES_DENIED | Authorization failure | Requête | L’utilisateur n’a pas le droit d’accès au service search |
| ACCES_DENIED | You are not allowed to search in catalog HUB | Requête | L'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue HUB |
| ACCES_DENIED | You are not allowed to search in catalog PNB | Requête | L'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue PNB |
| ACCES_DENIED | You are not allowed to search in catalog HUB from this GlnDistributeur | Requête | Le paramètre advancedSearch.distributor est renseigné en format GLN13 et l'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue HUB de ce distributeur |
| ACCES_DENIED | You are not allowed to search in catalog PNB from this GlnDistributeur | Requête | Le paramètre advancedSearch.distributor est renseigné en format GLN13 et l'utilisateur n'est pas autorisé à effectuer des recherches dans le catalogue PNB de ce distributeur |