Webservice API/en: Unterschied zwischen den Versionen

Aus TopData WIKI
Wechseln zu: Navigation, Suche
(Die Seite wurde neu angelegt: „the product list is returned“)
(Die Seite wurde neu angelegt: „<h3>Productlist</h3> <p>Die The product list includes all information about the products and is returned when certain web services are accessed.</p> * Webser…“)
Zeile 125: Zeile 125:
 
the product list is returned
 
the product list is returned
  
−
<h3>Produktliste</h3>
+
<h3>Productlist</h3>
−
<p>Die Produktliste enthält alle Informationen zu den Produkten und wird bei bestimmten Webservice-Aufrufen zurückgegeben.</p>
+
<p>Die The product list includes all information about the products and is returned when certain web services are accessed.</p>
−
* [[Webservice_API#Warengruppen|Warengruppen Produkte]]
+
* [[Webservice_API#Warengruppen|waregroup_products]]
 
* [[Webservice_API#bundle_content|''bundle_content'']]  
 
* [[Webservice_API#bundle_content|''bundle_content'']]  
 
* [[Webservice_API#product_alternates|''product_alternates'']]  
 
* [[Webservice_API#product_alternates|''product_alternates'']]  
Zeile 133: Zeile 133:
 
* [[Webservice_API#product_accessories|''product_accessories'']]  
 
* [[Webservice_API#product_accessories|''product_accessories'']]  
 
* [[Webservice_API#product_application_in|''product_application_in'']]
 
* [[Webservice_API#product_application_in|''product_application_in'']]
−
* [[Webservice_API#Anbieter Produkte|Anbieter Produkte]]
+
* [[Webservice_API#Anbieter Produkte|provider_products]]
−
<p>'''Beispiel'''</p>
+
<p>'''Example'''</p>
 
<source lang="javascript">
 
<source lang="javascript">
 
{
 
{

Version vom 5. Mai 2015, 08:26 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": [
        ...
    ]
}

Um den Traffic und die Ladezeit gering zu halten, wird die Produktliste immer in mehrere Seiten unterteilt. Die einzelnen Seiten können über eine weitere HTTP Request Variable angesteuert werden:

?page=3

Die Produktliste beinhaltet Informationen über die Anzahl der Seiten, die Anzahl der Produkte, die Anzahl der Produkte pro Seite sowie die aktuell ausgewählte Unterseite.
Die Produkte in der Produktliste werden analog zum Aufruf eines einzelnen Produktes dargestellt.

Produkt

Abruf eines einzelnen Produktes vom Webservice. Dafür ist die Produkt ID notwendig.

  • Produkt ID (%products_id%) 
http://ws.cloud.topdata.de/product

Beispiel für den Artikel 92298A von HP

Bei Aufruf von: 

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

erhalten Sie folgende JSON Ausgabe: 

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

Legende uneindeutiger Variablen
Variable Beschreibung
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
bundle_content Falls das Produkt ein Bundle ist, kommen hier die Produkt IDs der Einzelprodukte
product_alternates Alternative Produkt IDs zum Produkt
product_is_alternate_of Produkt ist eine Alternative der genannten Produkt IDs
product_accessories Zubehör Produkt IDs zum Produkt
product_same_accessories Alle Produkt IDs mit dem selben Zubehör zum Produkt
product_application_in Produkt ist Zubehör von den genannten Produkt IDs
product_same_application_in Alle Produkt IDs mit dem selben Elternprodukt wozu es ein Zubehör ist vom Produkt
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

Ruft zu einem bestimmten Bundle-Produkt die enthalten Produkte ab. Diese werden als Produktliste zurückgegeben. Dafür ist die Produkt ID des Bundles notwendig.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/bundle_content/%product_id%

Beispiel

Bei Aufruf von: 

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

erhalten Sie die Produktliste als Rückgabe.

product_alternates

Ruft zu einem bestimmten Produkt die Alternativprodukte ab. Diese werden als Produktliste zurückgegeben. Dafür ist die Produkt ID notwendig.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_alternates/%product_id%

Beispiel

Bei Aufruf von: 

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

erhalten Sie die Produktliste als Rückgabe.

product_is_alternate_of

Ruft zu einem bestimmten Alternativprodukt diejenigen Produkte ab, zu denen es alternativ ist. Diese werden als Produktliste zurückgegeben. Dafür ist die Produkt ID notwendig.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_is_alternate_of/%product_id%

Beispiel

Bei Aufruf von: 

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

erhalten sie die Produktliste als Rückgabe.

product_accessories

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

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_accessories/%product_id%

Beispiel

Bei Aufruf von: 

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

erhalten Sie die Produktliste als Rückgabe.

product_same_accessories

Ruft zu einem bestimmten Produkt die Produkte ab mit den dem selben Zubehör. Diese werden als Produktliste zurückgegeben. Dafür ist die Produkt ID notwendig.

  • Produkt ID (%product_id%) 
http://ws.cloud.topdata.de/product_same_accessories/%product_id%

Beispiel

Bei Aufruf von: 

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

erhalten Sie die Produktliste als Rückgabe.

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