Table des matières

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

Notre API REST/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 :

Pour tester cette Api confortablement il est possible d'utiliser le plugin 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 cliquer ici

Authentification

Cette API utilise l'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
200OK Le serveur a accepté de traiter la requête. Le statut de traitement de la requête est défini dans le champ returnStatus
400Bad Request Le serveur HUB ne peut pas traiter la requête puisque la requête ne respecte pas le WSDL
401Unauthorized Appel d'un service sans authentification HTTP Basic
403ForbiddenLes paramètres d'authentification sont erronés
500Internal Server Error Erreur technique du serveur PNB

Vérification des disponibilités : checkAvailability()

URL

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique-api/json/checkAvailability?

Interrogation du web service

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

Réponse du web service

{
  "checkAvailabilityResponseLines" : [ {
    "glnDistributor" : "3012410002007",
    "ean13" : "9791093594712",
    "checkAvailabilityReturnValue" : "AVAILABLE",
    "returnStatus" : "OK"
  }, {
    "glnDistributor" : "3012410001000",
    "ean13" : "9791093983004",
    "checkAvailabilityReturnValue" : "AVAILABLE",
    "returnStatus" : "OK"
  } ],
  "returnStatus" : "OK"
}

Passage de commandes : sendOrder()

URL

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique-api/json/sendOrder?

Interrogation du web service

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

Réponse du web service

{
  "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"
}

Annulation d'une commande : cancelOrder()

URL

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique-api/json/cancelOrder?

Interrogation du web service

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

Réponse du web service

{
  "orderId" : "ORDER0001",
  "cancelOrderResponseLines" : [ {
    "glnDistributor" : "3012410001000",
    "ean13" : "9791093983004",
    "returnStatus" : "CANCELLED"
  } ],
  "returnStatus" : "OK"
}

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

URL

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique-api/json/getOrderDetails?

Interrogation du web service

https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getOrderDetail?glnContractor=0000000000000&orderId=ORDER0001

Réponse du web service

{
  "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"
  } ]
}

Obtention des version numériques associé à des ean physiques : getDigitalVersions()

URL

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique-api/json/getDigitalVersions?

Interrogation du web service

https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/getDigitalVersions?
  glnContractor=3026900001000
  &physicalEans[0]=9782092524374
  &physicalEans[1]=9782212120035

Réponse du web service

{
  "physicalVersions" : [ {
    "ean13" : "9782092524374",
    "noDigitalVersion" : ""
  }, {
    "digitalVersions" : [ {
      "glnDistributor" : "3012410001000",
      "ean13" : "9782212850888"
    } ],
    "ean13" : "9782212120035"
  } ],
  "returnStatus" : "OK"
}

Récupération des notices : getNotices()

URL

[ Nom de la plateforme]/v[ 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)

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

https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getNotices?glnGroup=0000000000000&glnContractor=30269000010012&initialization

Cas 2 - Récupération depuis un instant T

https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getNotices?glnGroup=0000000000000&glnContractor=30269000010012&sinceDate=2010-08-20T00:00:00

Cas 3 - Récupération depuis la dernière connexion

https://hub-dilicom.centprod.com/v3/hub-numerique-api/json/getNotices?glnGroup=0000000000000&glnContractor=30269000010012&lastConnection

Réponse du Web Service

{
    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"
}

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.

Ou bien lorsque aucune notice ne correspond à la demande : 

{
    noNotice: "",
    returnStatus:"OK"
}

Récupération des notices pour un seul distributeur : getNoticesForDistributor()

Service non implémenté en REST.

Obtention de notices onix d'une liste d'ean/distributeur : getDetailNotices()

URL

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique-api/json/getDetailNotices?

Interrogation du web service

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

Réponse du web service

{
  "detailNotices" : [ {
    "ean13" : "9782092528068",
    "onixProduct" :"<ONIXMessage>.....</ONIXMessage>" ,
    "glnDistributor" : "3012410003004"
  }, {
    "ean13" : "9782092628068",
    "glnDistributor" : "3012410003004",
    "noNotice" : ""
  } ],
  "returnStatus" : "OK"
}

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

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

URL

[ Nom de la plateforme]/v[ numéro de version ]/hub-numerique-api/onix/getNotice?

Interrogation du web service

https://hub-dilicom.centprod.com/v3/hub-numerique-api/onix/getNotice?
  glnContractor=0000000000000
  &ean13=3600120309440
  &glnDistributor=3012410001000

Réponse du web service

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