Différences

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

hub_principal:examples_api_json [2015/05/28 12:33]
 hub_principal:examples_api_json [2018/04/23 11:22] (version actuelle)
Ligne 1: Ligne 1:
 +====== API Principale :  REST ( http + json) ======
 +
 +=====Présentation=====
 +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, ..).
 +
 +Notre API [[http://fr.wikipedia.org/wiki/Representational_State_Transfer|REST]]/[[http://fr.wikipedia.org/wiki/HTTP|Http]] utilise de simples requêtes HTTP GET avec un passage d'arguments standard. En cas d'erreur dans les arguments le serveur renvoie un code 403 (BadRequest) avec une description JSON des champs erronés.  Il est à noter qu'une réponse 200 **OK** ne signifie pas forcément que le service appelé s'est exécuté correctement mais qu'il a répondu correctement. Il faudra comme pour le web service soap vérifier la valeur du champ returnStatus.
 +
 +
 +
 +
 +__**Exemple d'utilisation** :__
 +
 +  * Exemple d'utilisation de cette API dans un script python : [[exemple_api_python|Exemple python]]
 +  * Exemple d'utilisation de cette API dans un script php : [[exemple_api_php|Exemple php]]
 +Pour tester cette Api confortablement il est possible d'utiliser le plugin [[https://addons.mozilla.org/en-US/firefox/addon/10869/|JSON View]] sous Firefox.
 +Vous trouverez ci-dessous des exemples d'appel et de retour de notre API REST.
 +
 +
 +
 +Pour connaître la dernière version en cours et l'adresse des services [[hub_principal:start|cliquer ici ]]
 +
 +===== Authentification =====
 +Cette API utilise l'authentification [[http://fr.wikipedia.org/wiki/HTTP_Authentification|HTTP Basic]]. Vous devez donc utiliser votre **glnReseller** et votre **passwordReseller** comme authentifiant HTTP. Les paramètres d'entée **glnReseller** et **passwordReseller** ne sont donc pas, contrairement a l'api SOAP, nécessaires.
 +
 +
 +===== Les statuts HTTP des réponses HUB=====
 +^Code ^ Statut ^ Description^
 +|200|OK| Le serveur a accepté de traiter la requête. **//Le statut de traitement de la requête est défini dans le champ returnStatus//**|
 +|400|Bad Request| Le serveur HUB ne peut pas traiter la requête puisque la requête ne respecte pas le [[hub_principal:start#|WSDL]] |
 +|401|Unauthorized| Appel d'un service sans authentification [[http://fr.wikipedia.org/wiki/HTTP_Authentification|HTTP Basic]]|
 +|403|Forbidden|Les paramètres d'authentification sont erronés |
 +|500|Internal Server Error| Erreur technique du serveur PNB|  
 +
 +===== Vérification des disponibilités : checkAvailability() =====
 +==== URL ====
 +**[ [[: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-api/json/checkAvailability?**
 +
 +==== Interrogation du web service ====
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/checkAvailability?
 +  glnContractor=0000000000000
 +  &country=FR
 +  &checkAvailabilityLines[0].ean13=9791093983004
 +  &checkAvailabilityLines[0].glnDistributor=3012410001000
 +  &checkAvailabilityLines[0].unitPrice=399
 +  &checkAvailabilityLines[1].ean13=9791093594712
 +  &checkAvailabilityLines[1].glnDistributor=3012410002007
 +  &checkAvailabilityLines[1].unitPrice=799
 +  &checkAvailabilityLines[1].unitPriceExcludingTax=450
 +  &checkAvailabilityLines[1].unitPriceExcludingTax=EUR
 +</code>
 +
 +==== Réponse du web service ====
 +<code javascript>
 +{
 +  "checkAvailabilityResponseLines" : [ {
 +    "glnDistributor" : "3012410002007",
 +    "ean13" : "9791093594712",
 +    "checkAvailabilityReturnValue" : "AVAILABLE",
 +    "returnStatus" : "OK"
 +  }, {
 +    "glnDistributor" : "3012410001000",
 +    "ean13" : "9791093983004",
 +    "checkAvailabilityReturnValue" : "AVAILABLE",
 +    "returnStatus" : "OK"
 +  } ],
 +  "returnStatus" : "OK"
 +}
 +
 +</code>
 +
 +===== Passage de commandes : sendOrder() =====
 +==== URL ====
 +**[ [[: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-api/json/sendOrder?**
 +
 +==== Interrogation du web service ====
 +
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/sendOrder?
 +  orderId=ORDER0001
 +  &glnGroup=6235482301523
 +  &glnContractor=0000000000000
 +  &customerId=test
 +  &finalBookOwner.identifier=test
 +  &finalBookOwner.civility=M
 +  &finalBookOwner.firstName=John
 +  &finalBookOwner.lastName=Doe
 +  &finalBookOwner.email=john@doe.com
 +  &finalBookOwner.country=FR
 +  &finalBookOwner.city=Paris
 +  &finalBookOwner.postalCode=75000
 +  &orderRequestLines[0].ean13=9791093983004
 +  &orderRequestLines[0].glnDistributor=3012410001000
 +  &orderRequestLines[0].quantity=1
 +  &orderRequestLines[0].unitPrice=99
 +  &orderRequestLines[0].lineReference=RefLine1
 +  &orderRequestLines[0].specialCode=SpecialCode
 +  &orderRequestLines[1].ean13=9791093594712
 +  &orderRequestLines[1].glnDistributor=3012410002007
 +  &orderRequestLines[1].quantity=1
 +  &orderRequestLines[1].lineReference=RefLine12
 +  &orderRequestLines[1].unitPrice=799
 +  &orderRequestLines[1].unitPriceExcludingTax=450
 +  &orderRequestLines[1].currency=EUR
 +</code>
 +
 +==== Réponse du web service ====
 +<code javascript>
 +{
 +  "orderId" : "ORDER0001",
 +  "orderLines" : [ {
 +    "ean13" : "9791093983004",
 +    "glnDistributor" : "3012410001000",
 +    "links" : [ {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093983004-3012410001000/8515-52594-HOEJPC4H7OI89C1SHRO06D1XTG9U7VD4.do",
 +      "ean13" : "3612220747466",
 +      "mimetype" : "text/html",
 +      "formatDescription" : "HTML",
 +      "format" : "E105"
 +    }, {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093983004-3012410001000/8515-52595-HOEJPC4H7OI89C1SHRO06D1XTG9U7VD4.do",
 +      "ean13" : "3612220747442",
 +      "mimetype" : "application/x-mobipocket-ebook",
 +      "formatDescription" : "Mobipocket",
 +      "format" : "E127"
 +    }, {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093983004-3012410001000/8515-52596-HOEJPC4H7OI89C1SHRO06D1XTG9U7VD4.do",
 +      "ean13" : "3612220747459",
 +      "mimetype" : "application/epub+zip",
 +      "formatDescription" : "EPUB",
 +      "format" : "E101"
 +    } ],
 +    "orderLineId" : "8515",
 +    "lineReference" : "RefLine1",
 +    "returnStatus" : "OK"
 +  }, {
 +    "ean13" : "9791093594712",
 +    "glnDistributor" : "3012410002007",
 +    "links" : [ {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093594712-3012410002007/8516-40155-7V4OBS3Y7MRF79ZK7ETKA4P3BCEV6GVR.do",
 +      "ean13" : "9791093594712",
 +      "mimetype" : "application/epub+zip",
 +      "formatDescription" : "EPUB",
 +      "format" : "E101"
 +    } ],
 +    "orderLineId" : "8516",
 +    "lineReference" : "RefLine12",
 +    "currency" : "EUR",
 +    "returnStatus" : "OK"
 +  } ],
 +  "returnStatus" : "OK"
 +}
 +</code>
 +
 +===== Annulation d'une commande : cancelOrder() =====
 +==== URL ====
 +**[ [[: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-api/json/cancelOrder?**
 +
 +==== Interrogation du web service ====
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/cancelOrder?
 +  orderId=ORDER0001
 +  &glnContractor=0000000000000
 +  &reason=test
 +  &cancelOrderLines[0].ean13=9791093983004
 +  &cancelOrderLines[0].glnDistributor=3012410001000
 +</code>
 +
 +==== Réponse du web service ====
 +<code javascript>
 +{
 +  "orderId" : "ORDER0001",
 +  "cancelOrderResponseLines" : [ {
 +    "glnDistributor" : "3012410001000",
 +    "ean13" : "9791093983004",
 +    "returnStatus" : "CANCELLED"
 +  } ],
 +  "returnStatus" : "OK"
 +}
 +</code>
 +
 +===== Récupération des détails d'une commande : getOrderDetails() =====
 +==== URL ====
 +**[ [[: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-api/json/getOrderDetails?**
 +
 +==== Interrogation du web service ====
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getOrderDetail?glnContractor=0000000000000&orderId=ORDER0001
 +</code>
 +
 +==== Réponse du web service ====
 +<code javascript>
 +{
 +  "returnStatus" : "OK",
 +  "orderId" : "ORDER0001",
 +  "orderLines" : [ {
 +    "ean13" : "9791093983004",
 +    "glnDistributor" : "3012410001000",
 +    "links" : [ {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093983004-3012410001000/8515-52594-HOEJPC4H7OI89C1SHRO06D1XTG9U7VD4.do",
 +      "ean13" : "3612220747466",
 +      "mimetype" : "text/html",
 +      "formatDescription" : "HTML",
 +      "format" : "E105"
 +    }, {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093983004-3012410001000/8515-52595-HOEJPC4H7OI89C1SHRO06D1XTG9U7VD4.do",
 +      "ean13" : "3612220747442",
 +      "mimetype" : "application/x-mobipocket-ebook",
 +      "formatDescription" : "Mobipocket",
 +      "format" : "E127"
 +    }, {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093983004-3012410001000/8515-52596-HOEJPC4H7OI89C1SHRO06D1XTG9U7VD4.do",
 +      "ean13" : "3612220747459",
 +      "mimetype" : "application/epub+zip",
 +      "formatDescription" : "EPUB",
 +      "format" : "E101"
 +    } ],
 +    "orderLineId" : "8515",
 +    "lineReference" : "RefLine1",
 +    "returnStatus" : "OK"
 +  }, {
 +    "ean13" : "9791093594712",
 +    "glnDistributor" : "3012410002007",
 +    "links" : [ {
 +      "url" : "https://hub-dilicom.centprod.com/v3//link/3026900001000/ORDER0001/9791093594712-3012410002007/8516-40155-7V4OBS3Y7MRF79ZK7ETKA4P3BCEV6GVR.do",
 +      "ean13" : "9791093594712",
 +      "mimetype" : "application/epub+zip",
 +      "formatDescription" : "EPUB",
 +      "format" : "E101"
 +    } ],
 +    "orderLineId" : "8516",
 +    "lineReference" : "RefLine12",
 +    "currency" : "EUR",
 +    "returnStatus" : "OK"
 +  } ]
 +}
 +</code>
 +
 +===== Obtention des version numériques associé à des ean physiques : getDigitalVersions()  =====
 +==== URL ====
 +**[ [[: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-api/json/getDigitalVersions?**
 +
 +==== Interrogation du web service ====
 +<code javascript>
 +https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/getDigitalVersions?
 +  glnContractor=3026900001000
 +  &physicalEans[0]=9782092524374
 +  &physicalEans[1]=9782212120035
 +</code>
 +
 +==== Réponse du web service ====
 +<code javascript>
 +{
 +  "physicalVersions" : [ {
 +    "ean13" : "9782092524374",
 +    "noDigitalVersion" : ""
 +  }, {
 +    "digitalVersions" : [ {
 +      "glnDistributor" : "3012410001000",
 +      "ean13" : "9782212850888"
 +    } ],
 +    "ean13" : "9782212120035"
 +  } ],
 +  "returnStatus" : "OK"
 +}
 +</code>
 +
 +===== Récupération des notices : getNotices() =====
 +
 +==== URL ====
 +**[ [[: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-api/json/getNotices?**
 +
 +==== Interrogation du web service ====
 +
 +=== Cas 1 – Initialisation du catalogue (service désactivé, le catalogue d'initialisation est fourni par FTP) ===
 +<note important>
 +Attention : l'option initialization a été désactivée, merci de contacter Dilicom pour plus d’informations.
 +</note>
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getNotices?glnGroup=0000000000000&glnContractor=30269000010012&initialization
 +</code>
 +
 +=== Cas 2 - Récupération depuis un instant T ===
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getNotices?glnGroup=0000000000000&glnContractor=30269000010012&sinceDate=2010-08-20T00:00:00
 +</code>
 +
 +
 +=== Cas 3 - Récupération depuis la dernière connexion ===
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getNotices?glnGroup=0000000000000&glnContractor=30269000010012&lastConnection
 +</code>
 +
 +==== Réponse du Web Service ====
 +<code javascript>
 +{
 +    onixFileUrls:[{
 +        httpLink:"https://hub-dilicom.centprod.com/notices_onix/diffusion_3025594195700_201008272128_1110247456419854240546744705832927698715.xml"
 +        },{
 +        httpLink:"https://hub-dilicom.centprod.com/notices_onix/diffusion_3025594164342_201008272330_1256851354542405467447058329276987145685.xml"
 +    }],
 +    returnStatus:"OK"
 +}
 +</code>
 +
 +<note important>L'exemple présente le cas où plusieurs fichiers sont renvoyés. Actuellement le web service renvoie toujours un seul lien, cependant il est possible qu'à terme il soit nécessaire de renvoyer plusieurs liens.</note>
 +
 +Ou bien lorsque aucune notice ne correspond à la demande :
 +<code javascript>
 +{
 +    noNotice: "",
 +    returnStatus:"OK"
 +}
 +</code>
 +
 +===== Récupération des notices pour un seul distributeur : getNoticesForDistributor() =====
 +<note important> Service non  implémenté en REST. </note>
 +
 +===== Obtention de notices onix d'une liste d'ean/distributeur : getDetailNotices() =====
 +==== URL ====
 +**[ [[: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-api/json/getDetailNotices?**
 +
 +==== Interrogation du web service ====
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getDetailNotices?
 +  glnContractor=0000000000000
 +  &notices[0].ean13=9782092528068
 +  &notices[0].glnDistributor=3012410003004
 +  &notices[1].ean13=9782092628068
 +  &notices[1].glnDistributor=3012410003004
 +</code>
 +
 +==== Réponse du web service ====
 +<code javascript>
 +{
 +  "detailNotices" : [ {
 +    "ean13" : "9782092528068",
 +    "onixProduct" :"<ONIXMessage>.....</ONIXMessage>" ,
 +    "glnDistributor" : "3012410003004"
 +  }, {
 +    "ean13" : "9782092628068",
 +    "glnDistributor" : "3012410003004",
 +    "noNotice" : ""
 +  } ],
 +  "returnStatus" : "OK"
 +}
 +</code>
 +
 +
 +
 +===== Chargement de la notices d'un produit directement au format ONIX : getNotice() =====
 +<note important>Attention ce service ne retourne pas du JSON mais directement un message ONIX, donc au format XML.</note>
 +
 +
 +
 +==== URL ====
 +**[ [[: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-api/onix/getNotice?**
 +
 +
 +
 +==== Interrogation du web service ====
 +<code javascript>
 +https://hub-dilicom.centprod.com/v3/hub-numerique-api/onix/getNotice?
 +  glnContractor=0000000000000
 +  &ean13=3600120309440
 +  &glnDistributor=3012410001000
 +</code>
 +
 +==== Réponse du web service ====
 +<code xml>
 +<?xml version="1.0" encoding="UTF-8"?><ONIXMessage release="3.0" xmlns="http://www.editeur.org/onix/3.0/reference">
 +<Header>
 +<Sender>
 +<SenderIdentifier><SenderIDType>06</SenderIDType><IDValue>3025599000108</IDValue></SenderIdentifier>
 +<SenderName>SERVEUR DILICOM - HUB NUMERIQUE</SenderName></Sender>
 +<Addressee><AddresseeIdentifier><AddresseeIDType>06</AddresseeIDType><IDValue>3012410001000</IDValue></AddresseeIdentifier></Addressee>
 +<SentDateTime>20101103T0529Z</SentDateTime>
 +</Header>
 +<Product><RecordReference>immateriel.fr-RP944</RecordReference><NotificationType>03</NotificationType><ProductIdentifier><ProductIDType>01</ProductIDType><IDValue>RP944</IDValue></ProductIdentifier><ProductIdentifier><ProductIDType>03</ProductIDType><IDValue>3600120309440</IDValue></ProductIdentifier><DescriptiveDetail><ProductComposition>00</ProductComposition><ProductForm>ED</ProductForm><ProductFormDetail>E107</ProductFormDetail><ProductFormDescription>PDF</ProductFormDescription><EpubTechnicalProtection>02</EpubTechnicalProtection><EpubUsageConstraint><EpubUsageType>02</EpubUsageType><EpubUsageStatus>01</EpubUsageStatus></EpubUsageConstraint><EpubUsageConstraint><EpubUsageType>03</EpubUsageType><EpubUsageStatus>01</EpubUsageStatus></EpubUsageConstraint><EpubUsageConstraint><EpubUsageType>04</EpubUsageType><EpubUsageStatus>01</EpubUsageStatus></EpubUsageConstraint><TitleDetail><TitleType>01</TitleType><TitleElement><TitleElementLevel>01</TitleElementLevel><TitleText>Mieux programmer en C++</TitleText></TitleElement></TitleDetail></DescriptiveDetail><RelatedMaterial><RelatedProduct><ProductRelationCode>02</ProductRelationCode><ProductIdentifier><ProductIDType>01</ProductIDType><IDValue>O18600</IDValue></ProductIdentifier><ProductIdentifier><ProductIDType>03</ProductIDType><IDValue>9782212850185</IDValue></ProductIdentifier><ProductIdentifier><ProductIDType>15</ProductIDType><IDValue>9782212850185</IDValue></ProductIdentifier></RelatedProduct></RelatedMaterial><ProductSupply><SupplyDetail><Supplier><SupplierRole>03</SupplierRole><SupplierIdentifier><SupplierIDType>02</SupplierIDType><IDValue>D1</IDValue></SupplierIdentifier><SupplierIdentifier><SupplierIDType>06</SupplierIDType><IDValue>3012410001000</IDValue></SupplierIdentifier><SupplierName>immat&#233;riel.fr</SupplierName></Supplier><ProductAvailability>45</ProductAvailability><UnpricedItemType>03</UnpricedItemType></SupplyDetail></ProductSupply></Product>
 +
 +</ONIXMessage>
 +</code>
 +