Webservice API

Sprachen:

Deutsch • ‎English

Webservice API Grundlagen

Nutzung

Mit dem Zugang zum Webservice haben Sie automatisch unsere Webservice Nutzungsbedingungen verstanden und akzeptiert.

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.
Zugangsdaten dürfen nicht an Dritte weitergegeben oder öffentlich dargestellt werden.
Für Ihre Zugangsdaten sind bestimmte, vorher vereinbarte, Daten freigegeben.

Datenformat

Die Rückgabe des Webservices erfolgt im JSON Format. Wir haben uns gegen XML entschieden, da JSON inzwischen genauso weit verbreitet ist und gegenüber XML den Overhead reduziert. Mehr Informationen

Zeichencodierung

Die Ausgabe der Daten des Webservices erfolgt in UFT8

Zugang

Der Abruf der Webservice-Daten erfolgt über eine feste 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.

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

?version=100

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

http://ws.cloud.topdata.de/waregroups

Example:

When accessing:

http://ws.cloud.topdata.de/waregroups?
  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%?
  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.

Example

{
 
    "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.

Product

Accesses an individual product from the web service. The product ID is required for this.

Produkt ID (%products_id%)

http://ws.cloud.topdata.de/product

Example für den Artikel 92298A von HP

By accessing:

http://ws.cloud.topdata.de/product/145080?
  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": [ ]
    }
}

Bei der Produktliste werden die Produkte ebenso übergeben.

Legend of unclear variables
Variable	Description
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
bundle_content	Falls If the product is a bundle, then the product IDs for the individual products appear here
product_alternates	Alternative product IDs for the product
product_is_alternate_of	The product is an alternative of the product IDs indicated
product_accessories	Zubehör Accessory product IDs for the product
product_same_accessories	All product IDs with the same accessories for the product
product_application_in	Product is an accessory of the named product IDs
product_same_application_in	All product IDs with the same parent product which are an accessory for the product
distributors	available providers and their article numbers

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

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%?
  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%?
  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%?
  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%?
  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%?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

the product list is returned.

product_application_in

Ruft zu einem bestimmten Produkt die Produkte ab wozu es ein Zubehör ist. Diese werden als Produktliste zurückgegeben. Dafür ist die Produkt ID notwendig.

Produkt ID (%product_id%)

http://ws.cloud.topdata.de/product_application_in/%product_id%

Beispiel

Bei Aufruf von:

http://ws.cloud.topdata.de/product_application_in/%product_id%?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

erhalten Sie die Produktliste als Rückgabe.

product_same_application_in

Ruft zu einem bestimmten Produkt die Produkte ab die genauso ein Zubehör sind. Diese werden als Produktliste zurückgegeben. Dafür ist die Produkt ID notwendig.

Produkt ID (%product_id%)

http://ws.cloud.topdata.de/product_same_application_in/%product_id%

Beispiel

Bei Aufruf von:

http://ws.cloud.topdata.de/product_same_application_in/%product_id%?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

erhalten Sie die Produktliste als Rückgabe.

Anbieter Produkte

Ruft zu einem bestimmten Anbieter die Produkte ab. Diese werden als Produktliste zurückgegeben. Dafür ist die Anbieter ID notwendig. Diese ist z.B. bei einem der Produkte einsehbar.

Anbieter ID (%distributor_id%)

http://ws.cloud.topdata.de/distributor/%distributor_id%

Beispiel

Bei Aufruf von:

http://ws.cloud.topdata.de/distributor/%distributor_id%?
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

erhalten Sie die Produktliste als Rückgabe.

Code Beispiele

PHP

Z.B. für das Abrufen von einem Produkt.

<?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);
 
?>

Webservice API

Inhaltsverzeichnis

Webservice API Grundlagen

Nutzung

Datenformat

Zeichencodierung

Zugang

API-Version

Language

Error Codes

Webservice API functions

My products

Product groups

Products

Productlist

Product

bundle_content

product_alternates

product_is_alternate_of

product_accessories

product_same_accessories

product_application_in

product_same_application_in

Anbieter Produkte

Code Beispiele

PHP

Navigationsmenü

Meine Werkzeuge

Namensräume

Varianten

Ansichten

Aktionen

Suche

Navigation

Werkzeuge