Webservice API: Unterschied zwischen den Versionen

Version vom 18. September 2014, 10:13 Uhr

Inhaltsverzeichnis

1 Webservice API Grundlagen
2 Webservice API Funktionen

Webservice API Grundlagen

Nutzung

Der Zugang zum Webservice hat sich an die Webservice Nutzungsbedingungen zu richten.

Zugriffe werden gelogt und ausgewertet. Um Zugriffe/Bandbreite sowie Serverkapazitäten zu sparen wird empfohlen die Anfragen auf den Webservice soweit es geht zu minimieren. Wir behalten uns das Recht vor Zugänge einzuschränken oder gegebenfalls auch zu sperren.
Zugangsdaten dürfen nicht an Dritte weitergegeben werden oder dargestellt werden.
Für Ihre Zugangsdaten sind bestimmte vorher vereinbarte Daten freigegeben.

Datenformat

Der Webservice gibt alles im JSON Format zurück. 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 Zugang zum Webservice erfolgt über eine feste HTTP URL.

http://ws.cloud.topdata.de

Für den Zugang zum Webservice werden Zugangsdaten benötigt die sich wie folgt zusammensetzen.

User ID (%uid%)
Passwort (%password%)
Sicherheitscode (%security_key%)

Die Zugangsdaten müssen bei jedem Aufruf des Webservices mit übergeben werden als HTTP Request.

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

Weiter sind folgende HTTP Request Variablen pflicht um eine Antwort vom Webservice zu erhalten

API-Version (%version%)
Sprache (%language%)

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

API-Version

Sollten Änderungen am Webservice statt finden wird eine neue API-Version vergeben. Damit Ihre eigene Applikation nicht immer mit geupdatet werden muss. ACHTUNG Support können wir immer nur für die altuelle API-Version geben.

Aktuelle APIVersion: 100

?version=100

Sprache

Die Sprache muss nach ISO 639-1 übergeben werden.

?language=en

Webservice API Funktionen

Warengruppen

Ruft die kompletten Warengruppen als Liste auf:

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

Beispiel

Bei Aufruf von:

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

Erhalten Sie folgende JSON Ausgabe:

{
    "waregroups": [
        {
            "waregroup_id": 1,
            "parent_waregroup_id": 173,
            "waregroup": "Printmedien"
        },
        {
            "waregroup_id": 3,
            "parent_waregroup_id": 162,
            "waregroup": "Etiketten"
        },
        ...
    ]
}

Produkte

Ruft zu einer bestimmten Warengruppe alle enthalten Produkte ab. Diese werden als Produktliste zurückgegeben. Dafür ist die Warengruppen ID notwendig. Diese erhalten Sie z.B. aus dem Aufruf der Warengruppen oder hinterlegt bei einem Produkt

Warengruppen ID (%waregroup_id%)

http://ws.cloud.topdata.de/waregroup/%warengroup_id%

Beispiel

Bei Aufruf von:

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

Erhalten sie die Produktliste als Rückgabe

Produktliste

Die Produktliste enthällt alle Information zu den Produkten und wird bei bestimmten Webservice-Aufrufen zurückgegeben.

Beispiel

{
 
    "page": {
        "count_products": 694,
        "products_per_page": 50,
        "page": 1,
        "available_pages": 14
    },
    "products": [
        ...
    ]
}

Die Produktliste wird immer in mehreren Seiten unterteilt um den traffic und die Ladezeit gering zu halten. Es ist aber möglich über eine weiter HTTP Request Variable die Seiten anzusteuern:

?page=3

Es sind alle Informationen enthalten wieviel Seiten, wieviel Produkte, wieviel Produkte pro Seite und auf welcher Seite man sich befindet.
Die Produtke in der Produktliste werden wie der 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 genause übergeben.

Legende uneindeutiger Variablen
Variable	Beschreibung
reference_oems	Falls das Produkt eine Alternative ist kommen hier die OEMs 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 sind hier die Produkte IDs der Einzelprodukte
product_alternates	Alternative Produkt IDs zum Produkt
product_is_alternate_of	Produkt ist Alternative von den genannten Produkt IDs
product_accessories	Zubehör Produkt IDs zum Produkt
product_application_in	Produkt ist Zubehör von den genannten Produkt IDs
distributors	verfügbare Anbieter und deren Artikelnummern

Zugangseinschränkungen
Variable	Beschreibung
images	Bilder erhalten Sie nur wenn diese für Ihren Zugang aktiviert wurden
distributors	Sie erhalten immer nur die Lieferanten die für Ihren Zugang aktiviert wurden

bundle_content

Ruft zu einer 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 einer 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 einer bestimmten Alternativprodukt die Produkte ab wozu 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 einer 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_application_in

Ruft zu einer 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_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.

Anbieter Produkte

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

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.

@@ Zeile 247: / Zeile 247: @@
 |[[Webservice_API#product_application_in|''product_application_in'']]||Produkt ist Zubehör von den genannten Produkt IDs
 |-
-|''distributors''||Lieferanten und deren Artikelnummern
+|''distributors''||verfügbare Anbieter und deren Artikelnummern
 |}<br>
 {| class="wikitable"
@@ Zeile 306: / Zeile 306: @@
 Bei Aufruf von:
 <source lang="text">http://ws.cloud.topdata.de/product_application_in/%product_id%?uid=%uid%&security_key=%security_key%&password=%password%&version=%version%&language=%language%</source>
+Erhalten sie die Produktliste als Rückgabe.
+<h3>Anbieter Produkte</h3>
+<p>Ruft zu einer bestimmten Anbieter die Produkte ab. Diese werden als [[Webservice_API#Produktliste|Produktliste]] zurückgegeben.
+Dafür ist die Anbieter ID notwendig. Diese ist z.B. bei einem Produkt</p>
+* Anbieter ID (%distributor_id%)
+<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%</source>
+<p>'''Beispiel'''</p>
+Bei Aufruf von:
+<source lang="text">http://ws.cloud.topdata.de/distributor/%distributor_id%?uid=%uid%&security_key=%security_key%&password=%password%&version=%version%&language=%language%</source>
 Erhalten sie die Produktliste als Rückgabe.

Webservice API: Unterschied zwischen den Versionen

Version vom 18. September 2014, 10:13 Uhr

Inhaltsverzeichnis

Webservice API Grundlagen

Nutzung

Datenformat

Zeichencodierung

Zugang

API-Version

Sprache

Webservice API Funktionen

Warengruppen

Produkte

Produktliste

Produkt

bundle_content

product_alternates

product_is_alternate_of

product_accessories

product_application_in

Anbieter Produkte

Navigationsmenü

Meine Werkzeuge

Namensräume

Varianten

Ansichten

Aktionen

Suche

Navigation

Werkzeuge