Bewusstkaufen.at XML Produkt Importschnittstelle für Händler Inhalt Inhalt... 1 Ablauf... 2 Bilder vorbereiten... 2 Methode 1: Bilder auf Fremdserver bereitstellen... 2 Methode 2: Bilder per FTP auf den Server von Bewusstkaufen hochladen.... 2 Import der Stammdaten... 3 Nachbearbeitung im Online-Backend... 3 XML Aufbau... 4 Produktdaten (Request senden)... 4 Grundstruktur... 4 DTD... 5 Beschreibung... 5 Report (Antwort auf Request empfangen)... 7 Grundstruktur... 7 Beschreibung... 7 Beispiel in PHP... 8 Version 0.5 1
Ablauf Bilder vorbereiten Bevor Sie Ihre Daten importieren können, müssen Sie alle in der Importvorlage eingetragenen Bilder zur Verfügung stellen. Dazu gibt es 2 Möglichkeiten Methode 1: Bilder auf Fremdserver bereitstellen Sie können mit URLs arbeiten welche auf die Bilder auf einem Fremdserver verweisen. Diese URLs müssen mit http:// oder https:// beginnen. Die Bilder werden automatisch vom Fremdserver auf den Bewusstkaufenserver geladen. Methode 2: Bilder per FTP auf den Server von Bewusstkaufen hochladen. Laden Sie die Bilder vor dem Import via FTP auf unseren Server. Anstatt URLs verwenden sie einfach die Dateinamen der Bilder. Zugangsdaten: Server: www.bewusstkaufen.at Benutzername: bilder Passwort: fabofa19 Die Produktbilder müssen im JPG, GIF oder PNG Format vorliegen und eine Mindestauflösung von 350x260 Pixel haben (maximal 2MB pro Bild). Die Dateinamen der Bilder müssen exakt mit den Bildnamen der Produkt-Stammdaten (siehe Import der Stammdaten) übereinstimmen. Da dieser FTP Ordner auch von anderen Händlern genutzt wird, kann es sein dass bereits Bilder in dem Ordner vorliegen. Wir bitten Sie daher bestehende Bilder weder zu überschreiben noch zu löschen. Um Probleme zu vermeiden ersuchen wir Sie die Dateinamen der Bilder mit einem Händlerkürzel zu kennzeichnen. Beispiele: ihrhaendlername-brot.jpg ihrhaendlername-nudeln.jpg ihrhaendlername-kuehlschrank.jpg Für den FTP Upload empfehlen wir den kostenlos erhältlichen FTP Client Filezilla. WICHTIG! Die Daten auf dem FTP Server werden täglich um 24 Uhr gelöscht. Der Import (siehe Import der Stammdaten) muss deshalb am selben Tag wie der Bildupload stattfinden. Version 0.5 2
Import der Stammdaten Zum Import der Produkt Stammdaten steht eine XML Import Schnittstelle zur Verfügung. Schicken Sie die Produktdaten als XML dargestellt (siehe XML Aufbau) via HTTP POST Request in einer Post-Variable mit dem Namen data an http://www.bewusstkaufen.at/import/import.php Als Antwort auf den Request wird ein Import-Bericht, ebenfalls im XML-Format, zurückgesendet. Bei wiederholtem Import eines zuvor importierten Produkts, wird das Bestehende mit dem Neuen überschrieben (identifiziert durch entweder GTIN, oder - falls nicht vorhanden - Produktname). Es werden nur die Stammdaten überschrieben, die im nächsten Schritt beschriebene Nachbearbeitung von Produktgruppe, Themen und Labels bleibt erhalten. Dadurch ist ein automatisiertes aktuell halten der Produkte in der Bewusstkaufen Datenbank möglich. Nachbearbeitung im Online-Backend Nachdem erfolgreichen Import der Stammdaten müssen Sie im Händler-Bereich von Bewusstkaufen.at Ihre Produktdaten vervollständigen (Labels, Themen, Produktgruppen). Loggen Sie sich dafür auf www.bewusstkaufen.at mit den Zugangsdaten die Sie erhalten haben ein, und klicken Sie anschließend rechts Oben beim Login-Bereich auf den Link CMS. Im Händlerbereich finden Sie unter Import FAQ alle nötigen Informationen die ihnen dabei helfen die Nachbearbeitung abzuschließen. Version 0.5 3
XML Aufbau Produktdaten (Request senden) Grundstruktur <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE import SYSTEM "http://www.bewusstkaufen.at/import/import.dtd"> <import> <authentication> <user></user> <password></password> </authentication> <products> <product> <gtin></gtin> <bezeichnung> </bezeichnung> <zusatz></zusatz> <bild></bild> <bild></bild> <bild></bild> <beschreibung></beschreibung> <hersteller></hersteller> <regional /> <herkunftsland></herkunftsland> <energieeffizienzklasse></energieeffizienzklasse> <lebensdauer></lebensdauer> <topprodukt /> <topprodukturl></topprodukturl> <shopurl></shopurl> </product> <product>... </product> <product>... </product> </products> </import> Version 0.5 4
DTD Wie aus dem Doctype erkennbar wird das XML gegen http://www.bewusstkaufen.at/import/import.dtd validiert. Dieses sieht wie folgt aus: <!ELEMENT import (authentication, products)> <!ELEMENT authentication (user, password)> <!ELEMENT products (product+)> <!ELEMENT product (gtin?,bezeichnung,zusatz?,bild*,beschreibung,hersteller,regional?,herkunft sland?,energieeffizienzklasse?,lebensdauer?,topprodukt?,topprodukturl?,shop url?)> <!ELEMENT user (#PCDATA)> <!ELEMENT password (#PCDATA)> <!ELEMENT gtin (#PCDATA)> <!ELEMENT bezeichnung (#PCDATA)> <!ELEMENT zusatz (#PCDATA)> <!ELEMENT bild (#PCDATA)> <!ELEMENT beschreibung (#PCDATA)> <!ELEMENT hersteller (#PCDATA)> <!ELEMENT regional EMPTY> <!ELEMENT herkunftsland (#PCDATA)> <!ELEMENT energieeffizienzklasse (#PCDATA)> <!ELEMENT lebensdauer (#PCDATA)> <!ELEMENT topprodukt EMPTY> <!ELEMENT topprodukturl (#PCDATA)> <!ELEMENT shopurl (#PCDATA)> Beschreibung Der Wurzelknoten hat 2 Kinder die beide verpflichtend sind: <authentication>... </authentication> o darf nur einmal vorkommen o enthält in <user>... </user> und <password>... </password> die Zugangsdaten die Sie erhalten haben (die selben wie für den Login zum Händlerbereich von Bewusstkaufen.at) <products>... </products> o darf nur einmal vorkommen o enthält beliebig viele <product>... </product> Tags, welche die Produktdaten enthalten. Die Produktdaten zwischen den <product>... </product> Tags sind wie folgt strukturiert: <gtin>... </gtin> o EAN/GTIN Code des Produkts o 8 oder 13 stellige ganze Zahl (GTIN8 oder GTIN13) <bezeichnung>... </bezeichnung> o verpflichtend o die Bezeichnung des Produkts o unique o max 255 Zeichen Version 0.5 5
<zusatz>... </zusatz> o Zusatz zur Bezeichung o max 255 Zeichen <bild>... </bild> o Dateiname des Produkt-Bildes aus vorigem FTP-Upload oder http-url zu Bild auf Fremdserver o darf bis zu 5 mal vorkommen <beschreibung>... </beschreibung> o verpflichtend o die Beschreibung des Produkts o kein HTML o Zeilenumbrüche erlaubt <hersteller>... </hersteller> o verpflichtend o der Hersteller des Produkts o max 255 Zeichen <regional /> o muss leer sein o gibt an ob es sich um ein regionales Produkt handelt <herkunftsland>... </herkunftsland> o verpflichtend wenn VorgängerTag <regional /> gesetzt ist, sonst optional o das Herkunftsland des Produkts <energieeffizienzklasse>... </energieeffizienzklasse> o die Energieeffizienzklasse des Produkts falls es ein Elektrogerät ist o muss eines folgender Werte sein: A, A+, A++, B <lebensdauer>... </lebensdauer> o die Lebensdauer in Stunden des Produkts falls es ein Elektrogerät ist o ganze Zahl zwischen 1 und 1000000 <topprodukt /> o muss leer sein o gibt an ob es sich um ein Produkt handelt das auf www.topprodukte.at gelistet ist <topprodukturl>... </topprodukturl> o URL zum Produkt auf www.topprodukte.at <shopurl>... </shopurl> o URL zum Produkt im eigenen Online-Shop Version 0.5 6
Report (Antwort auf Request empfangen) Grundstruktur <?xml version="1.0" encoding="utf-8"?> <report> <status>success</status> <entry> <severity></severity> <productnumber></productnumber> <productname></productname> <message></message> </entry> <entry>... </entry> <entry>... </entry> </report> Beschreibung Der Wurzelknoten <report> enthält immer einen Knoten <status> </status> und kann optional eine beliebige Anzahl von <entry> </entry> Knoten besitzen. <status> </status> beinhaltet entweder den Text success oder failed, und gibt somit den Erfolg des Vorgangs an. Die <entry> </entry> Knoten sind Report Einträge und enthalten folgende Informationen: o <severity> </severity> verpflichtend Einer folgender Werte: Hinweis, WARNUNG, FEHLER, KRITISCHER FEHLER Gibt die Schwere der Meldung an. Bei einem FEHLER oder KRITISCHER FEHLER Eintrag, ist der Import immer gescheitert. o <productnumber> </productnumber> optional Die Nummer des betroffenen Produkts in angegebener Reihenfolge o <productname > </productname> optional Der Name des betroffenen Produkts o <message> </message> verpflichtend der Report Text Version 0.5 7
Beispiel in PHP Folgendes Beispiel in PHP illustriert wie die Importschnittstelle anprogrammiert werden kann. Der XML-Report wird im Anschluss unverarbeitet auf dem Bildschirm ausgegeben. <?php?> // angenommen die XML Daten befinden sich in einer Datei products.xml $xml = file_get_contents("products.xml"); // XML Daten der Post Variable data zuweisen $xml_data = "data=".urlencode($xml); // Ziel URL $URL = "http://www.bewusstkaufen.at/import/import.php"; // XML Daten mit Hilfe von curl verschicken $ch = curl_init($url); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, "$xml_data"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); $output = curl_exec($ch); curl_close($ch); // XML Report ausgeben echo $output; Version 0.5 8