Webservice API/en: Unterschied zwischen den Versionen

Aus TopData WIKI
Wechseln zu: Navigation, Suche
(Die Seite wurde neu angelegt: „<h3>Provider products</h3> <p> Accesses the products for a certain provider. These are output as a Productlist . The product I…“)
(Die Seite wurde neu angelegt: „the product list is returned <h2>Code Examples</h2> <h3>PHP</h3> For instance the calling of a product:“)
Zeile 435: Zeile 435:
 
   version=%version%&
 
   version=%version%&
 
   language=%language%</source>
 
   language=%language%</source>
erhalten Sie die Produktliste als Rückgabe.
+
the product list is returned
<h2>Code Beispiele</h2>
+
<h2>Code Examples</h2>
 
<h3>PHP</h3>
 
<h3>PHP</h3>
Z.B. für das Abrufen von einem Produkt.
+
For instance the calling of a product:
 
<source lang="php">
 
<source lang="php">
 
<?php
 
<?php

Version vom 5. Mai 2015, 08:33 Uhr

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.

?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

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%

Beispiel

Bei Aufruf von:

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

the product list is returned

Code Examples

PHP

For instance the calling of a 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);
 
?>