Webservice API/en: Unterschied zwischen den Versionen
(Die Seite wurde neu angelegt: „<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 Webse…“) |
(Die Seite wurde neu angelegt: „<h4>Distributor articlenumber</h4> <p>You get all for your user available Distributor articlenumber with our product ID. This comes in 1000er blocks. With "pag…“) |
||
Zeile 584: | Zeile 584: | ||
version=%version%& | version=%version%& | ||
language=%language%</source> | language=%language%</source> | ||
− | <h4> | + | <h4>Distributor articlenumber</h4> |
− | <p> | + | <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>''' | + | <p>'''Example'''</p> |
− | + | By accessing: | |
<source lang="text">http://ws.cloud.topdata.de/match/distributor? | <source lang="text">http://ws.cloud.topdata.de/match/distributor? | ||
uid=%uid%& | uid=%uid%& |
Version vom 19. Februar 2016, 16:19 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
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
?version=103
Language
The language must be provided as per ISO 639-1
?language=en
Error Codes
Alle Fehler im Überblick
Fehler Code | Fehler Beschreibung |
---|---|
100 | Unbekannter Fehler |
101 | 404 - Seite nicht gefunden |
102 | User ID nicht vorhanden oder nicht valide |
103 | Sicherheitscode nicht vorhanden oder nicht valide |
104 | Passwort nicht vorhanden oder nicht valide |
105 | API-Version nicht vorhanden oder nicht valide |
106 | Authentifizierung fehlgeschlagen |
107 | Sprache nicht vorhanden oder nicht valide |
108 | Template nicht gefunden (Bitte Service informieren) |
109 | Template Fehler (Bitte Service informieren) |
110 | Filter nicht vorhanden oder nicht valide |
200 | Produkt nicht gefunden |
Webservice API functions
My products
Sie You will receive all products activated for your access details in the form of a product list.
http://ws.cloud.topdata.de/my_products
Example:
When accessing:
http://ws.cloud.topdata.de/my_products? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
erhalten Sie die Produktliste als Rückgabe.
My products only with articlenumber
You get all your products as productlist that are activate for your account and where is a articlenumber of a distributor for.
http://ws.cloud.topdata.de/distributor_products
Waregroups
get the complete waregroups as list:
http://ws.cloud.topdata.de/waregroups
Example:
When accessing:
http://ws.cloud.topdata.de/waregroups? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
you receive the following JSON output:
{ "waregroups": [ { "waregroup_id": 1, "parent_waregroup_id": 173, "waregroup": "Printmedien" }, { "waregroup_id": 3, "parent_waregroup_id": 162, "waregroup": "Etiketten" }, ... ] }
Products
Accesses all products contained in a specific product group. These are output as a Productlist. The product groups ID is required for this. This is can be obtained for example, by accessing the produktgroups or it is stored with one of the products
- Warengruppen ID (%waregroup_id%)
http://ws.cloud.topdata.de/waregroup/%warengroup_id%
'Example
When accessing
http://ws.cloud.topdata.de/waregroup/%warengroup_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned
Produktliste
Die Produktliste enthält alle vom Filter zugelassenen Informationen zu den Produkten und wird bei bestimmten Webservice-Aufrufen zurückgegeben. Es gelten die selben Filterangaben wie beim Produkt
- Warengruppen Produkte
- bundle_content
- product_alternates
- product_is_alternate_of
- product_accessories
- product_application_in
- Anbieter Produkte
Beispiel
{ "page": { "count_products": 694, "products_per_page": 50, "page": 1, "available_pages": 14 }, "products": [ ... ] }
In order to keep traffic and loading times low, the product list is always divided into multiple pages. The individual pages may be accessed via an additional HTTP request variable:
?page=3
The product list includes information about the number of pages, the number of products, the number of products per page, and the currently selected sub-page. The products in the product list are displayed analogously to how individual products are accessed.
more products for one request (since version 103)
You can give the webservice more than one products id to get a productlist for this. Provide the products ids comma seperated in a string. Attention only maximal 50 Product-IDs are allowed(more of this will be ignored).
http://ws.cloud.topdata.de/product_list
Example
By accessing:
http://ws.cloud.topdata.de/product_list?products=123456,789012& filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the productlist is returned 2 products(123456 and 789012).
Product
Request one with the from filter allowed informations of the webservice. The product ID is required for this
- Produkt ID (%products_id%)
- Filter (%filter%)
http://ws.cloud.topdata.de/product
Example für den Artikel 92298A von HP
By accessing:
http://ws.cloud.topdata.de/product/145080?filter=all& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
you receive the following JSON output:
{ "product": { "products_id": 145080, "creation_date": null, "edit_date": null, "short_description": "Original Hewlett Packard Toner-Kartusche schwarz (92298A, 98A)", "manufacturer": "Hewlett Packard (HP)", "name": "", "oems": [ "92298A", "98A" ], "eans": [ "088698005668" ], "reference_oems": [ "1538A003", "M2473G/A", "LN0XX-AA" ], "bundle_content_oems": [ ], "waregroups": [ { "waregroup_id": 57, "waregroup": "Toner-Kartuschen", "main_waregroup": true, "waregroup_tree": [ { "waregroup_id": 157, "waregroup": "Bürobedarf" }, { "waregroup_id": 173, "waregroup": "Druckerzubehör" }, { "waregroup_id": 199, "waregroup": "Laserdrucker" }, { "waregroup_id": 56, "waregroup": "Toner" }, { "waregroup_id": 57, "waregroup": "Toner-Kartuschen" } ] } ], "specifications": [ { "specification_id": 6, "specification": "Seitendeckung", "attribute_id": 4521, "attribute": "bei 5% Seitendeckung", "attribute_synonym": "", "count": 1 }, ... ], "images": [ { "type_id": 5, "type_id_string": "005", "type_key": "image_type_pack_and_product", "thumb": { "url": "http://image.cloud.topdata.de/t/145080.jpg", "url_own_filename": "http://image.cloud.topdata.de/t/145080/" }, "normal": { "url": "http://image.cloud.topdata.de/n/145080.jpg", "url_own_filename": "http://image.cloud.topdata.de/n/145080/" } }, { "type_id": 10, "type_id_string": "010", "type_key": "image_type_pack", "thumb": { "url": "http://image.cloud.topdata.de/t/145080.jpg", "url_own_filename": "http://image.cloud.topdata.de/t/145080/" }, "normal": { "url": "http://image.cloud.topdata.de/n/145080.jpg", "url_own_filename": "http://image.cloud.topdata.de/n/145080/" } }, ... ], "bundle_content": [ ], "product_alternates": { "ws_list_url": "/product_alternates/145080", "products": [ [ 145070, ... ] ] }, "product_is_alternate_of": { "ws_list_url": "/product_is_alternate_of/145080", "products": [ [ 145070, ... ] ] }, "product_accessories": [ ], "product_application_in": [ ], "distributors": [ ] } }
By the Productlist the products will be transfered in the same way
Filter
since Verion 103 required
The product features can be filtered to minimize the JSON return of the webservice. If not all the information are needed, with teh correct filtering the converting from JSON to an object can save a lot of time in your application.
- Filter (%filter%)
?filter=all
The following basic filter available "all". This is in principle given back everything. If you do not need anything, you can use different filters in the table below. This can also be passed separately combined with comma.
?filter=specifications,product_alternates
Variable | Description | Filter |
---|---|---|
reference_oems | If the product is an alternative, then the OEMs for the corresponding products appear here | |
bundle_content_oems | If the product is a bundle, then the OEMs for the individual products appear here | |
waregroups | Waregroups for the product | waregroups |
specifications | specifications for the product | specifications |
images | Images for the product | images |
bundle_content | Falls If the product is a bundle, then the product IDs for the individual products appear here | bundle_content |
product_alternates | Alternative product IDs for the product | product_alternates |
product_is_alternate_of | The product is an alternative of the product IDs indicated | product_is_alternate_of |
product_accessories | Zubehör Accessory product IDs for the product | product_accessories |
product_same_accessories | All product IDs with the same accessories for the product | product_same_accessories |
product_application_in | Product is an accessory of the named product IDs | product_application_in |
product_same_application_in | All product IDs with the same parent product which are an accessory for the product | product_same_application_in |
child_extra_infos | Basic infos for the crossesproducts (manufacturer, name and shortdescription) (since version 102) | child_extra_infos |
distributors | available providers and their article numbers |
Variable | Description |
---|---|
images | You will only receive images if these are activated for your access details |
distributors | You will only receive suppliers that are activated for your access details |
bundle_content
Accesses the products contained for a certain bundle product. These are output as a Productlist . The product ID of the bundle is required for this.
- Produkt ID (%product_id%)
http://ws.cloud.topdata.de/bundle_content/%product_id%
Example
By accessing:
http://ws.cloud.topdata.de/bundle_content/%product_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned.
product_alternates
Accesses the alternative product for a certain product. These are output as a Productlist . The product ID of the bundle is required for this.
- Produkt ID (%product_id%)
http://ws.cloud.topdata.de/product_alternates/%product_id%
Example
By accessing:
http://ws.cloud.topdata.de/product_alternates/%product_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned.
product_is_alternate_of
For a certain alternative product, accesses those products for which it is an alternative.These are output as a Productlist . The product ID of the bundle is required for this.
- Produkt ID (%product_id%)
http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%
'Example
Bay accessing:
http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned.
product_accessories
Accesses those products which are an accessory. These are output as a Productlist . The product ID of the bundle is required for this.
- Produkt ID (%product_id%)
http://ws.cloud.topdata.de/product_accessories/%product_id%
Example
By accessing
http://ws.cloud.topdata.de/product_accessories/%product_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned.
product_same_accessories
Accesses those products for a certain product, which are having the same accessories. These are output as a Productlist . The product ID of the bundle is required for this
- Produkt ID (%product_id%)
http://ws.cloud.topdata.de/product_same_accessories/%product_id%
Example
By accessing
http://ws.cloud.topdata.de/product_same_accessories/%product_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned.
product_application_in
Accesses those products for which it is an accessory. These are output as a Productlist . The product ID of the bundle is required for this.
- Produkt ID (%product_id%)
http://ws.cloud.topdata.de/product_application_in/%product_id%
Example
By accessing:
http://ws.cloud.topdata.de/product_application_in/%product_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned.
product_same_application_in
Accesses those products which are also an accessory. These are output as a Productlist . The product ID of the bundle is required for this.
- Produkt ID (%product_id%)
http://ws.cloud.topdata.de/product_same_application_in/%product_id%
Example
By accessing
http://ws.cloud.topdata.de/product_same_application_in/%product_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
the product list is returned.
Provider products
Accesses the products for a certain provider. These are output as a Productlist . The product ID of the bundle is required for this.
- Anbieter ID (%distributor_id%)
http://ws.cloud.topdata.de/distributor/%distributor_id%
Example
By accessing:
http://ws.cloud.topdata.de/distributor/%distributor_id%? filter=%filter%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
Productfinder
Here you get the data ready to use it as productfinder.
Ink and Toner Finder
The Ink and Toner Finder needs to find the matching consumables for your printer in 2-3 steps.
- Printer-Brand (Required) Step 1
- Printer-Modelseries (Optional) Step 2
- Printer-Types (Optional) Step 2
- Printer-Model (Required) Step 3
- Printer-Model Textsearch
Printer-Brand
By accessing:
http://ws.cloud.topdata.de/finder/ink_toner/brands? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
you get the Printer-Brands as Request.
Printer-Modelseries
By accessing:
- Printer-Brand ID is required (%brand_id%)
http://ws.cloud.topdata.de/finder/ink_toner/modelseries? brand_id=%brand_id%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
you get the Printer-Modelseries as Request.
Printer-Types
By accessing:
- Printer-Brand ID is required (%brand_id%)
http://ws.cloud.topdata.de/finder/ink_toner/devicetypes? brand_id=%brand_id%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
you get the Printer-Types as Request.
Printer-Models
By accessing:
- Printer-Brand ID is required (%brand_id%)
- Printer-Modelserie ID is optional (%modelserie_id%)
- Printer-Type ID is optional (%devicetype_id%)
http://ws.cloud.topdata.de/finder/ink_toner/models? brand_id=%brand_id%& modelserie_id=%modelserie_id%& //devicetype_id=%devicetype_id%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
you get the Printer-Models as Request.
After choose a Printer-model you can receive the matching supplies over product_accessories.
Printer-Model Textsearch
By accessing:
- Searchkeyword is required (%q%)
http://ws.cloud.topdata.de/finder/ink_toner/search? q=%q%& uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
you get the Printer-Models as Request.
After choose a Printer-model you can receive the matching supplies over product_accessories.
Mapping
Use the mapping to match quickly your product portfolio with our product portfolio. So it is not necessary to get all the info.
OEM
You get all for your user available OEM with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear
Example
By accessing:
http://ws.cloud.topdata.de/match/oem? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
PCD
You get all for your user available PCD with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear
Example
By accessing:
http://ws.cloud.topdata.de/match/pcd? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
EAN
You get all for your user available EAN with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear
Example
By accessing:
http://ws.cloud.topdata.de/match/ean? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
Distributor articlenumber
You get all for your user available Distributor articlenumber with our product ID. This comes in 1000er blocks. With "page" you can go through it. More infos hear
Example
By accessing:
http://ws.cloud.topdata.de/match/distributor? uid=%uid%& security_key=%security_key%& password=%password%& version=%version%& language=%language%
Code Example
PHP
Example to receive one product.
<?php //receive data $data = file_get_contents('http://ws.cloud.topdata.de/product/145080?uid=...&security_key=...&password=..&version=100&language=de'); //decode json data $json = json_decode($data); //display json object var_dump($json); ?>