Webservice API/en: Unterschied zwischen den Versionen

Version vom 7. Mai 2015, 08:49 Uhr

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

?version=100

Language

The language must be provided as per ISO 639-1

?language=en

Error Codes

Overview of all errors:

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.

• 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": [
        ...
    ]
}

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.

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

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

erhalten Sie die Drucker-Modelle als Rückgabe.

Nach auswahl eines Druckers lässt sich das passende Verbrauchsmaterial über product_accessories aufrufen.

Drucker-Modell Textsuche

Bei Aufruf von:

• Suchbegriff wird benötigt (%q%)

http://ws.cloud.topdata.de/finder/ink_toner/search?
  q=%q%&
  uid=%uid%&
  security_key=%security_key%&
  password=%password%&
  version=%version%&
  language=%language%

erhalten Sie die Drucker-Modelle als Rückgabe.

Nach auswahl eines Druckers lässt sich das passende Verbrauchsmaterial über product_accessories aufrufen.

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