Webservice API

Aus TopData WIKI
Wechseln zu: Navigation, Suche
Sprachen:
Deutsch • ‎English


Webservice Api Basics

Use

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

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

Data format:

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

Character encoding

data from the web services is released UFT8

Access

The web service data is accessed via a fixed HTTP URL 

http://ws.cloud.topdata.de

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

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

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

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

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

API-Version

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

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

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
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
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

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

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);
 
?>
Von „http://wiki.cloud.topdata.de/index.php?title=Webservice_API/en&oldid=352“