Webservice API/en: Unterschied zwischen den Versionen
(Die Seite wurde neu angelegt: „<p>'''Example'''</p> By accessing:“) |
(Die Seite wurde neu angelegt: „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 pro…“) |
||
Zeile 159: | Zeile 159: | ||
} | } | ||
</source> | </source> | ||
− | <p> | + | <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> | <source lang="text">?page=3</source> | ||
− | <p> | + | <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> | </p> | ||
− | |||
− | |||
− | |||
<source lang="text">http://ws.cloud.topdata.de/product_list</source> | <source lang="text">http://ws.cloud.topdata.de/product_list</source> | ||
<p>'''Example'''</p> | <p>'''Example'''</p> | ||
Zeile 177: | Zeile 178: | ||
version=%version%& | version=%version%& | ||
language=%language%</source> | language=%language%</source> | ||
− | + | the productlist is returned 2 products(123456 and 789012). | |
− | <h3> | + | <h3>Product</h3> |
− | <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%) | * Filter (%filter%) | ||
Zeile 319: | Zeile 320: | ||
<source lang="text">?filter=specifications,product_alternates</source> | <source lang="text">?filter=specifications,product_alternates</source> | ||
{| class="wikitable" | {| class="wikitable" | ||
− | |+ | + | |+ Legende uneindeutiger Variablen und Filterangaben |
− | !Variable!! | + | !Variable!!Beschreibung!!Filterkeys |
|- | |- | ||
− | |''reference_oems''|| | + | |''reference_oems''||Falls das Produkt eine Alternative ist, kommen hier die OEMs zu den entsprechenden Produkten|| |
|- | |- | ||
− | |''bundle_content_oems''|| | + | |''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# | + | |[[Webservice_API#bundle_content|''bundle_content'']]||Falls das Produkt ein Bundle ist, kommen hier die Produkt IDs der Einzelprodukte||bundle_content |
|- | |- | ||
− | |[[Webservice_API# | + | |[[Webservice_API#product_alternates|''product_alternates'']]||Alternative Produkt IDs zum Produkt||product_alternates |
|- | |- | ||
− | |[[Webservice_API# | + | |[[Webservice_API#product_is_alternate_of|''product_is_alternate_of'']]||Produkt ist eine Alternative der genannten Produkt IDs||product_is_alternate_of |
|- | |- | ||
− | |[[Webservice_API# | + | |[[Webservice_API#product_accessories|''product_accessories'']]||Zubehör Produkt IDs zum Produkt||product_accessories |
|- | |- | ||
− | |''distributors''|| | + | |[[Webservice_API#product_same_accessories|''product_same_accessories'']]||Alle Produkt IDs mit dem selben Zubehör zum Produkt||product_same_accessories |
− | |}<br | + | |- |
+ | |[[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" | {| class="wikitable" | ||
− | |+ | + | |+ Zugangseinschränkungen |
− | + | !Variable!!Beschreibung | |
− | !Variable!! | + | |
|- | |- | ||
− | |''images''|| | + | |''images''||Bilder erhalten Sie nur dann, wenn diese für Ihren Zugang aktiviert wurden |
|- | |- | ||
− | |''distributors''|| | + | |''distributors''||Sie erhalten jeweils nur die Lieferanten, die für Ihren Zugang aktiviert wurden |
|} | |} | ||
Version vom 19. Februar 2016, 15:58 Uhr
Inhaltsverzeichnis
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%)
?uid=%uid%&security_key=%security_key%&password=%password%
The following HTTP request variables are required to receive a response from the web service.
- API-Version (%version%)
- Sprache (%language%)
?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: 101
?version=103
Language
The language must be provided as per ISO 639-1
?language=en
Error Codes
Overview of all errors:
Error Code | Description |
---|---|
100 | unknown error |
101 | 404 – page not found |
102 | User ID not available or not valid |
103 | safety code not available or not valid |
104 | password not available or not valid |
105 | API-Version not available or not valid |
106 | authentication failed |
107 | language not available or not valid |
108 | template not found (please inform service) |
109 | template error (please inform service) |
200 | product not found |
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%
the product list is returned.
Product groups
Accesses the complete product groups as a list::
Meine Produkte nur mit Artikel-Nr.
Sie erhalten alle für Ihren Zugang aktivierten Produkte als Produktliste wo eine Artikel-Nr. eines zugelassenen Anbieters hinterlegt ist.
http://ws.cloud.topdata.de/distributor_products
Warengruppen
ruft die kompletten Warengruppen als Liste auf:
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
Productlist
Die The product list includes all information about the products and is returned when certain web services are accessed.
- waregroup_products
- bundle_content
- product_alternates
- product_is_alternate_of
- product_accessories
- product_application_in
- provider_products
Example
{ "page": { "count_products": 694, "products_per_page": 50, "page": 1, "available_pages": 14 }, "products": [ ... ] }
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:
?page=3
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.
Die Produkte in der Produktliste werden analog zum Aufruf eines einzelnen Produktes dargestellt.
mehrere Produkte auf einmal abrufen (ab Version 103)
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).
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
ab Verion 103 pflicht
Die Produkteigenschaften lassen sich filtern um die JSON Rückgabe des Webservice zu minimieren. Wenn nicht alle Informationen benötigt werden, kann korrektes Filtern beim umwandeln von JSON in ein Objekt in Ihrer Anwendung sehr viel Zeit sparen.
- Filter (%filter%)
?filter=all
Folgender Grundfilter steht zur Verfügung "all". Damit wird Grundsätzlich alles zurück gegeben. Wenn Sie nicht alles benötigen können Sie aus der folgenden Tabelle andere Filter benutzen. Diese lassen sich auch kombiniert übergeben mit komma getrennt.
?filter=specifications,product_alternates
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 |
bundle_content | Falls das Produkt ein Bundle ist, kommen hier die Produkt IDs der Einzelprodukte | bundle_content |
product_alternates | Alternative Produkt IDs zum Produkt | product_alternates |
product_is_alternate_of | Produkt ist eine Alternative der genannten Produkt IDs | product_is_alternate_of |
product_accessories | Zubehör Produkt IDs zum Produkt | product_accessories |
product_same_accessories | Alle Produkt IDs mit dem selben Zubehör zum Produkt | product_same_accessories |
product_application_in | Produkt ist Zubehör von den genannten Produkt IDs | product_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 |
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 |
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
Nutzen Sie das Mapping um schnell unseren Produktbestand mit Ihrem abzugeleichen. So ist es nicht nötig sich alle Produktinfos zu holen.
OEM
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 hier
Beispiel
Bei Aufruf von:
http://ws.cloud.topdata.de/match/oem? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
PCD
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 hier
Beispiel
Bei Aufruf von:
http://ws.cloud.topdata.de/match/pcd? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
EAN
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 hier
Beispiel
Bei Aufruf von:
http://ws.cloud.topdata.de/match/ean? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
Lieferanten Artikel-Nr
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 hier
Beispiel
Bei Aufruf von:
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); ?>