Webservice API/en

2020-02-19T10:25:34Z

Christian Täuber:

<languages />
<br />
<h2>Webservice Api Basics</h2>
<h3>Use</h3>
<p> By accessing our web service, you automatically declare that you understand and accept our [[web service use conditions]].<br /><br />
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.<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>
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.
[http://de.wikipedia.org/wiki/JavaScript_Object_Notation#Unterschied_zu_XML More Information]
</p>
<h3> Character encoding </h3>
<p>
data from the web services is released [http://de.wikipedia.org/wiki/UTF-8 UFT8]
</p>
<h3>Access</h3>
<p>
The web service data is accessed via a fixed HTTP URL </p>
<source lang="text">http://ws.cloud.topdata.de</source>
<p> 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.
</p>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%</source>
<p> The following HTTP request variables are required to receive a response from the web service.
* [[Webservice_API#API-Version|API-Version]] (''%version%'')
* [[Webservice_API#Sprache|Sprache]] (''%language%'')
</p>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%&version=%version%&language=%language%</source>
<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.
* actual APIVersion: '''107'''
<source lang="text">?version=103</source>
<h3>Language</h3>
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>
<h3>Error Codes</h3>
Alle Fehler im Überblick
{| class="wikitable"
!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
|}

<h2>Webservice API functions</h2>
<h3>My products</h3>
<p>Sie You will receive all products activated for your access details in the form of a product list.</p>
<source lang="text">http://ws.cloud.topdata.de/my_products</source>
<p>''' Example: '''</p>
When accessing:
<source lang="text">http://ws.cloud.topdata.de/my_products?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
erhalten Sie die Produktliste als Rückgabe.
<h4>My products only with articlenumber</h4>
<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>
<p>''' Example: '''</p>
When accessing:
<source lang="text">http://ws.cloud.topdata.de/waregroups?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
you receive the following JSON output:
<source lang="javascript">
{
"waregroups": [
{
"waregroup_id": 1,
"parent_waregroup_id": 173,
"waregroup": "Printmedien"
},
{
"waregroup_id": 3,
"parent_waregroup_id": 162,
"waregroup": "Etiketten"
},
...
]
}
</source>
<h4>Products</h4>
<p> Accesses all products contained in a specific product group. These are output as a [[Webservice_API#Produktliste|Productlist]].
The product groups ID is required for this. This is can be obtained for example, by accessing the [[Webservice_API#Warengruppen|produktgroups]] or it is stored with one of the products </p>
* Warengruppen ID (%waregroup_id%)
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%</source>
<p>'''Example''</p>
When accessing
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned

<h3>Produktliste</h3>
<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|Warengruppen Produkte]]
* [[Webservice_API#bundle_content|''bundle_content'']]
* [[Webservice_API#product_alternates|''product_alternates'']]
* [[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]
* [[Webservice_API#product_accessories|''product_accessories'']]
* [[Webservice_API#product_application_in|''product_application_in'']]
* [[Webservice_API#Anbieter Produkte|Anbieter Produkte]]
<p>'''Beispiel'''</p>
<source lang="javascript">
{

"page": {
"count_products": 694,
"products_per_page": 50,
"page": 1,
"available_pages": 14
},
"products": [
...
]
}
</source>
<p> 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:</p>
<source lang="text">?page=3</source>
<p> 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.
</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>
<p>Request one with the from filter allowed informations of the webservice. The product ID is required for this</p>
* Produkt ID (%products_id%)
* Filter (%filter%)
<source lang="text">http://ws.cloud.topdata.de/product</source>
<p>'''Example''' für den Artikel 92298A von HP</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/product/145080?filter=all&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
you receive the following JSON output:
<source lang="javascript">
{
"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": [ ]
}
}
</source>

<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"
|+ 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
|-
|[[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||product_alternates

|-
|[[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_same_accessories|''product_same_accessories'']]|| All product IDs with the same accessories for the product||product_same_accessories
|-
|[[Webservice_API#product_application_in|''product_application_in'']]|| Product is an accessory of the named product IDs||product_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||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||
|}<br />
{| class="wikitable"
|+ 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
|}

<h4>''bundle_content''</h4>
<p> Accesses the products contained for a certain bundle product. These are output as a [[Webservice_API#Produktliste|Productlist]] .
The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_alternates''</h4>
<p> Accesses the alternative product for a certain product. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_is_alternate_of''</h4>
<p> For a certain alternative product, accesses those products for which it is an alternative.These are output as a [[Webservice_API#Produktliste|Productlist]] .
The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%</source>
<p>'''Example''</p>
Bay accessing:
<source lang="text">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%</source>
the product list is returned.

<h4>''product_accessories''</h4>
<p> Accesses those products which are an accessory. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%</source>
<p>'''Example'''</p>
By accessing
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_same_accessories''</h4>
<p> Accesses those products for a certain product, which are having the same accessories. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this </p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%</source>
<p>'''Example'''</p>
By accessing
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_application_in''</h4>
<p> Accesses those products for which it is an accessory. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.
</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_same_application_in''</h4>
<p> Accesses those products which are also an accessory. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_same_application_in/%product_id%</source>
<p>'''Example'''</p>
By accessing
<source lang="text">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%</source>
the product list is returned.

<h3>Provider products</h3>
<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>
* Anbieter ID (%distributor_id%)
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<h3>Productfinder</h3>
<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>
Example to receive one product.
<source lang="php">
<?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);

?>
</source>

2016-02-19T15:19:49Z

Christian Täuber:

Webservice API/en

2016-02-19T15:19:49Z

2016-02-19T15:14:09Z

Christian Täuber:

{| class="wikitable"
|+ 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
|-
|[[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||product_alternates

|-
|[[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_same_accessories|''product_same_accessories'']]|| All product IDs with the same accessories for the product||product_same_accessories
|-
|[[Webservice_API#product_application_in|''product_application_in'']]|| Product is an accessory of the named product IDs||product_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||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||
|}<br />
{| class="wikitable"
|+ 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
|}

Webservice API/en

2016-02-19T15:10:24Z

Christian Täuber: Die Seite wurde neu angelegt: „<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 informat…“

<languages />
<br />
<h2>Webservice Api Basics</h2>
<h3>Use</h3>
<p> By accessing our web service, you automatically declare that you understand and accept our [[web service use conditions]].<br /><br />
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.<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>
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.
[http://de.wikipedia.org/wiki/JavaScript_Object_Notation#Unterschied_zu_XML More Information]
</p>
<h3> Character encoding </h3>
<p>
data from the web services is released [http://de.wikipedia.org/wiki/UTF-8 UFT8]
</p>
<h3>Access</h3>
<p>
The web service data is accessed via a fixed HTTP URL </p>
<source lang="text">http://ws.cloud.topdata.de</source>
<p> 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.
</p>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%</source>
<p> The following HTTP request variables are required to receive a response from the web service.
* [[Webservice_API#API-Version|API-Version]] (''%version%'')
* [[Webservice_API#Sprache|Sprache]] (''%language%'')
</p>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%&version=%version%&language=%language%</source>
<h3>API-Version</h3>
Sollten Änderungen am Webservice stattfinden, wird eine neue API-Version vergeben, damit Ihre eigene Applikation nicht immer mit geupdatet werden muss. ACHTUNG, Support unsererseits kann nur für die jeweils aktuelle API-Version geleistet werden.
* Aktuelle APIVersion: '''103'''
<source lang="text">?version=103</source>
<h3>Language</h3>
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>
<h3>Error Codes</h3>
Alle Fehler im Überblick
{| class="wikitable"
!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
|}

<h2>Webservice API functions</h2>
<h3>My products</h3>
<p>Sie You will receive all products activated for your access details in the form of a product list.</p>
<source lang="text">http://ws.cloud.topdata.de/my_products</source>
<p>''' Example: '''</p>
When accessing:
<source lang="text">http://ws.cloud.topdata.de/my_products?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
erhalten Sie die Produktliste als Rückgabe.
<h4>My products only with articlenumber</h4>
<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>
<p>''' Example: '''</p>
When accessing:
<source lang="text">http://ws.cloud.topdata.de/waregroups?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
you receive the following JSON output:
<source lang="javascript">
{
"waregroups": [
{
"waregroup_id": 1,
"parent_waregroup_id": 173,
"waregroup": "Printmedien"
},
{
"waregroup_id": 3,
"parent_waregroup_id": 162,
"waregroup": "Etiketten"
},
...
]
}
</source>
<h4>Products</h4>
<p> Accesses all products contained in a specific product group. These are output as a [[Webservice_API#Produktliste|Productlist]].
The product groups ID is required for this. This is can be obtained for example, by accessing the [[Webservice_API#Warengruppen|produktgroups]] or it is stored with one of the products </p>
* Warengruppen ID (%waregroup_id%)
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%</source>
<p>'''Example''</p>
When accessing
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned

<h3>Produktliste</h3>
<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|Warengruppen Produkte]]
* [[Webservice_API#bundle_content|''bundle_content'']]
* [[Webservice_API#product_alternates|''product_alternates'']]
* [[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]
* [[Webservice_API#product_accessories|''product_accessories'']]
* [[Webservice_API#product_application_in|''product_application_in'']]
* [[Webservice_API#Anbieter Produkte|Anbieter Produkte]]
<p>'''Beispiel'''</p>
<source lang="javascript">
{

"page": {
"count_products": 694,
"products_per_page": 50,
"page": 1,
"available_pages": 14
},
"products": [
...
]
}
</source>
<p> 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:</p>
<source lang="text">?page=3</source>
<p> 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.
</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>
<p>Request one with the from filter allowed informations of the webservice. The product ID is required for this</p>
* Produkt ID (%products_id%)
* Filter (%filter%)
<source lang="text">http://ws.cloud.topdata.de/product</source>
<p>'''Example''' für den Artikel 92298A von HP</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/product/145080?filter=all&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
you receive the following JSON output:
<source lang="javascript">
{
"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": [ ]
}
}
</source>

<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"
|+ Legende uneindeutiger Variablen und Filterangaben
!Variable!!Beschreibung!!Filterkeys
|-
|''reference_oems''||Falls das Produkt eine Alternative ist, kommen hier die OEMs zu den entsprechenden Produkten||
|-
|''bundle_content_oems''||Falls das Produkt ein Bundle ist, kommen hier die OEMs der Einzelprodukte||
|-
|''waregroups''||Warengruppen zum Produktes||waregroups
|-
|''specifications''||Spezifikationen des Produktes||specifications
|-
|''images''||Bilder zum Produkt||images
|-
|[[Webservice_API#bundle_content|''bundle_content'']]||Falls das Produkt ein Bundle ist, kommen hier die Produkt IDs der Einzelprodukte||bundle_content
|-
|[[Webservice_API#product_alternates|''product_alternates'']]||Alternative Produkt IDs zum Produkt||product_alternates
|-
|[[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]||Produkt ist eine Alternative der genannten Produkt IDs||product_is_alternate_of
|-
|[[Webservice_API#product_accessories|''product_accessories'']]||Zubehör Produkt IDs zum Produkt||product_accessories
|-
|[[Webservice_API#product_same_accessories|''product_same_accessories'']]||Alle Produkt IDs mit dem selben Zubehör zum Produkt||product_same_accessories
|-
|[[Webservice_API#product_application_in|''product_application_in'']]||Produkt ist Zubehör von den genannten Produkt IDs||product_application_in
|-
|[[Webservice_API#product_same_application_in|''product_same_application_in'']]||Alle Produkt IDs mit dem selben Elternprodukt wozu es ein Zubehör ist vom Produkt||product_same_application_in
|-
|''child_extra_infos''||Grundinfos zu den Verknüpften Produkten (Hersteller, Produktname und Kurzbeschreibung) (ab Verion 102)||child_extra_infos
|-
|''distributors''||verfügbare Anbieter und deren Artikelnummern
|}<br>
{| class="wikitable"
|+ Zugangseinschränkungen
!Variable!!Beschreibung
|-
|''images''||Bilder erhalten Sie nur dann, wenn diese für Ihren Zugang aktiviert wurden
|-
|''distributors''||Sie erhalten jeweils nur die Lieferanten, die für Ihren Zugang aktiviert wurden
|}

<h4>''bundle_content''</h4>
<p> Accesses the products contained for a certain bundle product. These are output as a [[Webservice_API#Produktliste|Productlist]] .
The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_alternates''</h4>
<p> Accesses the alternative product for a certain product. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_is_alternate_of''</h4>
<p> For a certain alternative product, accesses those products for which it is an alternative.These are output as a [[Webservice_API#Produktliste|Productlist]] .
The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%</source>
<p>'''Example''</p>
Bay accessing:
<source lang="text">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%</source>
the product list is returned.

<h4>''product_accessories''</h4>
<p> Accesses those products which are an accessory. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%</source>
<p>'''Example'''</p>
By accessing
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_same_accessories''</h4>
<p> Accesses those products for a certain product, which are having the same accessories. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this </p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%</source>
<p>'''Example'''</p>
By accessing
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_application_in''</h4>
<p> Accesses those products for which it is an accessory. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.
</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
the product list is returned.

<h4>''product_same_application_in''</h4>
<p> Accesses those products which are also an accessory. These are output as a [[Webservice_API#Produktliste|Productlist]] . The product ID of the bundle is required for this.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_same_application_in/%product_id%</source>
<p>'''Example'''</p>
By accessing
<source lang="text">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%</source>
the product list is returned.

<h3>Provider products</h3>
<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>
* Anbieter ID (%distributor_id%)
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%</source>
<p>'''Example'''</p>
By accessing:
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%?
filter=%filter%&
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<h3>Productfinder</h3>
<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>Nutzen Sie das Mapping um schnell unseren Produktbestand mit Ihrem abzugeleichen. So ist es nicht nötig sich alle Produktinfos zu holen.</p>
<h4>OEM</h4>
<p>Sie erhalten alle für Ihren User zugelassenen OEMs mit dazugehöriger Produkt-ID. Sie erhalten diese in 1000er Blöcken. Mit "page" können Sie diese durchgehen. Mehr infos [[Webservice_API#Produktliste|hier]] </p>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>Sie erhalten alle für Ihren User zugelassenen PCDs mit dazugehöriger Produkt-ID. Sie erhalten diese in 1000er Blöcken. Mit "page" können Sie diese durchgehen. Mehr infos [[Webservice_API#Produktliste|hier]] </p>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>Sie erhalten alle für Ihren User zugelassenen EANs mit dazugehöriger Produkt-ID. Sie erhalten diese in 1000er Blöcken. Mit "page" können Sie diese durchgehen. Mehr infos [[Webservice_API#Produktliste|hier]] </p>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<source lang="text">http://ws.cloud.topdata.de/match/ean?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<h4>Lieferanten Artikel-Nr</h4>
<p>Sie erhalten alle für Ihren User zugelassenen Lieferanten Artikel-Nr mit dazugehöriger Produkt-ID. Sie erhalten diese in 1000er Blöcken. Mit "page" können Sie diese durchgehen. Mehr infos [[Webservice_API#Produktliste|hier]] </p>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>
Example to receive one product.
<source lang="php">
<?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);

?>
</source>

2016-02-19T13:26:24Z

Christian Täuber:

<languages />
<br />
<translate>

<h2>Webservice API Grundlagen</h2>
<h3>Nutzung</h3>
<p>Mit dem Zugang zum Webservice haben Sie automatisch unsere [[Webservice Nutzungsbedingungen]] verstanden und akzeptiert.<br><br>
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>
Zugangsdaten dürfen nicht an Dritte weitergegeben oder öffentlich dargestellt werden.<br>
Für Ihre Zugangsdaten sind bestimmte, vorher vereinbarte, Daten freigegeben.
</p>
<h3>Datenformat</h3>
<p>
Die Rückgabe des Webservices erfolgt im [http://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] Format.
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]
</p>
<h3>Zeichencodierung</h3>
<p>
Die Ausgabe der Daten des Webservices erfolgt in [http://de.wikipedia.org/wiki/UTF-8 UFT8]
</p>
<h3>Zugang</h3>
<p>
Der Abruf der Webservice-Daten erfolgt über eine feste HTTP URL.
</p>
</translate>
<source lang="text">http://ws.cloud.topdata.de</source>
<translate>

<p>Für den Zugang zum Webservice werden Zugangsdaten benötigt, die sich wie folgt zusammensetzen:
* User ID (''%uid%'')
* Passwort (''%password%'')
* Sicherheitscode (''%security_key%'')
Die Zugangsdaten müssen bei jedem Aufruf des Webservices als HTTP Request mit übergeben werden.
</p>
</translate>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%</source>
<translate>

<p>Weiter sind folgende HTTP Request Variablen Pflicht, um eine Antwort vom Webservice zu erhalten
* [[Webservice_API#API-Version|API-Version]] (''%version%'')
* [[Webservice_API#Sprache|Sprache]] (''%language%'')
</p>
</translate>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%&version=%version%&language=%language%</source>
<translate>

<h3>API-Version</h3>
Sollten Änderungen am Webservice stattfinden, wird eine neue API-Version vergeben, damit Ihre eigene Applikation nicht immer mit geupdatet werden muss. ACHTUNG, Support unsererseits kann nur für die jeweils aktuelle API-Version geleistet werden.
* Aktuelle APIVersion: '''103'''
</translate>
<source lang="text">?version=103</source>
<translate>

<h3>Sprache</h3>
Die Sprache muss nach [http://de.wikipedia.org/wiki/ISO_639#ISO_639-1 ISO 639-1] übergeben werden.
</translate>
<source lang="text">?language=en</source>
<translate>

<h3>Error Codes</h3>
Alle Fehler im Überblick
{| class="wikitable"
!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)
|-
|''200''||Produkt nicht gefunden
|}


<h2>Webservice API Funktionen</h2>
<h3>Meine Produkte</h3>
<p>Sie erhalten alle für Ihren Zugang aktivierten Produkte als [[Webservice_API#Produktliste|Produktliste]].</p>
</translate>
<source lang="text">http://ws.cloud.topdata.de/my_products</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/my_products?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe.
</translate>
<translate>
<h4>Meine Produkte nur mit Artikel-Nr.</h4>
<p>Sie erhalten alle für Ihren Zugang aktivierten Produkte als [[Webservice_API#Produktliste|Produktliste]] wo eine Artikel-Nr. eines zugelassenen Anbieters hinterlegt ist.</p>
<source lang="text">http://ws.cloud.topdata.de/distributor_products</source>
<h3>Warengruppen</h3>
<p>ruft die kompletten Warengruppen als Liste auf:</p>
</translate>
<source lang="text">http://ws.cloud.topdata.de/waregroups</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/waregroups?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie folgende JSON Ausgabe:
</translate>
<source lang="javascript">
{
"waregroups": [
{
"waregroup_id": 1,
"parent_waregroup_id": 173,
"waregroup": "Printmedien"
},
{
"waregroup_id": 3,
"parent_waregroup_id": 162,
"waregroup": "Etiketten"
},
...
]
}
</source>
<translate>

<h4>Produkte</h4>
<p>Ruft alle enthalten Produkte zu einer bestimmten Warengruppe ab. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Warengruppen ID notwendig. Diese erhalten Sie z.B. aus dem Aufruf der [[Webservice_API#Warengruppen|Warengruppen]] oder sie ist bei einem der Produkte hinterlegt</p>
* Warengruppen ID (%waregroup_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe


<h3>Produktliste</h3>
<p>Die Produktliste enthält alle Informationen zu den Produkten und wird bei bestimmten Webservice-Aufrufen zurückgegeben.</p>
* [[Webservice_API#Warengruppen|Warengruppen Produkte]]
* [[Webservice_API#bundle_content|''bundle_content'']]
* [[Webservice_API#product_alternates|''product_alternates'']]
* [[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]
* [[Webservice_API#product_accessories|''product_accessories'']]
* [[Webservice_API#product_application_in|''product_application_in'']]
* [[Webservice_API#Anbieter Produkte|Anbieter Produkte]]
<p>'''Beispiel'''</p>
</translate>
<source lang="javascript">
{

"page": {
"count_products": 694,
"products_per_page": 50,
"page": 1,
"available_pages": 14
},
"products": [
...
]
}
</source>
<translate>

<p>Um den Traffic und die Ladezeit gering zu halten, wird die Produktliste immer in mehrere Seiten unterteilt. Die einzelnen Seiten können über eine weitere HTTP Request Variable angesteuert werden:</p>
<source lang="text">?page=3</source>
<p>Die Produktliste beinhaltet Informationen über die Anzahl der Seiten, die Anzahl der Produkte, die Anzahl der Produkte pro Seite sowie die aktuell ausgewählte Unterseite.<br>
Die Produkte in der Produktliste werden analog zum Aufruf eines einzelnen Produktes dargestellt.
</p>
<p>'''mehrere Produkte auf einmal abrufen (ab Version 103)'''</p>
<p>Sie können auch einer Webservice Abfrage mehrere Produkt-IDs übergeben um dazu die Produktliste zu erhalten.
Diese werden per Komma getrennten String übergeben. ACHTUNG es sind maxmimal 50 Produkt-IDs zugelassen (mehr werden ignoriert).
</p>
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_list</source>
<translate>
<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_list?products=123456,789012
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>
erhalten Sie die Produktliste mit 2 Produkten (123456 und 789012) als Rückgabe.
<h3>Produkt</h3>
<p>Abruf eines einzelnen Produktes vom Webservice. Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%products_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/product</source>
<translate>

<p>'''Beispiel''' für den Artikel 92298A von HP</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product/145080?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie folgende JSON Ausgabe:
</translate>
<source lang="javascript">
{
"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": [ ]
}
}
</source>
<translate>

<p>Bei der [[Webservice_API#Produktliste|Produktliste]] werden die Produkte ebenso übergeben.<br><br></p>


{| class="wikitable"
|+ Legende uneindeutiger Variablen
!Variable!!Beschreibung
|-
|''reference_oems''||Falls das Produkt eine Alternative ist, kommen hier die OEMs zu den entsprechenden Produkten
|-
|''bundle_content_oems''||Falls das Produkt ein Bundle ist, kommen hier die OEMs der Einzelprodukte
|-
|[[Webservice_API#bundle_content|''bundle_content'']]||Falls das Produkt ein Bundle ist, kommen hier die Produkt IDs der Einzelprodukte
|-
|[[Webservice_API#product_alternates|''product_alternates'']]||Alternative Produkt IDs zum Produkt
|-
|[[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]||Produkt ist eine Alternative der genannten Produkt IDs
|-
|[[Webservice_API#product_accessories|''product_accessories'']]||Zubehör Produkt IDs zum Produkt
|-
|[[Webservice_API#product_same_accessories|''product_same_accessories'']]||Alle Produkt IDs mit dem selben Zubehör zum Produkt
|-
|[[Webservice_API#product_application_in|''product_application_in'']]||Produkt ist Zubehör von den genannten Produkt IDs
|-
|[[Webservice_API#product_same_application_in|''product_same_application_in'']]||Alle Produkt IDs mit dem selben Elternprodukt wozu es ein Zubehör ist vom Produkt
|-
|''distributors''||verfügbare Anbieter und deren Artikelnummern
|}<br>
{| class="wikitable"
|+ Zugangseinschränkungen
!Variable!!Beschreibung
|-
|''images''||Bilder erhalten Sie nur dann, wenn diese für Ihren Zugang aktiviert wurden
|-
|''distributors''||Sie erhalten jeweils nur die Lieferanten, die für Ihren Zugang aktiviert wurden
|}


<h4>''bundle_content''</h4>
<p>Ruft zu einem bestimmten Bundle-Produkt die enthalten Produkte ab. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID des Bundles notwendig.</p>
* Produkt ID (%product_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe.


<h4>''product_alternates''</h4>
<p>Ruft zu einem bestimmten Produkt die Alternativprodukte ab. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%product_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe.


<h4>''product_is_alternate_of''</h4>
<p>Ruft zu einem bestimmten Alternativprodukt diejenigen Produkte ab, zu denen es alternativ ist. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%product_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten sie die Produktliste als Rückgabe.


<h4>''product_accessories''</h4>
<p>Ruft zu einem bestimmten Produkt die Zubehörprodukte ab. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%product_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe.


<h4>''product_same_accessories''</h4>
<p>Ruft zu einem bestimmten Produkt die Produkte ab mit den dem selben Zubehör. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%product_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_same_accessories/%product_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe.


<h4>''product_application_in''</h4>
<p>Ruft zu einem bestimmten Produkt die Produkte ab wozu es ein Zubehör ist. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%product_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe.


<h4>''product_same_application_in''</h4>
<p>Ruft zu einem bestimmten Produkt die Produkte ab die genauso ein Zubehör sind. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%product_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_same_application_in/%product_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/product_same_application_in/%product_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

erhalten Sie die Produktliste als Rückgabe.


<h3>Anbieter Produkte</h3>
<p>Ruft zu einem bestimmten Anbieter die Produkte ab. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Anbieter ID notwendig. Diese ist z.B. bei einem der Produkte einsehbar.</p>
* Anbieter ID (%distributor_id%)
</translate>
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%</source>
<translate>

<p>'''Beispiel'''</p>
Bei Aufruf von:
</translate>
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
<translate>

<h3>Produktfinder</h3>
<p>Hier werden die Daten fertig aufbereitet zurück geliefert um diese direkt als Produktfinder zu verwenden.</p>
<h4>''Tinten-Toner Finder''</h4>
<p>Der Tinten Toner Finder dient dafür sein passendes Verbrauchsmaterial zu seinem Drucker zu finden. Das ganze passiert in 2-3 Schritten.</p>
* Drucker-Hersteller (Auswahl Pflicht) ''Schritt 1''
* Drucker-Modellserien (Auswahl Optional) ''Schritt 2''
* Drucker-Typen (Auswahl Optional) ''Schritt 2''
* Drucker-Modelle (Auswahl Pflicht) ''Schritt 3''
* Drucker-Modell Textsuche
<p>'''Drucker-Hersteller'''</p>
Bei Aufruf von:
</translate>
<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>
<translate>

<p>erhalten Sie die Drucker-Hersteller als Rückgabe.</p>
<p>'''Drucker-Modellserien'''</p>
Bei Aufruf von:
* Drucker-Hersteller ID wird benötigt (%brand_id%)
</translate>
<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>
<translate>

<p>erhalten Sie die Modellserien als Rückgabe.</p>
<p>'''Drucker-Typen'''</p>
Bei Aufruf von:
* Drucker-Hersteller ID wird benötigt (%brand_id%)
</translate>
<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>
<translate>

<p>erhalten Sie die Drucker-Typen als Rückgabe.</p>
<p>'''Drucker-Modelle'''</p>
Bei Aufruf von:
* Drucker-Hersteller ID wird benötigt (%brand_id%)
* Drucker-Modellserien ID optional benötigt (%modelserie_id%)
* Drucker-Typen ID optional benötigt (%devicetype_id%)
</translate>
<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>
<translate>

<p>erhalten Sie die Drucker-Modelle als Rückgabe.</p>
<p>Nach auswahl eines Druckers lässt sich das passende Verbrauchsmaterial über [[Webservice_API#product_accessories|product_accessories]] aufrufen.</p>
<p>'''Drucker-Modell Textsuche'''</p>
Bei Aufruf von:
* Suchbegriff wird benötigt (%q%)
</translate>
<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>
<translate>

<p>erhalten Sie die Drucker-Modelle als Rückgabe.</p>
<p>Nach auswahl eines Druckers lässt sich das passende Verbrauchsmaterial über [[Webservice_API#product_accessories|product_accessories]] aufrufen.</p>
</translate>
<translate>

<h2>Code Beispiele</h2>
<h3>PHP</h3>
Z.B. für das Abrufen von einem Produkt.
</translate>
<source lang="php">
<?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);

?>
</source>

Translations:Webservice API/19/en

2015-11-30T13:42:24Z

Christian Täuber:

<p>By the [[Webservice_API#Produktliste|Productlist]] the products will be transfered in the same way<br /><br /></p>