OXID calling eBay

Integration des eBay API in ein Shopsystem
Kommentare

Die Integration in OXID hinein erfolgt in Form eines neuen Moduls. In Abbildung 1 sehen Sie den dazu angelegten Bereich im Source-Code-Ordner des OXID-Shops. Faktisch muss hierzu nur eine Datei menu.xml im angelegten Modulordner /cxebayutils/ existieren und eine Moduldatei cxebayutils.php direkt im Modulordner angelegt werden.

Vor einigen Jahren war die Welt der eBay Powerseller noch in Ordnung. Viele Händler konnten mit einer ausschließlichen Aktivität auf dem Onlinemarktplatz ihren Lebensunterhalt bestreiten. Heute lassen sich Gewinne im E-Commerce-Bereich nur in einer Kombination aus eigenem Shopsystem und der Anbindung an Onlinemarktplätze realisieren. Nichtsdestotrotz sind aber auch hier eine effiziente Abwicklung und die Unterstützung durch entsprechende Softwarefunktionen wünschenswert. Häufig erfolgt der Aufbau eines eigenen Onlineshops in inkrementellen Phasen. Zunächst kann durch den Einsatz einer Open-Source-Lösung die Höhe der Anfangsinvestition reduziert werden. Bei Erfolg kann dann eventuell zu einer Lizenzlösung gewechselt oder das System nach eigenen Ansprüchen und Erfordernissen erweitert werden.

eBay und OXID

Die OXID eSales AG bietet mit der seit Jahresende 2008 verfügbaren Community-Edition einen kostenfreien Einstieg in die Welt des E-Commerce. Bei Bedarf können die Systeme mit Modulen erweitert werden. Auch hierunter finden sich teilweise kostenfreie Pakete. Die Mehrzahl der kostenpflichtigen Module liefert einen Betrag zum Einkommen von OXID und diversen Partnern. Aber auch ohne Erweiterungen steht bereits ein voll funktionsfähiges System zur Verfügung. Vielen Unkenrufen und Kritikern zum Trotz stellt eBay weiterhin den reichweitenstärksten Onlinemarktplatz dar. Die Unterstützung von Tools, sei es für Käufer oder Verkäufer, ist mittlerweile vielfältig. Auch die von eBay selbst angebotenen Hilfsprogramme (Turbolister, eBay-Verkaufsabwicklung) sind bis zum Überschreiten eines größeren Volumens durchaus brauchbar.

OXID eFire

Der Aufbau einer vollständigen Integrationslösung, die sämtliche Aspekte der Verkaufsabwicklung abdeckt, wird häufig in einem Shopsystem unterschätzt. Basisfunktionen können zunächst mit vertretbarem Aufwand realisiert werden – die vielen kleinen Details machen die Komplettierung aber zu einem durchaus anspruchsvollen Unterfangen.

Die OXID eSales AG selbst bietet hier bereits eine Integrationslösung an. Dabei werden die wesentlichen Funktionalitäten mittels der so genannten OXID-eFire-Schnittstelle auf einem Portal realisiert. Das kostenpflichtige Modul steht allen OXID-Shops (inklusive der Community-Edition) zur Verfügung. Somit ist – bei gewachsenem Bedarf – die Nutzung auch hier problemlos möglich. Die durch eFire bereitgestellte Schnittstelle ermöglicht das Einstellen von Shopartikeln auf eBay und später den Import der dort stattgefundenen Verkäufe als Bestellungen in den eigenen Shop.

Der Onlinemarktplatz eBay stellt ein kostenfreies nutzbares API zur Verfügung, das den Zugriff auf die Daten eines eBay-Mitgliedskontos ermöglicht. Mithilfe dieses API können sämtliche Aspekte der während der Verkaufsabwicklung notwendigen Schritte realisiert werden. Dazu gehören elementare Funktionen wie das Einstellen und der Abruf von Verkäufen, aber auch die Kommunikation mit einem Käufer, die Verarbeitung der wichtigen Bewertungen und viele weitere Datenzugriffsfunktionen. Faktisch basiert die eFire-Anbindung von OXID auf dem eBay API (inklusive des PHP SDKs). Nachfolgend erhalten Sie einen Einblick in die Nutzung des eBay API mittels PHP und die Integration dieser Funktionen in das OXID-Shopsystem. Den Quellcode der Beispiele finden Sie auf der Heft-DVD. Funktionell sollen dabei zunächst nur Bereiche berührt werden, die sinnvoll das Leben als eBay-Verkäufer erleichtern. Das Beispielsystem kann selbstständig erweitert werden und sollte auch bei einer späteren Anbindung an OXID eFire weiterhin nutzbar sein.

Installation und Downloads

Für den Aufbau unseres Systems benötigen wir eine Reihe von Softwarekomponenten und müssen daneben einige Vorbereitungen treffen. Das Downloadpaket für OXID-eSales-Community-Edition finden Sie unter hier. Die Installation auf einem LAMP-System geht schnell und problemlos vonstatten. Nach dem Entpacken des Archivs und dem erstmaligen Aufruf der Website wird automatisch das Setupsystem von OXID eSales gestartet, das durch die Installationsroutine führt. Hierbei wird auf jeden Fall die Nutzung von PHP5 vorausgesetzt. Für den Zugriff auf das eBay API wird das „eBay Accellerator Toolkit for PHP/Trading Edition“ (EbatNs Trading) genutzt. Den Download hierzu finden Sie nach einer kurzen Registrierung hier. Achten Sie auch hier darauf, das Paket für PHP 5 zu laden. Dem aufmerksamen Leser fällt vielleicht auf, dass der Ersteller des EbatNs der Autor dieses Artikels ist. Daher können Sie alternativ auch das Quellcodepaket zum Artikel nutzen, der das EbatNs bereits enthält.

Setup des eBay API

Für den Zugriff auf das eBay API benötigen Sie eine Registrierung im eBay-Entwicklerprogramm. Das Anmeldeformular hierzu finden Sie hier. Die Teilnahme am eBay-Entwicklerprogramm ist grundsätzlich kostenlos. Als registrierter Entwickler erhalten Sie ein so genannte Key Triple, das der Anwendung den Zugriff auf das API ermöglicht. Die Anzahl von API-Aufrufen ist zunächst auf 5000 Zugriffe pro Monat beschränkt. Nach der Fertigstellung der Anwendung kann das Limit auf 1,5 Mio. Zugriffe täglich erhöht werden. Hierzu muss allerdings einmalig eine kostenpflichtige Zertifizierung vorgenommen werden. Im Rahmen der entstehenden Anwendung sollte die Limitierung aber kaum eine Rolle spielen. Es ist jedoch zu beachten, dass durch das eBay API z. B. mit dem Einstellen von Artikeln indirekt Kosten (Einstellgebühren) entstehen können.

eBay-Nomenklatur

Bei der Beschäftigung mit dem eBay API ist es unumgänglich, sich mit der englischen Nomenklatur vertraut zu machen. Betrachten wir hierzu kurz den eBay-Prozess unter Berücksichtigung der entsprechenden Termini.

Der eBay-Verkäufer (Seller) stellt einen Artikel bei eBay ein. Der Prozess wird dabei „Item Listing“ genannt. Als Ergebnis entsteht das Item mit seiner Item-Id (Artikelnummer). Während der Laufzeit einer Auktion (Chinese Auction) kann ein potentieller Bieter (Bidder) eine Nachricht (Message) an den Seller schicken. Ähnliches ist auch bei Sofort-Kaufen-Artikeln (Buy It Now = BIN) möglich. Mit dem Zuschlag für einen Artikel wird der so genannte HighBidder zum Buyer – entsprechendes gilt bei BIN-Items. Alle User besitzen eine sog. EIAS-ID, die auch nach einem Wechsel des eBay-Namens erhalten bleibt. Der Verkauf resultiert in der Erzeugung einer Transaktion, die aus Transaction-ID und Item-ID besteht. Mehrere Transaktionen können bei Bedarf in einer Order zusammengefasst werden. Ein erfolgreicher Abschluss endet dann in der Regel mit dem gegenseitigen Hinterlassen einer positiven Bewertung (Feedback). Alternativ kann mittels des Dispute-Managements bei aufgetretenen Problemen eine Rückabwicklung oder anderweitige Einigung erzielt werden.

Sandbox/Produktion

Während der Testphase einer Anwendung kann der eBay-Spielplatz (Sandbox) genutzt werden. Die Sandbox entspricht funktionell (zumeist) der echten Produktionsumgebung, ist aber auf der Datenbankebene vollständig getrennt. Dadurch kann hier testweise „gehandelt“ werden, es entstehen jedoch keine echten Kosten. Wie auch die große Schwester steht die Sandbox für die meisten Sprachversionen zur Verfügung. Die deutsche Sandbox erreichen Sie hier. Bitte beachten Sie, dass bestimmte Funktionen teilweise nur im englischen System verfügbar sind. Der häufig benötigte My-eBay-Bereich ist dann nur in englischer Sprache verfügbar. Das ist leider ein wenig unhandlich. Daneben werden die Sessiondaten jeweils in Browsercookies gespeichert und die parallele Nutzung von Sandbox und Produktion im gleichen Browser ist kaum möglich. Wichtig ist hier zu beachten, dass die Benutzer der Sandbox vollständig von der Produktionsumgebung getrennt sind. Damit funktioniert Ihr „normales“ eBay-Konto auf der Sandbox nicht und Sie sollten sich ein Set von Anmeldenamen zum Spielen anlegen. Hier stellt eBay ein Tool bereit. Damit Sie später auch Verkäufe simulieren können, ist die Anlage von mindestens einem Verkäufer- und einem Käufer-Konto sinnvoll.

Keys und Token

Vor der Nutzung des eBay API müssen zunächst die Keys erzeugt werden. Zunächst  benötigen Sie nur die Sandbox Keys – die Generierung der Production Keys kann bei Bedarf später erfolgen. Die DEV-ID ist dabei gleich – APP-ID und CERT-ID unterscheiden sich aber entsprechend. Die Keys verweisen letztlich lediglich auf die Anwendung. Das so genannte „Token“ speichert die Datenfreigabe für ein bestimmtes Benutzerkonto. Hier nutzt eBay das so genannte „Auth & Auth -Verfahren“, mit dem ein eBay-Benutzer den Datenzugriff an eine Anwendung delegieren kann. Das Verfahren leitet dabei den Benutzer über die „normale“ eBay-Anmeldeseite und reicht danach das Token an die 3rd-Party-Anwendung weiter. Das Token enthält verschlüsselt die Verbindung von Benutzer-ID und Anwendungs-ID, aber nicht das eBay-Passwort. Allerdings sollte das Token wie ein Passwort behandelt werden. Faktisch reicht das Token aus, um (auch indirekt kostenpflichtige) API-Aufrufe durchzuführen. Auch hier steht im Entwicklerbereich ein Tool zur Verfügung. Hiermit lassen sich schnell einmalige Token erzeugen und via Copy & Paste übernehmen. Achten Sie bei der Erzeugung von Sandbox Token auf die Besonderheiten der Benutzerkonten in der Sandbox.

Funktionsweise des eBay API und des EbatNs

Das eBay API stellt eine enorme Vielfalt von Funktionen zur Verfügung. Dabei wurden die unterschiedlichen Bereiche in diverse „Produkte“ aufgeteilt. Für unser Projekt benötigen wir den Zugriff auf das Trading API. Hiermit erhalten wir Zugriff auf die Daten aus dem Bereich My eBay. Andere APIs wie etwa das Shopping API liefern lediglich öffentlich zugängliche Daten wie Suchergebnisse oder Basisinformationen über einen eBay-Nutzer unter seinem Pseudonym. Hier wird dann kein Token benötigt und die Nutzung damit vereinfacht. Technisch wurde das eBay API als XML Web-Service realisiert, wobei hier historisch bedingt unterschiedliche serverseitige Frameworks im Einsatz sind. Sinnvoll ist dabei die Nutzung eines SDKs (wie hier des EbatNs), das diese technischen Aspekte für den Entwickler transparent macht. Neben der synchronen Aufrufform der Web Services existiert eine weitere, interessante Alternative. Die so genannte eBay Platform Notifications liefern die Ergebnisdaten eines API-Aufrufs automatisch an einen hinterlegten URL oder ein E-Mail-Konto. Dabei werden die Aufrufe automatisch nach dem Auftreten eines Ereignisses ausgelöst. So kann z. B. nach Verkaufsabschluss automatisch eine Benachrichtigung verschickt werden. Das eBatNs PHP SDK bildet die Funktionen des eBay API in Form von PHP-Klassen ab. Das Sessionobjekt speichert dabei die API Keys und eventuell das Token eines Benutzers. Das Proxy-Objekt wird mit dem Sessionobjekt verbunden und definiert die nutzbaren API-Funktionen nach. Als Eingabe wird jeweils ein Call-spezifisches Request-Objekt erwartet. Entsprechend wird ein Response-Objekt durch den Methodenaufruf zurückgeliefert.

Ein neues Oxid-Modul

Die Integration in OXID hinein erfolgt in Form eines neuen Moduls. In Abbildung 1 sehen Sie den dazu angelegten Bereich im Source-Code-Ordner des OXID-Shops. Faktisch muss hierzu nur eine Datei menu.xml im angelegten Modulordner /cxebayutils/ existieren und eine Moduldatei cxebayutils.php direkt im Modulordner angelegt werden. Die gleichnamige Modulklasse cxebayutils erbt hier zur Vereinfachung einfach von der in OXID vordefinierten Klasse oxAdminView. Durch das Überschreiben der Methode render kann dann die Funktionalität des Moduls definiert werden (Abb. 1).

Abb. 1: Das OXID-Modul in der Dateistruktur

Abb. 1: Das OXID-Modul in der Dateistruktur

Die Datei menu.xml beschreibt die Menüstruktur, unter der die neuen Funktionen erreichbar sein sollen. Der Beispielcode enthält daneben die Datei cxebayutils_lang.php, die die sprachspezifischen Werte für die Menüeinträge beinhaltet. Um nicht für jede Funktion ein neues Modul anlegen zu müssen, wurde hier der Wert clparam missbraucht. Das Modul (Klasse cxebayutils) delegiert dann an das entsprechende Submodul weiter. Schließlich muss das Modul noch im OXID-System bekannt gemacht werden. Hier wählen Sie im Admin-Bereich des Shops den Bereich Stammdaten / Grundeinstellungen / System / Module und fügen dort die Zeile cxebayutils => cxebayutils/cxebayutils hinzu (Abb. 2).

Abb. 2: Aktivierung des OXID Moduls

Abb. 2: Aktivierung des OXID Moduls

OXID arbeitet für die Darstellung fast ausschließlich mit der Template Engine Smarty. Das gilt auch für die Darstellung des Menüsystems. Damit die menu.xml genutzt und das Menü entsprechend erweitert wird, muss nun noch der Smarty Cache geleert werden – am einfachsten durch das Löschen des Verzeichnisses /tmp/ unter dem OXID-Shopordner. Nach dem erneuten Login in den Admin-Bereich sollte dann der soeben erstellte Menübereich angezeigt werden.

Testen der API-Schnittstelle

Bevor wir nun mit dem Test der Schnittstelle arbeiten, müssen wir unsere eBay API Keys und ein Token eintragen. Hierzu dient zunächst die Datei ebay.config.php. Unter den entsprechenden Einträgen innerhalb dieser INI-Datei sind die Keys einzutragen. Dabei existieren Einträge mit -test für die Sandbox und -prod für die Produktionsumgebung. Achten Sie darauf, dass die Werte hier in Anführungszeichen angegeben werden, um Seiteneffekte zu vermeiden. Daneben kann hier mittels app-mode die entsprechende Umgebung gewählt werden. Sollten Sie mit einer anderen Site als eBay Deutschland arbeiten wollen, tragen Sie unter site-id den entsprechenden von eBay definierten Wert ein.

Für die Testphase macht die Nutzung der deutschen Sandbox mit den entsprechenden Einträgen Sinn. Später kann mit entsprechenden Änderungen an der Config-Datei das System auf die Nutzung in der Produktionsumgebung umgestellt werden. Zum Schluss benötigen wir noch ein Token. Dieses können Sie wie beschrieben auf der Website des eBay-Entwicklerprogramms erzeugen. Die Daten des Token werden nun in einer Datei abgelegt. Dabei dürfen hier keine weiteren Zeichen (Kommentare oder Leerzeichen) hinzugefügt werden. Der Dateiname wird nun in der Config-Datei gesetzt. In der dieser Datei wird der Dateiname als absolut oder relativ zum aktuellen Verzeichnis vorausgesetzt. Bitte beachten Sie, dass im Beispielcode hier eine Anpassung vorgenommen wurde. Der Pfad der Token-Datei wird relativ zum Modulverzeichnis erwartet. Im Beispielcode werden die Token-Dateien im Ordner /tokens/ abgelegt und entsprechend in der Config-Datei z. B. mit /tokens/meine_token_datei.token/ erwartet. Nach diesen Vorbereitungen sollte nun die Nutzung der Modulfunktionen fehlerfrei möglich sein.

Wie viel Uhr hat es bei eBay geschlagen?

Exemplarisch für andere eBay API Calls kann der Call Get eBay Offical Time für einen ersten Test genutzt werden. Die Datei cxEbConfig.php realisiert hier den eBay API Call. Die Erzeugung der EbatNs-Session und des Proxies wurde in eine Basisklasse ausgelagert und dient auch in allen anderen Beispielen als Grundlage. Den Basisaufbau für den Ablauf eines eBay API Calls zeigt Listing 1.

Listing 1: Ein einfacher API Call

require_once 'ebatns_lib/EbatNs_ServiceProxy.php';
require_once 'ebatns_lib/GeteBayOfficialTimeRequestType.php';

$session = new EbatNs_Session('config/ebay.config.php');        
$proxy = new EbatNs_ServiceProxy($session);

$req = new GeteBayOfficialTimeRequestType();
$res = $proxy->GeteBayOfficialTime($req);
print_r($res);

Die Auslösung des Calls ist dabei höchst einfach. Bei vorhandenem Proxy-Objekt muss lediglich das Call-spezifische Request-Objekt erzeugt werden. Eventuell können hier mit entsprechenden Setter-Methoden weitere Parameter gesetzt werden. Das Request-Objekt wird nun zum Parameter der entsprechenden Methode auf dem Proxy. Das Ergebnis ist ein PHP-Objekt des durch den Call definierten Response-Typs. Innerhalb der OXID-Integration können nach dem Call die Ausgabedaten für die Darstellung im Smarty Template vorbereitet werden. Bei unserem Test ist das trivial – andere Calls liefern hier eventuell Listen zurück, die jeweils iteriert oder formatiert werden müssen.

Meine Artikel und Verkäufe

Für die Darstellung der aktuell auf eBay laufenden Artikel kann der Call Get My eBay Selling genutzt werden. Hiermit erhalten wir alle laufenden Artikel aber auch (minimale) Informationen bei einem Verkauf. Die Implementierung hier ist natürlich deutlich komplexer, aber im Rahmen des Machbaren (cxEbArticles.php). Bei der Auswertung der Daten müssen zwei grundsätzliche Aspekte betrachtet werden. Als international ausgerichtetes System liefert eBay sämtliche Zeitangaben als GMT. Damit sind die Angaben entsprechend der Zeitzone umzurechnen. Bei Operationen, die solche Listen liefern, werden die Daten in der Regel paginiert. Das API liefert dann jeweils ein Datenfenster von bis zu 200 Einträgen. Weitere Datenfenster können dann mit einem erneuten Call unter Angabe der Seite abgerufen werden.

Ausblick

Die Nutzung des eBay API und die Integration in das Shopsystem OXID eSales lassen sich mit vorliegendem Beispiel schnell um weitere Funktionalitäten erweitern. Das Gespann bietet eine Vielzahl von Möglichkeiten, eBay-Verkäufern Routinearbeiten abzunehmen.

Vielleicht ist innerhalb der Leserschaft auch jemand geneigt, eine erweiterte Lösung im OXID eXchange anderen Nutzern zur Verfügung zu stellen.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -