<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 auf den Webservice soweit es geht durch Datencaching zu minimieren. Wir behalten uns das Recht vor, Zugänge einzuschränken oder gegebenfalls auch zu sperren, sollte der Zugriff zum Webservice über ein plausibles Mass hinaus gehen.<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>
Der Webservice gibt alles im [http://de.wikipedia.org/wiki/JavaScript_Object_Notation JSON] Format zurück.
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>
<source lang="text">http://ws.cloud.topdata.de</source>
<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 mit übergeben werden als HTTP Request.
</p>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%</source>
<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>
<source lang="text">?uid=%uid%&security_key=%security_key%&password=%password%&version=%version%&language=%language%</source>
<h3>API-Version</h3>
Sollten Änderungen am Webservice statt finden wird eine neue API-Version vergeben. Damit Ihre eigene Applikation nicht immer mit geupdatet werden muss. ACHTUNG Support können wir immer nur für die altuelle API-Version geben.
* Aktuelle APIVersion: '''100'''
<source lang="text">?version=100</source>
<h3>Sprache</h3>
Die Sprache muss nach [http://de.wikipedia.org/wiki/ISO_639#ISO_639-1 ISO 639-1] übergeben werden.
<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)
|-
|''200''||Produkt nicht gefunden
|}

<h2>Webservice API Funktionen</h2>
<h3>Meine Produkte</h3>
<p>Sie erhalten als [[Webservice_API#Produktliste|Produktliste]] alle für Ihren Zugang aktivierten Produkte.</p>
<source lang="text">http://ws.cloud.topdata.de/my_products</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<source lang="text">http://ws.cloud.topdata.de/my_products?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
Erhalten sie die Produktliste als Rückgabe.
<h3>Warengruppen</h3>
<p>Ruft die kompletten Warengruppen als Liste auf:</p>
<source lang="text">http://ws.cloud.topdata.de/waregroups</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<source lang="text">http://ws.cloud.topdata.de/waregroups?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
Erhalten Sie folgende JSON Ausgabe:
<source lang="javascript">
{
"waregroups": [
{
"waregroup_id": 1,
"parent_waregroup_id": 173,
"waregroup": "Printmedien"
},
{
"waregroup_id": 3,
"parent_waregroup_id": 162,
"waregroup": "Etiketten"
},
...
]
}
</source>
<h4>Produkte</h4>
<p>Ruft zu einer bestimmten Warengruppe alle enthalten Produkte 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 hinterlegt bei einem Produkt</p>
* Warengruppen ID (%waregroup_id%)
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<source lang="text">http://ws.cloud.topdata.de/waregroup/%warengroup_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
Erhalten sie die Produktliste als Rückgabe

<h3>Produktliste</h3>
<p>Die Produktliste enthällt alle Information 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>
<source lang="javascript">
{

"page": {
"count_products": 694,
"products_per_page": 50,
"page": 1,
"available_pages": 14
},
"products": [
...
]
}
</source>
<p>Die Produktliste wird immer in mehreren Seiten unterteilt um den traffic und die Ladezeit gering zu halten. Es ist aber möglich über eine weiter HTTP Request Variable die Seiten anzusteuern:</p>
<source lang="text">?page=3</source>
<p>Es sind alle Informationen enthalten wieviel Seiten, wieviel Produkte, wieviel Produkte pro Seite und auf welcher Seite man sich befindet.<br>
Die Produtke in der Produktliste werden wie der Aufruf eines einzelnen Produktes dargestellt.
</p>
<h3>Produkt</h3>
<p>Abruf eines einzelnen Produktes vom Webservice. Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%products_id%)
<source lang="text">http://ws.cloud.topdata.de/product</source>
<p>'''Beispiel''' für den Artikel 92298A von HP</p>
Bei Aufruf von:
<source lang="text">http://ws.cloud.topdata.de/product/145080?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
Erhalten Sie folgende JSON Ausgabe:
<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>Bei der [[Webservice_API#Produktliste|Produktliste]] werden die Produkte genause ü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 sind hier die Produkte 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 Alternative von den genannten Produkt IDs
|-
|[[Webservice_API#product_accessories|''product_accessories'']]||Zubehör Produkt IDs zum Produkt
|-
|[[Webservice_API#product_application_in|''product_application_in'']]||Produkt ist Zubehör von den genannten Produkt IDs
|-
|''distributors''||verfügbare Anbieter und deren Artikelnummern
|}<br>
{| class="wikitable"
|+ Zugangseinschränkungen
!Variable!!Beschreibung
|-
|''images''||Bilder erhalten Sie nur wenn diese für Ihren Zugang aktiviert wurden
|-
|''distributors''||Sie erhalten immer 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%)
<source lang="text">http://ws.cloud.topdata.de/bundle_content/%product_id%</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>
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%)
<source lang="text">http://ws.cloud.topdata.de/product_alternates/%product_id%</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>
Erhalten sie die Produktliste als Rückgabe.

<h4>''product_is_alternate_of''</h4>
<p>Ruft zu einem bestimmten Alternativprodukt die Produkte ab wozu es alternativ ist. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
Dafür ist die Produkt ID notwendig.</p>
* Produkt ID (%product_id%)
<source lang="text">http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>
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%)
<source lang="text">http://ws.cloud.topdata.de/product_accessories/%product_id%</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>
Erhalten sie die Produktliste als Rückgabe.

<h4>''product_application_in''</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%)
<source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<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>
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 Produkt einsehbar.</p>
* Anbieter ID (%distributor_id%)
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%</source>
<p>'''Beispiel'''</p>
Bei Aufruf von:
<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%?
uid=%uid%&
security_key=%security_key%&
password=%password%&
version=%version%&
language=%language%</source>
Erhalten sie die Produktliste als Rückgabe.
<h2>Code Beispiele</h2>
<h3>PHP</h3>
Z.B. für das abrufen von einem Produkt.
<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>