Ceci est une ancienne révision du document !

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.

Les arguments sont les mêmes que dans l'interface SOAP. Chaque méthode a sa propre URL :

Vous trouverez ci-dessous des exemples d'appel et de retour de notre API REST.

Exemple d'utilisation de cette API dans un script python : Exemple python

Exemple d'utilisation de cette API dans un script php : Exemple php

Pour tester cette Api confortablement il est possible d'utiliser le plugin JSON View sous Firefox.

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.

Récupération des notices : getNotices()

Interrogation du web service

Cas 1=> Initialisation du catalogue (non actif, 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/v1/hub-numerique-api/json/getNotices?initialization

Cas 2 => Récupération depuis un instant T

https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/getNotices?sinceDate=2010-08-20T00:00:00

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

https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/getNotices?lastConnection

Réponse du Web Service

{
    onixFileUrls:[{
        httpLink:"https://hub-dilicom.centprod.com/notices_onyx/diffusion_3025594195700_201008272128_1110247456419854240546744705832927698715.xml"
        },{
        httpLink:"https://hub-dilicom.centprod.com/notices_onyx/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"
}

Vérification des disponibilités : checkAvailability()

Interrogation du web service

https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/checkAvailability?
  checkAvailabilityLines[0].ean13=9782296408876
  &checkAvailabilityLines[0].glnDistributor=3012410105012
  &checkAvailabilityLines[0].unitPrice=1
  &checkAvailabilityLines[1].ean13=9782296408870
  &checkAvailabilityLines[1].glnDistributor=3012410105012
  &checkAvailabilityLines[1].unitPrice=1

Réponse du web service

{
    checkAvailabilityResponseLines: [
        {
            glnDistributor: "3012410105012"
            returnStatus: "OK"
            returnMessage: [
                "The EAN13 9782296408870 does not exists for Distributor GLN 3012410105012"
            ]
            ean13: "9782296408870"
            checkAvailabilityReturnValue: "UNAVAILABLE"
        }
        {
            glnDistributor: "3012410105012"
            returnStatus: "OK"
            ean13: "9782296408876"
            checkAvailabilityReturnValue: "AVAILABLE"
        }
    ]
    returnStatus: "OK"
    returnMessage: []
}

Passage de commandes : sendOrder()

Interrogation du web service

https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/sendOrder?
  glnGroup=6235482301523
  &orderId=ORDER0001
  &customerId=test
  &finalBookOwner.identifier=test
  &finalBookOwner.civility=M
  &finalBookOwner.firstName=John
  &finalBookOwner.lastName=Doe
  &finalBookOwner.email=john@doe.com
  &finalBookOwner.country=France
  &finalBookOwner.city=Paris
  &finalBookOwner.postalCode=75000
  &orderRequestLines[0].ean13=9782814500136
  &orderRequestLines[0].glnDistributor=3012410001000
  &orderRequestLines[0].quantity=125
  &orderRequestLines[0].unitPrice=1
  &orderRequestLines[0].lineReference=01
  &orderRequestLines[1].ean13=9990000000001
  &orderRequestLines[1].glnDistributor=3012410002007
  &orderRequestLines[1].quantity=1
  &orderRequestLines[1].lineReference=02
  &orderRequestLines[1].unitPrice=1

Réponse du web service

{
  returnStatus: "OK",
  orderId: "ORDER0001",
  orderLines: [{
	ean13: "9990000000001",
	glnDistributor: "3012410002007",
	returnStatus: "OK",
	links: [{
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9990000000001-3012410002007/96-21-K9RY82112MOO8SSKDOAEI8D7WTKPP83J.do",
      formatDescription: "Unknown Format",
      ean13: "9990000000001"
    }],
    orderLineId: "96",
    lineReference:"01"
      },{
    ean13: "9782814500136",
    glnDistributor: "3012410001000",
    returnStatus: "OK",
    links: [{
	  format: "E127",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-22-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "application/x-mobipocket",
	  formatDescription: "Mobipocket",
        ean13: "9782814500136"
    },{
	  format: "E107",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-23-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "application/pdf",
	  formatDescription: "PDF",
          ean13: "9782814500136"
    },{
	  format: "E107",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-24-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "application/pdf",
	  formatDescription: "PDF",
          ean13: "9782814500136"
    },{
	  format: "E105",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-25-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "text/html",
	  formatDescription: "HTML",
          ean13: "9782814500136"
    }],
  orderLineId: "95",
  lineReference:"02"
  }]
}

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

Interrogation du web service

https://hub-dilicom.centprod.com/v1/hub-numerique-api/json/getOrderDetail?orderId=ORDER0001

Réponse du web service

{
  returnStatus: "OK",
  orderId: "ORDORDER0001",
  orderLines: [{
	ean13: "9990000000001",
	glnDistributor: "3012410002007",
	returnStatus: "OK",
	links: [{
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9990000000001-3012410002007/96-21-K9RY82112MOO8SSKDOAEI8D7WTKPP83J.do",
      formatDescription: "Unknown Format",
      ean13: "9990000000001"
    }],
    orderLineId: "96",
    lineReference:"01"
  },{
    ean13: "9782814500136",
    glnDistributor: "3012410001000",
    returnStatus: "OK",
    links: [{
	  format: "E127",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-22-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "application/x-mobipocket",
	  formatDescription: "Mobipocket",
          ean13: "9782814500136"
    },{
	  format: "E107",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-23-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "application/pdf",
	  formatDescription: "PDF",
          ean13: "9782814500136"
    },{
	  format: "E107",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-24-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "application/pdf",
	  formatDescription: "PDF",
          ean13: "9782814500136"
    },{
	  format: "E105",
	  url: "https://hub-dilicom.centprod.com/v1/link/3025594195700/ORDORDER0001/9782814500136-3012410001000/95-25-O70IIWUBEF85G8I2THAPFM9OA2CPRBMX.do",
	  mimetype: "text/html",
	  formatDescription: "HTML",
          ean13: "9782814500136"
    }],
    orderLineId: "95",
    lineReference:"02"
  }]
}

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

Interrogation du web service

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

Réponse du web service

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

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

Interrogation du web service

http:/hub.dilicom.net/hub-numerique-api/json/getDetailNotices?
  notices[0].ean13=9782092528068
  &notices[0].glnDistributor=3012410003004
  &notices[1].ean13=9782092628068
  &notices[1].glnDistributor=3012410003004

Réponse du web service

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

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

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

Interrogation du web service

https://hub-dilicom.centprod.com/v1/hub-numerique-api/onix/getNotice?
  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>

Chargement des notices onix par lien direct : getNotices()

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

Interrogation du web service

Cas 1=> Initialisation du catalogue

https://hub-dilicom.centprod.com/v1/hub-numerique-api/onix/getNotices?initialization

Cas 2 => Récupération depuis un instant T

https://hub-dilicom.centprod.com/v1/hub-numerique-api/onix/getNotices?sinceDate=2010-08-20T00:00:00

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

https://hub-dilicom.centprod.com/v1/hub-numerique-api/onix/getNotices?lastConnection

Réponse du web service

Le service répond un code HTTP 204 No content lorsqu'aucune notice ne correspond à la demande. Si la mise à jour contient des fiches le service redirige vers un fichier onix contenant les notices demandées. 

<?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>
<Product>
 
....
 
</Product>
</ONIXMessage>