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

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 als HTTP Request mit übergeben werden.

?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 stattfinden, wird eine neue API-Version vergeben, damit Ihre eigene Applikation nicht immer mit geupdatet werden muss. ACHTUNG, Support unsererseits kann nur für die jeweils aktuelle API-Version geleistet werden.

Aktuelle APIVersion: 100

?version=100

Sprache

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

?language=en

Error Codes

Alle Fehler im Überblick

Fehler Code	Fehler Beschreibung
100	Unbekannter Fehler
101	404 - Seite nicht gefunden
102	User ID nicht vorhanden oder nicht valide
103	Sicherheitscode nicht vorhanden oder nicht valide
104	Passwort nicht vorhanden oder nicht valide
105	API-Version nicht vorhanden oder nicht valide
106	Authentifizierung fehlgeschlagen
107	Sprache nicht vorhanden oder nicht valide
108	Template nicht gefunden (Bitte Service informieren)
109	Template Fehler (Bitte Service informieren)
200	Produkt nicht gefunden

Webservice API Funktionen

Meine Produkte

Sie erhalten alle für Ihren Zugang aktivierten Produkte als Produktliste.

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

Beispiel

Bei Aufruf von:

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

erhalten Sie die Produktliste als Rückgabe.

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 alle enthalten Produkte zu einer bestimmten Warengruppe 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 sie ist bei einem der Produkte hinterlegt

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ält alle Informationen 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": [
        ...
    ]
}

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

Webservice API

Inhaltsverzeichnis

Webservice API Grundlagen

Nutzung

Datenformat

Zeichencodierung

Zugang

API-Version

Sprache

Error Codes

Webservice API Funktionen

Meine Produkte

Warengruppen

Produkte

Produktliste

Produkt

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