Webservice API/en: Unterschied zwischen den Versionen

Aus TopData WIKI
Wechseln zu: Navigation, Suche
(Die Seite wurde neu angelegt: „the product list is returned.“)
 
(28 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
 
<languages />
 
<languages />
−
<h2>Webservice API Grundlagen</h2>
+
<br />
−
<h3>Nutzung</h3>
+
<h2>Webservice Api Basics</h2>
−
<p>Mit dem Zugang zum Webservice haben Sie automatisch unsere [[Webservice Nutzungsbedingungen]] verstanden und akzeptiert.<br><br>
+
<h3>Use</h3>
−
Zugriffe werden geloggt und ausgewertet. Um Zugriffe/Bandbreite sowie Serverkapazitäten zu sparen, wird empfohlen, die Anfragen an den Webservice (soweit es geht), durch Datencaching zu minimieren. Wir behalten uns das Recht vor, Zugänge einzuschränken oder gegebenenfalls auch zu sperren, sollte der Zugriff zum Webservice über ein plausibles Mass hinausgehen.<br>
+
<p> By accessing our web service, you automatically declare that you understand and accept our  [[web service use conditions]].<br /><br />
−
Zugangsdaten dürfen nicht an Dritte weitergegeben oder öffentlich dargestellt werden.<br>
+
Access is logged and evaluated. To save access/bandwidth and
−
Für Ihre Zugangsdaten sind bestimmte, vorher vereinbarte, Daten freigegeben.
+
server capacity, we recommend minimising queries to the web service via data caching
−
</p>
+
(if possible). We reserve the right to limit access or even to block it if access to the web service
−
<h3>Datenformat</h3>
+
exceeds a plausible level.<br />
 +
Access data may not be provided to third parties or displayed publicly. Certain previously
 +
agreed data is approved for use as your access details.</p>
 +
<h3> Data format: </h3>
 
<p>
 
<p>
−
Die Rückgabe des Webservices erfolgt im [http://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] Format.
+
The web service is returned in the JSON format. We have decided against XML because JSON is currently equally as popular and reduces overhead compared with XML.
−
Wir haben uns gegen XML entschieden, da JSON inzwischen genauso weit verbreitet ist und gegenüber XML den Overhead reduziert. [http://de.wikipedia.org/wiki/JavaScript_Object_Notation#Unterschied_zu_XML Mehr Informationen]
+
[http://de.wikipedia.org/wiki/JavaScript_Object_Notation#Unterschied_zu_XML More Information]
 
</p>
 
</p>
−
<h3>Zeichencodierung</h3>
+
<h3> Character encoding </h3>
 
<p>
 
<p>
−
Die Ausgabe der Daten des Webservices erfolgt in [http://de.wikipedia.org/wiki/UTF-8 UFT8]
+
data from the web services is released [http://de.wikipedia.org/wiki/UTF-8 UFT8]
 
</p>
 
</p>
−
<h3>Zugang</h3>
+
<h3>Access</h3>
 
<p>
 
<p>
−
Der Abruf der Webservice-Daten erfolgt über eine feste HTTP URL.
+
The web service data is accessed via a fixed HTTP URL </p>
−
</p>
+
 
<source lang="text">http://ws.cloud.topdata.de</source>
 
<source lang="text">http://ws.cloud.topdata.de</source>
 
<p> Access data is required to access the web service, which is comprised as follows:
 
<p> Access data is required to access the web service, which is comprised as follows:
Zeile 35: Zeile 37:
 
<h3>API-Version</h3>
 
<h3>API-Version</h3>
 
If the web service is changed, then a new API version will be provided so that your own application does not always also need to be updated. ATTENTION: We can only provide support for the latest API version.
 
If the web service is changed, then a new API version will be provided so that your own application does not always also need to be updated. ATTENTION: We can only provide support for the latest API version.
−
* actual APIVersion: '''100'''
+
* actual APIVersion: '''110'''
−
<source lang="text">?version=100</source>
+
<source lang="text">?version=103</source>
 
<h3>Language</h3>
 
<h3>Language</h3>
 
The language must be provided as per [http://de.wikipedia.org/wiki/ISO_639#ISO_639-1 ISO 639-1]
 
The language must be provided as per [http://de.wikipedia.org/wiki/ISO_639#ISO_639-1 ISO 639-1]
 
<source lang="text">?language=en</source>
 
<source lang="text">?language=en</source>
 
<h3>Error Codes</h3>
 
<h3>Error Codes</h3>
−
Overview of all errors:
+
Alle Fehler im Überblick
 
{| class="wikitable"
 
{| class="wikitable"
−
!Error Code!!Description
+
!Fehler Code!!Fehler Beschreibung
 +
|-
 +
|''100''||Unbekannter Fehler
 
|-
 
|-
−
|''100''||unknown error
+
|''101''||404 - Seite nicht gefunden
 
|-
 
|-
−
|''101''||404 – page not found
+
|''102''||User ID nicht vorhanden oder nicht valide
 
|-
 
|-
−
|''102''||User ID not available or not valid
+
|''103''||Sicherheitscode nicht vorhanden oder nicht valide
 
|-
 
|-
−
|''103''||safety code not available or not valid
+
|''104''||Passwort nicht vorhanden oder nicht valide
 
|-
 
|-
−
|''104''||password not available or not valid
+
|''105''||API-Version nicht vorhanden oder nicht valide
 
|-
 
|-
−
|''105''||API-Version not available or not valid
+
|''106''||Authentifizierung fehlgeschlagen
 
|-
 
|-
−
|''106''||authentication failed
+
|''107''||Sprache nicht vorhanden oder nicht valide
 
|-
 
|-
−
|''107''||language not available or not valid
+
|''108''||Template nicht gefunden (Bitte Service informieren)
 
|-
 
|-
−
|''108''||template not found (please inform service)
+
|''109''||Template Fehler (Bitte Service informieren)
 
|-
 
|-
−
|''109''||template error (please inform service)
+
|''110''||Filter nicht vorhanden oder nicht valide
 
|-
 
|-
−
|''200''||product not found
+
|''200''||Produkt nicht gefunden
 
|}
 
|}
  
Zeile 75: Zeile 79:
 
When accessing:
 
When accessing:
 
<source lang="text">http://ws.cloud.topdata.de/my_products?
 
<source lang="text">http://ws.cloud.topdata.de/my_products?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 80: Zeile 85:
 
   version=%version%&
 
   version=%version%&
 
   language=%language%</source>
 
   language=%language%</source>
−
the product list is returned.
+
erhalten Sie die Produktliste als Rückgabe.
−
<h3> Product groups </h3>
+
<h4>My products only with articlenumber</h4>
−
<p> Accesses the complete product groups as a list::</p>
+
<p>You get all your products as [[Webservice_API#Produktliste|productlist]] that are activate for your account and where is a articlenumber of a distributor for.</p>
 +
<source lang="text">http://ws.cloud.topdata.de/distributor_products</source>
 +
<h3>Waregroups</h3>
 +
<p>get the complete waregroups as list:</p>
 
<source lang="text">http://ws.cloud.topdata.de/waregroups</source>
 
<source lang="text">http://ws.cloud.topdata.de/waregroups</source>
 
<p>''' Example: '''</p>
 
<p>''' Example: '''</p>
 
When accessing:
 
When accessing:
 
<source lang="text">http://ws.cloud.topdata.de/waregroups?
 
<source lang="text">http://ws.cloud.topdata.de/waregroups?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 118: Zeile 127:
 
When accessing
 
When accessing
 
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%?
 
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 125: Zeile 135:
 
the product list is returned
 
the product list is returned
  
−
<h3>Productlist</h3>
+
<h3>Produktliste</h3>
−
<p>Die The product list includes all information about the products and is returned when certain web services are accessed.</p>
+
<p>Die Produktliste enthält alle vom Filter zugelassenen Informationen zu den Produkten und wird bei bestimmten Webservice-Aufrufen zurückgegeben. Es gelten die selben [[Webservice_API#Filter|Filterangaben wie beim Produkt]]</p>
−
* [[Webservice_API#Warengruppen|waregroup_products]]
+
* [[Webservice_API#Warengruppen|Warengruppen Produkte]]
 
* [[Webservice_API#bundle_content|''bundle_content'']]  
 
* [[Webservice_API#bundle_content|''bundle_content'']]  
 
* [[Webservice_API#product_alternates|''product_alternates'']]  
 
* [[Webservice_API#product_alternates|''product_alternates'']]  
Zeile 133: Zeile 143:
 
* [[Webservice_API#product_accessories|''product_accessories'']]  
 
* [[Webservice_API#product_accessories|''product_accessories'']]  
 
* [[Webservice_API#product_application_in|''product_application_in'']]
 
* [[Webservice_API#product_application_in|''product_application_in'']]
−
* [[Webservice_API#Anbieter Produkte|provider_products]]
+
* [[Webservice_API#Anbieter Produkte|Anbieter Produkte]]
−
<p>'''Example'''</p>
+
<p>'''Beispiel'''</p>
 
<source lang="javascript">
 
<source lang="javascript">
 
{
 
{
Zeile 154: Zeile 164:
 
The products in the product list are displayed analogously to how individual products are accessed.
 
The products in the product list are displayed analogously to how individual products are accessed.
 
</p>
 
</p>
 +
<p>'''more products for one request (since version 103)'''</p>
 +
<p>You can give the webservice more than one products id to get a productlist for this.
 +
Provide the products ids comma seperated in a string. Attention only maximal 50 Product-IDs are allowed(more of this will be ignored).
 +
</p>
 +
<source lang="text">http://ws.cloud.topdata.de/product_list</source>
 +
<p>'''Example'''</p>
 +
By accessing:
 +
<source lang="text">http://ws.cloud.topdata.de/product_list?products=123456,789012&
 +
  filter=%filter%&
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
the productlist is returned 2 products(123456 and 789012).
 
<h3>Product</h3>
 
<h3>Product</h3>
−
<p> Accesses an individual product from the web service. The product ID is required for this.</p>
+
<p>Request one with the from filter allowed informations of the webservice. The product ID is required for this</p>
 
* Produkt ID (%products_id%)
 
* Produkt ID (%products_id%)
 +
* Filter (%filter%)
 
<source lang="text">http://ws.cloud.topdata.de/product</source>
 
<source lang="text">http://ws.cloud.topdata.de/product</source>
 
<p>'''Example''' für den Artikel 92298A von HP</p>
 
<p>'''Example''' für den Artikel 92298A von HP</p>
 
By accessing:
 
By accessing:
−
<source lang="text">http://ws.cloud.topdata.de/product/145080?
+
<source lang="text">http://ws.cloud.topdata.de/product/145080?filter=all&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 283: Zeile 309:
 
}
 
}
 
</source>
 
</source>
−
<p>Bei der [[Webservice_API#Produktliste|Produktliste]] werden die Produkte ebenso übergeben.<br><br></p>
 
  
 +
<p>By the [[Webservice_API#Produktliste|Productlist]] the products will be transfered in the same way<br /><br /></p>
 +
<h4>Filter</h4>
 +
<p>since Verion 103 required</p>
 +
<p>The product features can be filtered to minimize the JSON return of the webservice. If not all the information are needed, with teh correct filtering the converting from JSON to an object can save a lot of time in your application.</p>
 +
* Filter (%filter%)
 +
<source lang="text">?filter=all</source>
 +
<p>The following basic filter available "all". This is in principle given back everything. If you do not need anything, you can use different filters in the table below.
 +
This can also be passed separately combined with comma.</p>
 +
<source lang="text">?filter=specifications,product_alternates</source>
 
{| class="wikitable"
 
{| class="wikitable"
−
|+ Legend of unclear variables
+
|+ Legend of unclear variables and filter values
−
!Variable!!Description
+
!Variable!!Description!!Filter
 
|-
 
|-
 
|''reference_oems''||If the product is an alternative, then the OEMs for the corresponding products appear here
 
|''reference_oems''||If the product is an alternative, then the OEMs for the corresponding products appear here
Zeile 294: Zeile 328:
  
 
|-
 
|-
−
|[[Webservice_API#bundle_content|''bundle_content'']]||Falls If the product is a bundle, then the product IDs for the individual products appear here
+
|''waregroups''||Waregroups for the product||waregroups
 +
|-
 +
|''specifications''||specifications for the product||specifications
 +
|-
 +
|''images''||Images for the product||images
 +
|-
 +
|[[Webservice_API#bundle_content|''bundle_content'']]||Falls If the product is a bundle, then the product IDs for the individual products appear here||bundle_content
  
 
|-
 
|-
−
|[[Webservice_API#product_alternates|''product_alternates'']]|| Alternative product IDs for the product
+
|[[Webservice_API#product_alternates|''product_alternates'']]|| Alternative product IDs for the product||product_alternates
  
 
|-
 
|-
−
|[[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]|| The product is an alternative of the product IDs indicated
+
|[[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]|| The product is an alternative of the product IDs indicated||product_is_alternate_of
 +
|-
 +
|[[Webservice_API#product_accessories|''product_accessories'']]||Zubehör Accessory product IDs for the product||product_accessories
 
|-
 
|-
−
|[[Webservice_API#product_accessories|''product_accessories'']]||Zubehör Accessory product IDs for the product
+
|[[Webservice_API#product_same_accessories|''product_same_accessories'']]|| All product IDs with the same accessories for the product||product_same_accessories
 
|-
 
|-
−
|[[Webservice_API#product_same_accessories|''product_same_accessories'']]|| All product IDs with the same accessories for the product
+
|[[Webservice_API#product_application_in|''product_application_in'']]|| Product is an accessory of the named product IDs||product_application_in
 
|-
 
|-
−
|[[Webservice_API#product_application_in|''product_application_in'']]|| Product is an accessory of the named product IDs
+
|[[Webservice_API#product_same_application_in|''product_same_application_in'']]|| All product IDs with the same parent product which are an accessory for the product||product_same_application_in
 
|-
 
|-
−
|[[Webservice_API#product_same_application_in|''product_same_application_in'']]|| All product IDs with the same parent product which are an accessory for the product
+
|''child_extra_infos''||Basic infos for the crossesproducts (manufacturer, name and shortdescription) (since version 102)||child_extra_infos
 
|-
 
|-
−
|''distributors''|| available providers and their article numbers
+
|''distributors''|| available providers and their article numbers||
 
|}<br />
 
|}<br />
 
{| class="wikitable"
 
{| class="wikitable"
Zeile 330: Zeile 372:
 
By accessing:
 
By accessing:
 
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%?
 
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 344: Zeile 387:
 
By accessing:
 
By accessing:
 
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%?
 
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 359: Zeile 403:
 
Bay accessing:
 
Bay accessing:
 
<source lang="text">http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%?
 
<source lang="text">http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 373: Zeile 418:
 
By accessing
 
By accessing
 
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%?
 
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 387: Zeile 433:
 
By accessing
 
By accessing
 
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%?
 
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 402: Zeile 449:
 
By accessing:
 
By accessing:
 
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%?
 
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 416: Zeile 464:
 
By accessing
 
By accessing
 
<source lang="text">http://ws.cloud.topdata.de/product_same_application_in/%product_id%?
 
<source lang="text">http://ws.cloud.topdata.de/product_same_application_in/%product_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 423: Zeile 472:
 
the product list is returned.
 
the product list is returned.
  
−
<h3>Anbieter Produkte</h3>
+
<h3>Provider products</h3>
−
<p>Ruft zu einem bestimmten Anbieter die Produkte ab. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
+
<p> Accesses the products for a certain provider. These are output as a  [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.</p>
−
Dafür ist die Anbieter ID notwendig. Diese ist z.B. bei einem der Produkte einsehbar.</p>
+
 
* Anbieter ID (%distributor_id%)
 
* Anbieter ID (%distributor_id%)
 
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%</source>
 
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%</source>
−
<p>'''Beispiel'''</p>
+
<p>'''Example'''</p>
−
Bei Aufruf von:
+
By accessing:
 
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%?
 
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%?
 +
  filter=%filter%&
 
   uid=%uid%&
 
   uid=%uid%&
 
   security_key=%security_key%&
 
   security_key=%security_key%&
Zeile 436: Zeile 485:
 
   version=%version%&
 
   version=%version%&
 
   language=%language%</source>
 
   language=%language%</source>
−
erhalten Sie die Produktliste als Rückgabe.
+
<h3>Productfinder</h3>
−
<h2>Code Beispiele</h2>
+
<p>Here you get the data ready to use it as productfinder.</p>
 +
<h4>''Ink and Toner Finder''</h4>
 +
<p>The Ink and Toner Finder needs to find the matching consumables for your printer in 2-3 steps.</p>
 +
* Printer-Brand (Required) ''Step 1''
 +
* Printer-Modelseries (Optional) ''Step 2''
 +
* Printer-Types (Optional) ''Step 2''
 +
* Printer-Model (Required) ''Step 3''
 +
* Printer-Model Textsearch
 +
<p>'''Printer-Brand'''</p>
 +
By accessing:
 +
<source lang="text">http://ws.cloud.topdata.de/finder/ink_toner/brands?
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<p>you get the Printer-Brands as Request.</p>
 +
<p>'''Printer-Modelseries'''</p>
 +
By accessing:
 +
* Printer-Brand ID is required (%brand_id%)
 +
<source lang="text">http://ws.cloud.topdata.de/finder/ink_toner/modelseries?
 +
  brand_id=%brand_id%&
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<p>you get the Printer-Modelseries as Request.</p>
 +
<p>'''Printer-Types'''</p>
 +
By accessing:
 +
* Printer-Brand ID is required (%brand_id%)
 +
<source lang="text">http://ws.cloud.topdata.de/finder/ink_toner/devicetypes?
 +
  brand_id=%brand_id%&
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<p>you get the Printer-Types as Request.</p>
 +
<p>'''Printer-Models'''</p>
 +
By accessing:
 +
* Printer-Brand ID is required (%brand_id%)
 +
* Printer-Modelserie ID is optional (%modelserie_id%)
 +
* Printer-Type ID is optional (%devicetype_id%)
 +
<source lang="text">http://ws.cloud.topdata.de/finder/ink_toner/models?
 +
  brand_id=%brand_id%&
 +
  modelserie_id=%modelserie_id%&    //devicetype_id=%devicetype_id%&
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<p>you get the Printer-Models as Request.</p>
 +
<p>After choose a Printer-model you can receive the matching supplies over [[Webservice_API#product_accessories|product_accessories]].</p>
 +
<p>'''Printer-Model Textsearch'''</p>
 +
By accessing:
 +
* Searchkeyword is required (%q%)
 +
<source lang="text">http://ws.cloud.topdata.de/finder/ink_toner/search?
 +
  q=%q%&
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<p>you get the Printer-Models as Request.</p>
 +
<p>After choose a Printer-model you can receive the matching supplies over [[Webservice_API#product_accessories|product_accessories]].</p>
 +
<h3>Mapping</h3>
 +
<p>Use the mapping to match quickly your product portfolio with our product portfolio. So it is not necessary to get all the info.</p>
 +
<h4>OEM</h4>
 +
<p>You get all for your user available OEM with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos [[Webservice_API#Produktliste|hear]] </p>
 +
<p>'''Example'''</p>
 +
By accessing:
 +
<source lang="text">http://ws.cloud.topdata.de/match/oem?
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<h4>PCD</h4>
 +
<p>You get all for your user available PCD with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos [[Webservice_API#Produktliste|hear]] </p>
 +
<p>'''Example'''</p>
 +
By accessing:
 +
<source lang="text">http://ws.cloud.topdata.de/match/pcd?
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<h4>EAN</h4>
 +
<p>You get all for your user available EAN with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos [[Webservice_API#Produktliste|hear]] </p>
 +
<p>'''Example'''</p>
 +
By accessing:
 +
<source lang="text">http://ws.cloud.topdata.de/match/ean?
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<h4>Distributor articlenumber</h4>
 +
<p>You get all for your user available Distributor articlenumber with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos [[Webservice_API#Produktliste|hear]] </p>
 +
<p>'''Example'''</p>
 +
By accessing:
 +
<source lang="text">http://ws.cloud.topdata.de/match/distributor?
 +
  uid=%uid%&
 +
  security_key=%security_key%&
 +
  password=%password%&
 +
  version=%version%&
 +
  language=%language%</source>
 +
<h2>Code Example</h2>
 
<h3>PHP</h3>
 
<h3>PHP</h3>
−
Z.B. für das Abrufen von einem Produkt.
+
Example to receive one product.
 
<source lang="php">
 
<source lang="php">
 
<?php
 
<?php

Aktuelle Version vom 1. Dezember 2020, 09:06 Uhr

Sprachen:
Deutsch • ‎English


Webservice Api Basics

Use

By accessing our web service, you automatically declare that you understand and accept our web service use conditions.

Access is logged and evaluated. To save access/bandwidth and server capacity, we recommend minimising queries to the web service via data caching (if possible). We reserve the right to limit access or even to block it if access to the web service exceeds a plausible level.
Access data may not be provided to third parties or displayed publicly. Certain previously agreed data is approved for use as your access details.

Data format:

The web service is returned in the JSON format. We have decided against XML because JSON is currently equally as popular and reduces overhead compared with XML. More Information

Character encoding

data from the web services is released UFT8

Access

The web service data is accessed via a fixed HTTP URL 

http://ws.cloud.topdata.de

Access data is required to access the web service, which is comprised as follows:

  • User ID (%uid%)
  • Passwort (%password%)
  • Sicherheitscode (%security_key%)
The access data must be transferred as an HTTP request each time the web service is accessed. 

?uid=%uid%&security_key=%security_key%&password=%password%

The following HTTP request variables are required to receive a response from the web service. 

?uid=%uid%&security_key=%security_key%&password=%password%&version=%version%&language=%language%

API-Version

If the web service is changed, then a new API version will be provided so that your own application does not always also need to be updated. ATTENTION: We can only provide support for the latest API version.

  • actual APIVersion: 110 
?version=103

Language

The language must be provided as per ISO 639-1 

?language=en

Error Codes

Alle Fehler im Überblick

Fehler Code Fehler Beschreibung
100 Unbekannter Fehler
101 404 - Seite nicht gefunden
102 User ID nicht vorhanden oder nicht valide
103 Sicherheitscode nicht vorhanden oder nicht valide
104 Passwort nicht vorhanden oder nicht valide
105 API-Version nicht vorhanden oder nicht valide
106 Authentifizierung fehlgeschlagen
107 Sprache nicht vorhanden oder nicht valide
108 Template nicht gefunden (Bitte Service informieren)
109 Template Fehler (Bitte Service informieren)
110 Filter nicht vorhanden oder nicht valide
200 Produkt nicht gefunden

Webservice API functions

My products

Sie You will receive all products activated for your access details in the form of a product list.

http://ws.cloud.topdata.de/my_products

Example:

When accessing: 

http://ws.cloud.topdata.de/my_products?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

erhalten Sie die Produktliste als Rückgabe.

My products only with articlenumber

You get all your products as productlist that are activate for your account and where is a articlenumber of a distributor for.

http://ws.cloud.topdata.de/distributor_products

Waregroups

get the complete waregroups as list:

http://ws.cloud.topdata.de/waregroups

Example:

When accessing: 

http://ws.cloud.topdata.de/waregroups?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

you receive the following JSON output: 

{
    "waregroups": [
        {
            "waregroup_id": 1,
            "parent_waregroup_id": 173,
            "waregroup": "Printmedien"
        },
        {
            "waregroup_id": 3,
            "parent_waregroup_id": 162,
            "waregroup": "Etiketten"
        },
        ...
    ]
}

Products

Accesses all products contained in a specific product group. These are output as a Productlist. The product groups ID is required for this. This is can be obtained for example, by accessing the produktgroups or it is stored with one of the products

  • Warengruppen ID (%waregroup_id%) 
http://ws.cloud.topdata.de/waregroup/%warengroup_id%

'Example

When accessing 

http://ws.cloud.topdata.de/waregroup/%warengroup_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned

Produktliste

Die Produktliste enthält alle vom Filter zugelassenen Informationen zu den Produkten und wird bei bestimmten Webservice-Aufrufen zurückgegeben. Es gelten die selben Filterangaben wie beim Produkt

Beispiel

{
 
    "page": {
        "count_products": 694,
        "products_per_page": 50,
        "page": 1,
        "available_pages": 14
    },
    "products": [
        ...
    ]
}

In order to keep traffic and loading times low, the product list is always divided into multiple pages. The individual pages may be accessed via an additional HTTP request variable:

?page=3

The product list includes information about the number of pages, the number of products, the number of products per page, and the currently selected sub-page. The products in the product list are displayed analogously to how individual products are accessed.

more products for one request (since version 103)

You can give the webservice more than one products id to get a productlist for this. Provide the products ids comma seperated in a string. Attention only maximal 50 Product-IDs are allowed(more of this will be ignored). 

http://ws.cloud.topdata.de/product_list

Example

By accessing: 

http://ws.cloud.topdata.de/product_list?products=123456,789012&
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the productlist is returned 2 products(123456 and 789012).

Product

Request one with the from filter allowed informations of the webservice. The product ID is required for this

  • Produkt ID (%products_id%)
  • Filter (%filter%) 
http://ws.cloud.topdata.de/product

Example für den Artikel 92298A von HP

By accessing: 

http://ws.cloud.topdata.de/product/145080?filter=all&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

you receive the following JSON output: 

{
    "product": {
        "products_id": 145080,
        "creation_date": null,
        "edit_date": null,
        "short_description": "Original Hewlett Packard Toner-Kartusche schwarz (92298A, 98A)",
        "manufacturer": "Hewlett Packard (HP)",
        "name": "",
        "oems": [
            "92298A",
            "98A"
        ],
        "eans": [
            "088698005668"
        ],
        "reference_oems": [
            "1538A003",
            "M2473G/A",
            "LN0XX-AA"
        ],
        "bundle_content_oems": [ ],
        "waregroups": [
            {
                "waregroup_id": 57,
                "waregroup": "Toner-Kartuschen",
                "main_waregroup": true,
                "waregroup_tree": [
                    {
                        "waregroup_id": 157,
                        "waregroup": "Bürobedarf"
                    },
                    {
                        "waregroup_id": 173,
                        "waregroup": "Druckerzubehör"
                    },
                    {
                        "waregroup_id": 199,
                        "waregroup": "Laserdrucker"
                    },
                    {
                        "waregroup_id": 56,
                        "waregroup": "Toner"
                    },
                    {
                        "waregroup_id": 57,
                        "waregroup": "Toner-Kartuschen"
                    }
                ]
            }
        ],
        "specifications": [
            {
                "specification_id": 6,
                "specification": "Seitendeckung",
                "attribute_id": 4521,
                "attribute": "bei 5% Seitendeckung",
                "attribute_synonym": "",
                "count": 1
            },
            ...
        ],
        "images": [
            {
                "type_id": 5,
                "type_id_string": "005",
                "type_key": "image_type_pack_and_product",
                "thumb": {
                    "url": "http://image.cloud.topdata.de/t/145080.jpg",
                    "url_own_filename": "http://image.cloud.topdata.de/t/145080/"
                },
                "normal": {
                    "url": "http://image.cloud.topdata.de/n/145080.jpg",
                    "url_own_filename": "http://image.cloud.topdata.de/n/145080/"
                }
            },
            {
                "type_id": 10,
                "type_id_string": "010",
                "type_key": "image_type_pack",
                "thumb": {
                    "url": "http://image.cloud.topdata.de/t/145080.jpg",
                    "url_own_filename": "http://image.cloud.topdata.de/t/145080/"
                },
                "normal": {
                    "url": "http://image.cloud.topdata.de/n/145080.jpg",
                    "url_own_filename": "http://image.cloud.topdata.de/n/145080/"
                }
            },
            ...
        ],
        "bundle_content": [ ],
        "product_alternates": {
            "ws_list_url": "/product_alternates/145080",
            "products": [
                [
                    145070,
                    ...
                ]
            ]
        },
        "product_is_alternate_of": {
            "ws_list_url": "/product_is_alternate_of/145080",
            "products": [
                [
                    145070,
                    ...
                ]
            ]
        },
        "product_accessories": [ ],
        "product_application_in": [ ],
        "distributors": [ ]
    }
}

By the Productlist the products will be transfered in the same way

Filter

since Verion 103 required

The product features can be filtered to minimize the JSON return of the webservice. If not all the information are needed, with teh correct filtering the converting from JSON to an object can save a lot of time in your application.

  • Filter (%filter%) 
?filter=all

The following basic filter available "all". This is in principle given back everything. If you do not need anything, you can use different filters in the table below. This can also be passed separately combined with comma.

?filter=specifications,product_alternates
Legend of unclear variables and filter values
Variable Description Filter
reference_oems If the product is an alternative, then the OEMs for the corresponding products appear here
bundle_content_oems If the product is a bundle, then the OEMs for the individual products appear here
waregroups Waregroups for the product waregroups
specifications specifications for the product specifications
images Images for the product images
bundle_content Falls If the product is a bundle, then the product IDs for the individual products appear here bundle_content
product_alternates Alternative product IDs for the product product_alternates
product_is_alternate_of The product is an alternative of the product IDs indicated product_is_alternate_of
product_accessories Zubehör Accessory product IDs for the product product_accessories
product_same_accessories All product IDs with the same accessories for the product product_same_accessories
product_application_in Product is an accessory of the named product IDs product_application_in
product_same_application_in All product IDs with the same parent product which are an accessory for the product product_same_application_in
child_extra_infos Basic infos for the crossesproducts (manufacturer, name and shortdescription) (since version 102) child_extra_infos
distributors available providers and their article numbers

Access limitations:
Variable Description
images You will only receive images if these are activated for your access details
distributors You will only receive suppliers that are activated for your access details

bundle_content

Accesses the products contained for a certain bundle product. These are output as a Productlist . The product ID of the bundle is required for this.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/bundle_content/%product_id%

Example

By accessing: 

http://ws.cloud.topdata.de/bundle_content/%product_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

product_alternates

Accesses the alternative product for a certain product. These are output as a Productlist . The product ID of the bundle is required for this.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_alternates/%product_id%

Example

By accessing: 

http://ws.cloud.topdata.de/product_alternates/%product_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

product_is_alternate_of

For a certain alternative product, accesses those products for which it is an alternative.These are output as a Productlist . The product ID of the bundle is required for this.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%

'Example

Bay accessing: 

http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

product_accessories

Accesses those products which are an accessory. These are output as a Productlist . The product ID of the bundle is required for this.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_accessories/%product_id%

Example

By accessing 

http://ws.cloud.topdata.de/product_accessories/%product_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

product_same_accessories

Accesses those products for a certain product, which are having the same accessories. These are output as a Productlist . The product ID of the bundle is required for this

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_same_accessories/%product_id%

Example

By accessing 

http://ws.cloud.topdata.de/product_same_accessories/%product_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

product_application_in

Accesses those products for which it is an accessory. These are output as a Productlist . The product ID of the bundle is required for this.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_application_in/%product_id%

Example

By accessing: 

http://ws.cloud.topdata.de/product_application_in/%product_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

product_same_application_in

Accesses those products which are also an accessory. These are output as a Productlist . The product ID of the bundle is required for this.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_same_application_in/%product_id%

Example

By accessing 

http://ws.cloud.topdata.de/product_same_application_in/%product_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

Provider products

Accesses the products for a certain provider. These are output as a Productlist . The product ID of the bundle is required for this.

  • Anbieter ID (%distributor_id%) 
http://ws.cloud.topdata.de/distributor/%distributor_id%

Example

By accessing: 

http://ws.cloud.topdata.de/distributor/%distributor_id%?
  filter=%filter%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

Productfinder

Here you get the data ready to use it as productfinder.

Ink and Toner Finder

The Ink and Toner Finder needs to find the matching consumables for your printer in 2-3 steps.

  • Printer-Brand (Required) Step 1
  • Printer-Modelseries (Optional) Step 2
  • Printer-Types (Optional) Step 2
  • Printer-Model (Required) Step 3
  • Printer-Model Textsearch

Printer-Brand

By accessing: 

http://ws.cloud.topdata.de/finder/ink_toner/brands?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

you get the Printer-Brands as Request.

Printer-Modelseries

By accessing:

  • Printer-Brand ID is required (%brand_id%) 
http://ws.cloud.topdata.de/finder/ink_toner/modelseries?
  brand_id=%brand_id%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

you get the Printer-Modelseries as Request.

Printer-Types

By accessing:

  • Printer-Brand ID is required (%brand_id%) 
http://ws.cloud.topdata.de/finder/ink_toner/devicetypes?
  brand_id=%brand_id%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

you get the Printer-Types as Request.

Printer-Models

By accessing:

  • Printer-Brand ID is required (%brand_id%)
  • Printer-Modelserie ID is optional (%modelserie_id%)
  • Printer-Type ID is optional (%devicetype_id%) 
http://ws.cloud.topdata.de/finder/ink_toner/models?
  brand_id=%brand_id%&
  modelserie_id=%modelserie_id%&    //devicetype_id=%devicetype_id%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

you get the Printer-Models as Request.

After choose a Printer-model you can receive the matching supplies over product_accessories.

Printer-Model Textsearch

By accessing:

  • Searchkeyword is required (%q%) 
http://ws.cloud.topdata.de/finder/ink_toner/search?
  q=%q%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

you get the Printer-Models as Request.

After choose a Printer-model you can receive the matching supplies over product_accessories.

Mapping

Use the mapping to match quickly your product portfolio with our product portfolio. So it is not necessary to get all the info.

OEM

You get all for your user available OEM with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear

Example

By accessing: 

http://ws.cloud.topdata.de/match/oem?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

PCD

You get all for your user available PCD with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear

Example

By accessing: 

http://ws.cloud.topdata.de/match/pcd?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

EAN

You get all for your user available EAN with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear

Example

By accessing: 

http://ws.cloud.topdata.de/match/ean?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

Distributor articlenumber

You get all for your user available Distributor articlenumber with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear

Example

By accessing: 

http://ws.cloud.topdata.de/match/distributor?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

Code Example

PHP

Example to receive one product. 

<?php
 
	//receive data
	$data = file_get_contents('http://ws.cloud.topdata.de/product/145080?uid=...&security_key=...&password=..&version=100&language=de');
 
	//decode json data
	$json = json_decode($data);
 
	//display json object
	var_dump($json);
 
?>
Von „http://wiki.cloud.topdata.de/index.php?title=Webservice_API/en&oldid=385“