eBay API
Carsten Harnisch
eBay API
schnell + kompakt
Carsten Harnisch eBay API schnell + kompakt Frankfurt, 2007 ISBN 978-3-939084-20-4
© 2007 entwickler.press, ein Imprint der Software & Support Verlag GmbH
http://www.entwickler-press.de http://www.software-support.biz Ihr Kontakt zum Verlag und Lektorat:
[email protected] Bibliografische Information Der Deutschen Bibliothek Die Deutsche Bibliothek verzeichnet diese Publikation in der Deutschen Nationalbibliografie; detaillierte bibliografische Daten sind im Internet über http://dnb.ddb.de abrufbar.
Korrektorat: Petra Kienle Satz: text & form GbR, Carsten Kienle Umschlaggestaltung: Melanie Hahn, Maria Rudi Belichtung, Druck und Bindung: M.P. Media-Print Informationstechnologie GmbH, Paderborn. Alle Rechte, auch für Übersetzungen, sind vorbehalten. Reproduktion jeglicher Art (Fotokopie, Nachdruck, Mikrofilm, Erfassung auf elektronischen Datenträgern oder andere Verfahren) nur mit schriftlicher Genehmigung des Verlags. Jegliche Haftung für die Richtigkeit des gesamten Werks kann, trotz sorgfältiger Prüfung durch Autor und Verlag, nicht übernommen werden. Die im Buch genannten Produkte, Warenzeichen und Firmennamen sind in der Regel durch deren Inhaber geschützt.
Inhaltsverzeichnis Kapitel 1: Vorwort 1.1 Ressourcen Allgemein Entwicklung Softwaremarketing und Programme 1.2 Aktuelle Trends und Möglichkeiten für Entwickler Web 2.0 Nutzung von eBay-Marktdaten Monetarisierungsmöglichkeiten im eBay-Partnerprogramm Mobilfunklösungen IPTV
9 12 12 12 12 13 13 13
Kapitel 2: Der eBay-Geschäftsprozess 2.1 Benutzerrollen 2.2 Einstellen von Artikeln Auktion, Shop, eBay Express Kategorien Attribute Versand Zahlungsbedingungen Auktionsdauer Menge Features Bilder 2.3 Artikelnummer/ItemID 2.4 Beobachtung während der Auktion 2.5 Änderung von Artikeln 2.6 Transaktion
17 17 18 18 19 20 20 21 21 21 22 22 23 24 24 24
schnell + kompakt
5
14 14 15
Inhaltsverzeichnis
2.7 2.8 2.9 2.10 2.11 2.12
Verkaufsabwicklung und Bestellung Externe Verkaufsabwicklung Feedback bekommen und hinterlassen Gebühren Dispute-Management Besondere Artikelformen Second Chance Best Offer GetItFast und NowAndNew WantItNow eBay Express
25 26 26 27 27 28 28 28 29 29 29
Kapitel 3: eBay für Techniker 3.1 Alle Sites ein System Organisation in Sites Standard-Sites, Rest-World-Sites Versionierung und Compatibility-Level 3.2 Sandbox und Production 3.3 Keys und Zertifizierung 3.4 Token 3.5 URLs 3.6 Initialer Start und Testbenutzer
31 31 32 32 32 33 34 35 36 36
Kapitel 4: SDK oder nicht SDK 4.1 Dokumentation 4.2 SOAP Windows SDK Java SDK eBay PHP Accellerator Toolkit 4.3 REST 4.4 Direkter Zugriff
39 40 40 41 42 42 43 43
6
Inhaltsverzeichnis
Kapitel 5: eBay API – Technical Basics 5.1 Auth&Auth ReturnURL Auth&Auth Redirect Auth & Auth Fetchtoken Redirect ohne Token 5.2 Poll and Push Notifications 5.3 Compatibility Levels 5.4 Detail Level und Granularity Level 5.5 Paginierung 5.6 Behandlung von Datums- und Zeitwerten 5.7 Lookup-Werte Kategorie und Features CharacteristicsSets eBay-Details 5.8 Aufbau eines Call SOAP XML Request Token HTTPs Call Response
45 45 45 47 47 47 48 48 49 50 51 51 52 53 53 54 54 55 56 57 58
Kapitel 6: eBay API – can do 6.1 Einstellen von Artikeln Crosspromoting Ending Items Revise Relist SecondChance Messaging
59 59 60 60 61 61 61 62
schnell + kompakt
7
Inhaltsverzeichnis
6.2 Verkaufsabwicklung Abruf von Transaktionen Order, Combined Payment Feedback 6.3 Suchen von Artikeln 6.4 Dispute UPI – Unpaid Item INR – Item Not Received
62 63 64 64 64 66 66 67
Kapitel 7: eBay API – Technical Advanced 7.1 Versandoptionen national und international 7.2 Attribute und Kataloge 7.3 eBay Shops 7.4 Verwalten von Bildern
69 69 70 73 74
Kapitel 8: Code-Beispiele 8.1 Installation und Basisparameter 8.2 Proxy, Session und Request 8.3 Artikelsuche 8.4 Artikel einstellen 8.5 Transaktionen abrufen 8.6 Kommunikation mit Käufer und Verkäufer 8.7 Rechnung schicken 8.8 Feedback hinterlassen 8.9 Kategorien abrufen
77 78 78 79 82 84 85 86 87 88
Anhang: Kurzbeschreibung zu jedem API-Call
91
Stichwortverzeichnis
8
107
KAPITEL 1 Vorwort 1.1
Ressourcen
1.2
Aktuelle Trends und Möglichkeiten für Entwickler 13
12
eBay ist der weltweite Online-Marktplatz. 1995 in Kalifornien als Marktplatz für den Austausch von Sammlerartikeln gegründet, hat sich das E-Commerce-Unternehmen sehr rasch zum besucherstärksten Marktplatz für den Verkauf von Gütern und Dienstleistungen durch Privatpersonen und Unternehmen entwickelt. Als eines der wenigen Unternehmen der Internetwirtschaft ist eBay seit seiner Gründung durchgehend profitabel. eBay finanziert sich über eine Angebotsgebühr sowie eine Provision, die dem Verkäufer bei einem erfolgreichen Verkauf in Rechnung gestellt wird. Jeden Tag werden in Tausenden von Kategorien Millionen von Artikeln angeboten. eBay ermöglicht dabei den Handel auf regionaler, nationaler und globaler Ebene. Der Online-Marktplatz ist in 33 internationalen Märkten auf vier Kontinenten präsent. Die deutsche eBay GmbH wurde 1999 in Berlin gegründet; Mitte 2000 wurde der Geschäftssitz in den Europarc Dreilinden vor den Toren der deutschen Hauptstadt verlegt. Innerhalb der auch in Deutschland ständig wachsenden „OnlineGemeinde“ gilt eBay als großer Sympathieträger – Surfen und Suchen, Anbieten und Kaufen bei eBay macht Spaß und gilt bei
schnell + kompakt
9
1 – Vorwort
Internetfans aller Altersgruppen als „Kult“. Bei eBay finden nicht nur mit Abstand die meisten privaten Käufe und Verkäufe im Internet statt; der Auktionsmechanismus garantiert allen eBayMitgliedern auch faire Preise und gleichbleibend hohe Qualität. Inzwischen sind es bereits über 212 Millionen registrierte Mitglieder auf allen Kontinenten, die bei eBay handeln. Der Reiz des Handelns bei eBay liegt nicht zuletzt darin, dass die Funktionsweise des virtuellen Marktplatzes kinderleicht ist. Außer dem Online-Auktionsverfahren, durch das eBay weltbekannt wurde, ermöglicht der eBay-Marktplatz auch den Handel zu Festpreisen. Dabei kann der Verkäufer entweder das Auktionsformat mit einer „Sofort-Kaufen“-Option kombinieren oder aber seinen Artikel ausschließlich zu einem reinen Festpreis anbieten. Die eBay Shops bieten einem eBay-Verkäufer die Möglichkeit, ein eigenes virtuelles Ladengeschäft bei eBay zu betreiben. Der persönliche Verkaufsraum kann von seinem jeweiligen Inhaber mit einem Wunschnamen versehen und den eigenen Bedürfnissen entsprechend individuell gestaltet werden. Innerhalb seines eBay Shops kann der Betreiber nach seinen eigenen Vorstellungen unterschiedliche Kategorien definieren und sein Artikelangebot damit optimal strukturieren. Auf dem neuen Online-Marktplatz eBay Express verkaufen ausschließlich gewerbliche Anbieter Neuware zum Festpreis. Mit diesem Service kommt eBay den Wünschen und Bedürfnissen vieler Mitglieder nach: „Mit eBay Express bieten wir ein klassisches Online-Einkaufserlebnis. Jetzt ist es noch bequemer und einfacher, auf unserem weltweiten Online-Marktplatz zu handeln“, so Dr. Stefan Groß-Selbeck (Geschäftsführer eBay Deutschland). eBay Express ist ein idealer zusätzlicher Vertriebsweg für alle Online-Händler – auch für Anbieter, die bisher noch nicht bei eBay handeln. Gewerbliche Verkäufer haben die Chance, ihre Produkte professionell auf einem bekannten Online-Marktplatz zu
10
Vorwort
platzieren. Allein bei eBay in Deutschland handeln über 20 Millionen Mitglieder – somit warten über 20 Millionen potenzielle Kunden. Bis auf sehr wenige Ausnahmen, wie z.B. die erstmalige Anmeldung oder das Bieten, werden sämtliche Funktionen und Formate durch die eBay Web Services seit dem Jahr 2001 unterstützt. Softwareentwicklern bieten sich unzählige Möglichkeiten, neuartige Tools für eBay-Kunden zu entwickeln. Ursprünglich wurde diese API zusammen mit einem Tool-Hersteller initiiert, sie stand zunächst nur einer kleinen Gruppe von Fremdanbietern zur Verfügung. Die größte Hürde waren zunächst die Kosten der API-Nutzung, die sich schnell auf mehrere 10.000 US-Dollar belaufen konnten. Der erste Schritt war dementsprechend die massive Senkung der Kostenstrukturen; Ende 2005 wurde die APINutzung dann vollständig kostenfrei. Heute wird damit jedem Entwickler ein Weg eröffnet, beliebige Anwendungen unter Zuhilfenahme der eBay API zu entwickeln. Betrachten wir die reinen Zahlen der eBay API, so sprechen diese für sich: 쐌 Über 40.000 Softwareentwickler haben sich weltweit im eBayEntwicklerprogramm registriert, davon über 7.000 in Deutschland. 쐌 Über 25 % aller Artikel auf eBay.com werden durch Anwendungen Dritter – also mittels der eBay API – eingestellt. 쐌 Die eBay Web Services verarbeiten täglich über 100.000.000 API Calls aus über 120 unterschiedlichen API Calls, die nahezu die komplette Funktionalität der Website abbilden. Mit diesem kleinen Büchlein möchte ich Ihnen einen Überblick über die Möglichkeiten der eBay API geben. Die wenigen verfügbaren Seiten verbieten leider eine detaillierte Vertiefung der technischen Details. Allerdings zeigt meine Erfahrung mit „zukünftigen API-Entwicklern“, dass es häufig eher die Lücken im
schnell + kompakt
11
1 – Vorwort
Gesamtbild sind als die Kenntnis jedes Parameters, die die berühmten Anfangshürden darstellen.
1.1 Ressourcen Allgemein 쐌 쐌 쐌 쐌
Deutsche Entwicklerseiten: http://entwickler.ebay.de Internationale Entwicklerseiten: http://developer.ebay.com Applikationsverzeichnis: http://applikationsverzeichnis.ebay.de Blog des eBay-Entwicklerprogramms: http://ebaydeveloper.typepad.com/
Entwicklung 쐌 Testtool – Ausführung von Test Queries: http://developer.ebay.com/testtool 쐌 Tokentool – Generierung eines Auth&Auth-Token: http://developer.ebay.com/tokentool 쐌 Software Development Kits (SDKs): http://pages.ebay.de/entwickler/sdk.html 쐌 Forum: http://developer.ebay.com/forums 쐌 Knowledgebase des Entwicklerprogramms: http://ebay.custhelp.com 쐌 Open Source – Community Codebase: http://www.codebase.ebay.com 쐌 Hilfeseiten: http://developer.ebay.com/support/
Softwaremarketing und Programme 쐌 Zertifizierungsprogramm für Lösungsanbieter: http://pages.ebay.de/entwickler/zla.html 쐌 Zertifizierungsprogramm für Berater rund um eBay: http://pages.ebay.de/entwickler/consulting.html
12
Aktuelle Trends und Möglichkeiten für Entwickler
쐌 Partnerprogramm zur Einbindung und Monetarisierung von eBay-Inhalten : http://partnerprogramm.ebay.de (den dazugehörigen Affiliates API Tier finden Sie hier: http://developer.ebay.com/devprogram/membership/affiliate.asp) 쐌 eBay-Marktdatenprogramm zur statistischen und strategischen Analyse: http://marktdaten.ebay.de 쐌 PayPal Developer Network: http://www.paypal.com/pdn/ 쐌 Skype Developer Network: http://share.skype.com/sites/devzone/
1.2 Aktuelle Trends und Möglichkeiten für Entwickler Web 2.0 Web 2.0 ist derzeit ein viel diskutiertes Thema und gerade im Bereich der Verschmelzung von geografischen Informationen, Angeboten bei eBay, Landkarten und Planeten-Browsern lassen sich viel neue Mashups realisieren, z.B. über eine Produktanzeige in Google Maps oder Microsoft Virtual Earth. Auctionmapper.com liefert beispielsweise nicht nur eine geografische Anordnung von gesuchten Artikeln, sondern die Webapplikation stellt vielfältige innovative Such- und Browsing-Funktionalitäten zur Verfügung, die es in der Form bei eBay noch nicht gibt. Weitere Beispiele sind die Website www.dudewheresmyusedcar.com, die Daten von eBay Motors geografisch anzeigt, oder www.housingmaps.com im Immobilienbereich.
Nutzung von eBay-Marktdaten Weitere Beispiele für innovative Lösungen sind Tools, die sich der eBay-Marktdaten (http://marktdaten.ebay.de) bedienen und auf dieser Basis Trends in den eBay-Kategorien, Preisvergleiche oder Analysen für spezielle Produkte anbieten. Verschiedene Sites
schnell + kompakt
13
1 – Vorwort
liefern heute schon sehr aufwändige Vergleichs- und Trendbarometer, wie z.B. www.mpire.com oder auch www.ebay.com/ebaypop. DataUnison (www.dataunison.com) bietet Entwicklern zudem seit Mitte 2006 eine neuartige Research-API an, die Ad-hoc-Abfragen z.B. von Durchschnittspreisen ermöglicht. Daneben werden auch Tools zur Überwachung der eigenen Artikel immer wichtiger für die frühzeitige Erkennung von sich ändernden Markttrends (www.mrcounter.de).
Monetarisierungsmöglichkeiten im eBay-Partnerprogramm Als eines der wenigen großen Entwicklerprogramme bietet eBay externen Entwicklern handfeste Monetarisierungsmöglichkeiten über das Partnerprogramm (http://partnerprogramm.ebay.de) und kann dabei auf eine schier unerschöpfliche Produktdatenvielfalt zurückgreifen. Eine Reihe von Entwicklern versucht mittels Relevance-Ads, eBay-Artikel zu bewerben und Benutzerströme von ihren eigenen Seiten auf eBay weiterzuleiten. Im Gegenzug kassieren diese Geld für Clicks, Gebote bzw. Neuanmeldungen.
Mobilfunklösungen UMTS, HSDPA, WLAN, Bluetooth und weitere drahtlose digitale Übertragungsformen werden in Zukunft wesentlich größere Datenübertragungsgeschwindigkeiten und -volumen sowie neue Rückkanäle für mobile Endgeräte zulassen. Zudem werden sich in den nächsten Jahren Smartphones und Multifunktionsgeräte mehr und mehr durchsetzen, sodass auch der Nutzung von eBay und Skype über das Handy keine Hürden mehr im Weg stehen. In diesem Segment ist vieles an Innovationen möglich und eBay deckt mit seinem WAP-Portal und SMS-Service bisher nur einen begrenzten Bereich ab (http://unterwegs.ebay.de). Auch im Applikationsverzeichnis findet man derzeit nicht einmal eine Handvoll
14
Aktuelle Trends und Möglichkeiten für Entwickler
Anwendungen in dieser Kategorie (http://applikationsverzeichnis. ebay.de).
IPTV Die Zukunft des digitalen Fernsehens hat längst begonnen. Jedoch gibt es bisher erst eine einzige Applikation für eBay auf dem Fernseher, die auf der Microsoft Mediacenter Edition aufsetzt und von http://www.scendix.de angeboten wird. DownloadFernsehen hat Zukunft und damit auch alternative Werbeformate, die beispielsweise auf Basis des eBay-Partnerprogramms für Nischensender interessant sein könnten.
schnell + kompakt
15
KAPITEL 2 Der eBay-Geschäftsprozess 2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9 2.10 2.11 2.12
Benutzerrollen Einstellen von Artikeln Artikelnummer/ItemID Beobachtung während der Auktion Änderung von Artikeln Transaktion Verkaufsabwicklung und Bestellung Externe Verkaufsabwicklung Feedback bekommen und hinterlassen Gebühren Dispute-Management Besondere Artikelformen
17 18 23 24 24 24 25 26 26 27 27 28
Zunächst sollten Sie sich detailliert über den eBay-Geschäftsprozess im Klaren sein. Vielfach ergeben sich Probleme mit der API allein daraus, dass falsche Annahmen über die Abläufe bestehen.
2.1 Benutzerrollen Nach der initialen Registrierung kann ein Konto (eBay-Slang = eBay-ID) sofort für Käufe genutzt werden. Einzige Ausnahme ist die Registrierung als gewerblicher Verkäufer, bei welcher der Bestätigungs-Code in einem via Post versandten Brief enthalten ist. Sobald für ein eBay-Konto auch Bankinformationen hinterlegt wurden (eBay-Slang = CreditCardOnFile), kann die eBay-ID auch für Verkäufe genutzt werden. Bestimmte weitere Regelungen verhindern zunächst die Nutzung sämtlicher Möglichkeiten.
schnell + kompakt
17
2 – Der eBay-Geschäftsprozess
Die Nutzung von Ein-Tages-Auktionen ist z.B. erst nach zehn Bewertungspunkten möglich; die Nutzung von JavaScript nur für PowerSeller oder verifizierte Mitglieder. Im Rahmen der Teilnahme an einer Auktion ist der potenzielle Käufer zunächst ein Bieter (Bidder). Als Höchstbieter (HighBidder) führt dieser die Bieterliste an. Bei Ablauf der Auktion wird der HighBidder automatisch zum Käufer (Buyer), eventuelle andere Bieter zu „unterlegenen Bietern“.
2.2 Einstellen von Artikeln Aus Sicht von eBay beginnt der Prozess mit dem Einstellen eines Artikels. Dabei ist es unwesentlich, ob der Artikel nun mittels der API oder über einen anderen Weg eingestellt wurde. Typisch etwa wäre die Nutzung des Verkaufsformulars (SYI = SellYourItem) oder vielleicht des Turbolisters. Wobei Letzterer nichts anderes als eine Anwendung ist, die auch die eBay API nutzt. Für das Auslösen des Einstellvorgangs muss ein entsprechendes eBay-Konto genutzt werden, das die notwendigen Voraussetzungen bereits erfüllt. In der Dokumentation wird der Vorgang des Einstellens eines Artikels oft als „Listen“ bezeichnet – hiermit ist der engl. Begriff „list an item“ gemeint. Daneben wird auch allgemein von Auktionen gesprochen, wobei hierin eventuell auch Sonderformen wie Festpreis- oder Shop-Artikel eingeschlossen sind.
Auktion, Shop, eBay Express Die API-Dokumentation spricht immer von einem Artikel (= Item); unabhängig davon, ob es sich um eine Auktion (inklusive der Sonderformen wie SofortKauf-Option), einen Festpreisartikel, einen Shop-Artikel, einen eBay-Express-Artikel oder ein
18
Einstellen von Artikeln
Angebot im Bereich Immobilien handelt. Die API-Methode AddItem initiiert die Einstellung des Artikels und liefert bei Erfolg eine eindeutige ID (ArtikelNr oder ItemID) nebst der anfallenden Gebühren zurück. Zur Unterscheidung der unterschiedlichen Artikelformen wird das Feld „ListingType“ genutzt. Hierdurch ergibt sich zunächst bei der Einstellung die Anforderung, bestimmte Felder setzen zu müssen, und im weiteren Ablauf eine differierende Behandlung. In der API wird die „normale“ Auktion als „Chinese-Auction“ bezeichnet, die „Power-Auktion“ als „Dutch-Auction“. Die historische Wandlung vom reinen Online-Auktionshaus zur Shopping Mall lässt sich auch in der API ablesen. Hier wird sowohl für Auktionen als auch für Festpreisartikel stets das Feld „StartPrice“ genutzt, obwohl es bei letzterem Typ ein wenig verwirrend klingen mag. In Bezug auf die Einstellung ist es unbedingt notwendig, Felder wie „Title“, „Description“ (Artikelbeschreibung) und „Price“ (in den unterschiedlichen Variationen) zu bestimmen.
Kategorien Eine wesentliche weitere Information besteht in der Angabe der Kategorie, in welcher der Artikel später erscheinen soll. Technisch gesehen besteht die Kategorie lediglich aus einer Zahl, die in das entsprechende Feld zu setzen ist. Hierbei ist zu beachten, dass die eBay-Kategorien hierarchisch organisiert sind, wobei für die Einstellung lediglich die so genannten Leaf-Kategorien genutzt werden dürfen. Durch die Organisation der Kategorien als Baumstruktur ergeben sich zunächst so genannte Parent-Kategorien, die mehrheitlich lediglich weitere Parent-Kategorien enthalten. Letztlich erhalten wir die Blätter des Baums (Leafs), die zur Einstellung genutzt werden können.
schnell + kompakt
19
2 – Der eBay-Geschäftsprozess
Attribute Mithilfe von Attributen können besondere Merkmale eines Artikels abgebildet werden, etwa die KW-Zahl eines PKW, die ISBN eines Buches oder der Mietpreis einer Immobilie. Zwangsläufig ergeben sich dadurch unterschiedliche so genannte „CharacteristicsSet“ (CsSets) für die einzelnen Kategorien, welche die möglichen dort nutzbaren Attribute bestimmen. Neben diesen kategorienbezogenen CsSets besitzt eBay Deutschland (sowie Österreich und Schweiz) die Besonderheit der so genannten „SideWide-CsSets“. Hierzu gehören etwa die Angabe des Rückgaberechts und das Merkmal „Artikel-Zustand (neu/ gebraucht)“.
Versand Die Angabe der Versandkosten zu einem Artikel wurde im Laufe der Evolution der API mehrfach angepasst. Die aktuelle Version nutzt dabei ein zwar recht komplexes System von festen (flat shipping) und berechneten Versandkosten (calculated shipping), das aber leider – insbesondere auf eBay Deutschland – nur selten flexibel genug ist und eher der inneramerikanischen „Versandkostenwelt“ entspricht. Pro Artikel lassen sich zunächst drei unterschiedliche Versandarten für den Versand „im Land“ festlegen (etwa unversichert, versichert, Nachnahme). Hier spricht eBay von den „domestic shipping services“. Hinzu kommen drei weitere internationale Versandarten, bei denen jeweils auch die „Zielgebiete“ anzugeben sind. Insbesondere hier sind die Beschränkung und die Gruppierung der Zielgebiete stark störend. So gehört etwa die Schweiz aus eBay-Sicht zu Europa, was rein geografisch richtig ist. Allerdings wird die Besonderheit der Nichtzugehörigkeit zur EU in Bezug auf Mehrwertsteuer und Versandablauf ignoriert.
20
Einstellen von Artikeln
Ebenso sind etwa Besonderheiten beim Versand nach Großbritannien (Inselaufschlag) nur schwer realisierbar. Aus diesem Grund verzichten viele Verkäufer auf die Nutzung der eBay-eigenen Versandkostenangaben und bilden eigene Muster in der Artikelbeschreibung ab. Insbesondere aber in Hinblick auf eBay Express ist dies problematisch, da die Angabe von Versandkosten hier unabdingbar ist.
Zahlungsbedingungen Zur Angabe von Zahlungsbedingungen kann zwischen unterschiedlichen Zahlungsmethoden gewählt werden. Da die meisten innerdeutschen eBay-Verkäufer sicherlich die Möglichkeit der Banküberweisung bzw. Nachnahme nutzen, spielen alle anderen Methoden eine untergeordnete Rolle. Insbesondere die Nutzung von PayPal kann bei grenzüberschreitenden Verkäufen aber eine interessante Alternative sein.
Auktionsdauer Die nutzbare Auktionsdauer hängt von einer Reihe von Faktoren ab. Zunächst einmal ist der Typ des Artikels ausschlaggebend. Normale Auktionen etwa ermöglichen eine Zeitraumwahl von 1, 3, 5, 7 oder 10 Tagen. Für Shop-Artikel gelten Zeiträume von 30, 60 und 90 Tagen. Bestimmte Kategorien – etwa Immobilien – nutzen andere Regeln, daneben kann die Nutzung einer bestimmten Auktionsdauer vom Status des Verkäufers abhängig sein.
Menge Die Menge ist ein notwendiges Datenfeld für die Einstellung eines Artikels. Normale Auktionen haben hier immer den Wert 1.
schnell + kompakt
21
2 – Der eBay-Geschäftsprozess
Andere Typen können auch eine höhere Anzahl nutzen. In der Regel werden die Gebühren dann als Vielfaches der Menge berechnet. Einige Kategorien bieten zudem die Möglichkeit zur Einstellung von Chargen (lots), z.B. 10 Chargen à 100 Stück. Hier wäre die Menge dann 10 und die „lot“-Größe 100.
Features Insbesondere für die Sichtbarkeit von Artikeln in Kategorien mit großem Angebot kann die Nutzung der so genannten Features notwendig und sinnvoll sein. Teilweise ergeben sich diese Features (etwa Untertitel) indirekt durch das Setzen des entsprechenden Feldes. Andere Features wie etwa Bold (Fettschrift) und Border (Rahmen) werden explizit angegeben. Wiederum andere wie GalleryFeatured (Topangebot in Galerie) dürfen erst in Zusammenhang mit anderen Werten, wie hier dem Galeriebild, genutzt werden.
Bilder Abbildungen sind ein wichtiges Mittel, um den Verkaufserfolg sicherzustellen. Aus Sicht der API gibt es verschiedene Möglichkeiten, einen Artikel mit Bildern anzureichern. Der einfachste Weg besteht darin, in die Artikelbeschreibung mittels geeigneter HTML-Auszeichnungen (IMG-Tag) die gewünschten Bilder „einzubetten“. Hierbei müssen die URLs auf Server zeigen, die auch von den eBay-Käufern erreichbar sind. Aus Sicht von eBay sind dies „extern gehostete“ Bilder. Eine besondere Rolle kommt dem ersten Bild zu. Dieses wird oben außerhalb der Artikelbeschreibung gezeigt und muss in einem speziellen Feld übergeben werden. Wichtig ist hier, dass eBay die URL direkt übernimmt – ein Abruf der Auktion führt also zu Traffic auf dem Bilder-Server.
22
Artikelnummer/ItemID
Das Galeriebild wird hingegen in jedem Fall von einem Robot heruntergeladen, eventuell skaliert und während der Auktion automatisch auf einem eBay-Server gehostet. Steht kein eigener Bilder-Server zur Verfügung, kann auch ein eBay-eigenes System genutzt werden. Neben dem reinen Hosting der Bilder stehen hier weitere Möglichkeiten (Diashows, Galerien etc.) zur Verfügung, die allerdings sämtlich kostenpflichtig sind. Für den Upload von Bildern auf dieses System (EPS = eBay Picture Service) gibt es bisher keine offizielle Dokumentation – Anleitungen dazu kursieren allerdings im Internet.
2.3 Artikelnummer/ItemID Zur eindeutigen Identifikation von Artikeln wird die so genannte ItemID genutzt. Die Zahl hat zurzeit eine Länge von zwölf Stellen, wobei dies keine verlässliche Aussage ist, sprich: Die Anzahl der Stellen kann sich in Zukunft durchaus erhöhen. Diese Nummer ist weltweit eindeutig und wird jeweils in Bereichen vergeben. Eine Ableitung, wann eine ItemID vergeben wurde oder wird, ist aber nur Eingeweihten möglich und der Algorithmus ist nicht öffentlich. Wesentlich ist, dass die ItemID von eBay vergeben wird und somit lediglich lesend genutzt werden kann. Eine Artikelnummer wird sofort während eines erfolgreichen Einstellvorgangs vergeben. Normalerweise ist der Artikel dann auch sofort sichtbar – eine Ausnahme bilden lediglich vorgeplante Artikel. Aufgrund der von eBay genutzten Caching-Systeme erscheinen Artikel in der Galerie bzw. in der Suchliste nicht sofort nach der Einstellung, sondern mit leichtem zeitlichem Verzug.
schnell + kompakt
23
2 – Der eBay-Geschäftsprozess
2.4 Beobachtung während der Auktion Während einer laufenden Auktion halten sich die Interaktionen in Grenzen. Eventuell lassen sich die Auktionen beobachten und die aktuellen Höchstbieter abrufen. Einen Sonderfall stellen die Artikel in der Kategorie „Immobilien“ dar (Real Estate Ad), in der ein „Gebot“ einer Anfrage zu einem Objekt entspricht. Ebenfalls während der Auktion bietet die API den Zugriff auf die Fragen, die dem Verkäufer gestellt wurden, und einen Weg, eben diese zu beantworten.
2.5 Änderung von Artikeln Während der Laufzeit eines Artikels können die Daten in bestimmten Grenzen geändert werden (ReviseItem). Hierbei sind jedoch spezifische Regeln zu beachten – die allermeisten Daten können bis zwölf Stunden vor Ablauf noch geändert werden, hernach aber nicht mehr.
2.6 Transaktion Das Ende der Laufzeit eines Artikels ergibt sich zunächst direkt aus seinem Typ. Festpreisartikel, Shop-Artikel, aber auch Auktionen mit Sofortkauf-Option enden im Augenblick der Abgabe eines Festpreis-„Gebots“. Normale Auktionen (und auch PowerAuktionen) haben eine vordefinierte feste Laufzeit. Endet nun der Artikel mit einem Gebot, erzeugt das eBay-System eine so genannte Transaktion. Diese verbindet den Artikel und seinen Verkäufer mit dem Käufer. Die Transaktionen werden mit (verkäuferbezogenen) eindeutigen laufenden Nummern versehen. Hierbei ist zu beachten, dass
24
Verkaufsabwicklung und Bestellung
normale Auktionen immer die Transaktionsnummer 0 erhalten. Grundsätzlich ist aber zur Identifikation einer Transaktion die Kombination aus Artikel- und Transaktionsnummer notwendig. Hierdurch können etwa bei Angeboten mit einer Menge größer eins (z.B. in eBay Shops) die unterschiedlichen Transaktionen unterschieden werden. Der Artikel hat hier lediglich eine einzige ItemID. Zum Zeitpunkt der Transaktionserzeugung sendet das eBaySystem die ersten E-Mails in der Form „Sie haben einen Artikel verkauft ...“ bzw. „Sie haben einen Artikel erworben ...“ an Verkäufer und Käufer. Auch mittels der eBay API lassen sich nun die Transaktionsdaten inklusive der vergebenen IDs abrufen. Hier ist allerdings zu beachten, dass zu diesem Zeitpunkt dem Verkäufer bereits die Registrierungsadresse des Käufers mitgeteilt wird, aber noch nicht die Versandadresse. Daneben ist die Übergabe der Registrierungsadresse auf den Fall beschränkt, dass Verkäufer und Käufer auf eBay.de registriert sind. Sprich: Bei einem Verkauf an ein eBay-Mitglied z.B. in Belgien stehen diese Daten nicht zur Verfügung.
2.7 Verkaufsabwicklung und Bestellung Mit der initialen E-Mail wird der Käufer darüber informiert, dass nun die Verkaufsabwicklung auf der eBay-Website zu nutzen ist. Hier kann der Käufer eine Reihe von Werten einstellen und damit den Kauf abschließen. Hierzu gehört etwa die Auswahl einer der angebotenen Zahlungsmethoden (und im Fall von PayPal die direkte Auslösung der Zahlung). Hinzu kommt die Auswahl der gewünschten Versandart und bei Bedarf die Änderung der Versandadresse.
schnell + kompakt
25
2 – Der eBay-Geschäftsprozess
Wurde mehrere Artikel von einem bestimmten Verkäufer gekauft, werden die einzelnen Transaktionen automatisch in einer so genannten Bestellung (Order) zusammengefasst. Alle Einstellungen beziehen sich dann auf diese Gruppe von Artikeln. In Bezug auf die API stehen die Daten jetzt vollständig zur Verfügung. Auch bei ausländischen Käufern wird nun die Versandadresse geliefert. Die Nutzung der Verkaufsabwicklung kann von Verkäufern ausgeschaltet werden. In der Konsequenz stehen dadurch aber nicht alle Daten zur Verfügung. Insbesondere bei einer größeren Anzahl von ausländischen Käufern führt das Ausschalten der Verkaufsabwicklung regelmäßig zu Problemen.
2.8 Externe Verkaufsabwicklung Unter bestimmten Voraussetzungen erlaubt eBay die Nutzung von externen Verkaufsabwicklungssystemen (3rdParty CheckoutRedirect). Neben einer Vielzahl von Auflagen in Bezug auf die Verfügbarkeit und die bereitgestellten Bezahlmethoden (hier ist PayPal Pflicht), ist dieser Weg im Gegensatz zur Nutzung der normalen API kostenpflichtig und nur bei größerem eBay-Engagement lohnenswert.
2.9 Feedback bekommen und hinterlassen Typischerweise wartet der Verkäufer nun auf den Zahlungseingang und versendet dann die Artikel. Den Abschluss bildet dann das gegenseitige Hinterlassen von Bewertungen (Feedback).
26
Gebühren
2.10 Gebühren Seit Ende 2005 fallen für die Nutzung der eBay API keine Kosten mehr an. Dies betrifft allerdings nicht die „normalen“ eBay-Gebühren. Hierzu gehören zunächst die so genannten Einstellkosten, die gleich beim Start eines Artikels anfallen. Dabei werden die Kosten (variabel nach den unterschiedlichen Typen und Laufzeiten) zunächst auf der Basis des Start- bzw. Festpreises zuzüglich der Gebühren für besondere Features berechnet. Nach dem erfolgreichen Verkauf addieren sich dazu die Verkaufsgebühren. In der API werden erstere unter dem Begriff „Listing Fees“, die finalen Gebühren als FVF (Final Value Fee) bezeichnet.
2.11 Dispute-Management Auch wenn es einen Höchstbieter für einen Artikel gibt, bedeutet dies noch lange nicht, dass der Prozess nun vollständig abgeschlossen sein muss. Oft nehmen Käufer ihr Rücktrittsrecht in Anspruch oder ein Käufer weigert sich, einen Artikel zu bezahlen. Auf der anderen Seite kann es durchaus auch Probleme mit dem Artikel auf der Verkäuferseite geben, die den Abschluss der Transaktion verhindert. Seit einiger Zeit hat eBay hier ein semi-automatisches Verfahren eingeführt, das versucht, Streitigkeiten nach Auktionsende zu bearbeiten. Auf Deutsch heißen diese Verfahren „Streitigkeit wegen eines unbezahlten Artikels“ bzw. „Streitigkeit wegen eines nicht erhaltenen Artikels“ – die englischen Originale heißen UPI (Unpaid Item Dispute) bzw. INR (Item Not Received Dispute). Die entsprechenden Dispute können mittels der API gestartet und verwaltet werden. Auf Seiten eines Verkäufers führen diese in der Regel zur Rückerstattung der Einstellgebühren bzw. des FVF. Sollten sich Verkäufer und Käufer nicht einigen können,
schnell + kompakt
27
2 – Der eBay-Geschäftsprozess
führt der Disput eventuell zu einer Verwarnung und in wiederholten Fällen zum Ausschluss vom Handel auf dem eBay-Marktplatz.
2.12 Besondere Artikelformen Neben den „klassischen“ Auktionsformen bzw. dem Verkauf als Festpreisartikel existiert eine Reihe von besonderen Artikelformaten. Nicht alle Formate stehen dabei in allen Kategorien bzw. jederzeit zur Verfügung. Teilweise sind diese Formate aber auch nur Erweiterungen bzw. Ergänzungen zu bestehenden Artikeltypen. Bei allen Formaten besteht allerdings die Möglichkeit, diese mithilfe der eBay API zu verwalten.
Second Chance Das so genannte „Angebot an unterlegene Bieter“ (Second Chance) ermöglicht es bei normalen Auktionen, den unterlegenen Bietern ein erneutes Angebot zu unterbreiten. Sinnvoll ist dies nur, wenn Sie als Verkäufer mehrere gleiche Artikel auf Lager haben und die Gebote der nicht zum Zug gekommenen Bieter nur leicht vom gewünschten Mindestverkaufspreis abweichen. Vielleicht haben Sie einen Gartenstuhl für 20,99 € versteigert; Sie können aber durchaus auch mit einem Preis von mindestens 18,00 € leben. In diesem Fall können Sie dann jenen Bietern, die mindestens 18 € geboten haben, das entsprechende Angebot unterbreiten. Schlagen die Bieter nun zu, fallen natürlich die entsprechenden Gebühren an, aber Sie haben Ihren Verkauf eventuell deutlich gesteigert.
Best Offer In einigen Kategorien ermöglicht das eBay-System es potenziellen Käufern, Angebote zu unterbreiten. Vom Verkäufer können
28
Besondere Artikelformen
diese akzeptiert werden, womit der Artikel dann automatisch verkauft und die Auktion beendet wird.
GetItFast und NowAndNew Die Sonderformen GetItFast und NowAndNew können nur bei Festpreisangeboten genutzt werden. Letztlich entstehen dadurch besondere Markierungen in der Suchliste, die signalisieren, dass Artikel speziellen Kriterien entsprechen. Im Fall von „Sofort und Neu“ müssen dazu der Artikelzustand „Neu“, die Angaben zum Rückgaberecht sowie mindestens eine Versandoption gesetzt werden. GetItFast signalisiert, dass der Artikel sofort lieferbar ist.
WantItNow Der Bereich WantItNow (eBay-Suchanzeigen) ist ein nachfrageorientiertes Format. Käufer können hier ihre Wünsche äußern und eBay-Verkäufer können darauf mit konkreten bereits eingestellten Artikeln reagieren.
eBay Express Mit „eBay Express“ hat eBay eine neue Form des Verkaufs eingeführt. Das wesentliche Merkmal für Verkäufer ist, dass auf „eBay Express“ nur Neuwaren zum Festpreis angeboten werden können. Für Käufer ergibt sich die Möglichkeit, Artikel unterschiedlicher Verkäufer gemeinsam in einem Warenkorb „auschecken“ zu können. Von Seiten der API ergibt sich lediglich die Notwendigkeit, Artikel mit bestimmten definierten Merkmalen ausstatten zu müssen. Sind alle diese Merkmale gegeben und qualifiziert sich der Verkäufer für eBay Express, erscheint ein „normaler“ eBay-Festpreis- oder Shop-Artikel automatisch auch auf eBay Express.
schnell + kompakt
29
2 – Der eBay-Geschäftsprozess
Daneben besteht die Möglichkeit, einen Artikel nur auf eBay Express zu listen (dazu wurde ein neuer ListingType = Express eingeführt). Ansonsten entspricht die Behandlung von eBay Express der anderer Artikelformate.
30
KAPITEL 3 eBay für Techniker 3.1
Alle Sites ein System
31
3.2
Sandbox und Production
33
3.3
Keys und Zertifizierung
34
3.4
Token
35
3.5
URLs
36
3.6
Initialer Start und Testbenutzer
36
3.1 Alle Sites ein System Grundsätzlich wird das gesamte Hosting aller weltweiten eBaySites gemeinsam in Rechenzentren in den USA durchgeführt. Die lokalen eBay-Dependancen haben in Bezug auf das Site-Operating keine echte Funktion, mal abgesehen von Spezialsites, die im Rahmen von Marketingkampagnen genutzt werden. Damit ergibt sich ein weltweiter Datenpool, der sämtliche aktuelle – und für 90 Tage auch historischen – eBay-Artikeldaten beinhaltet. Die einzelnen Länder-Sites stellen diese Daten dann in ihren eigenen lokalisierten Kontextseiten dar. Ähnliches gilt auch für die funktionellen Aspekte der einzelnen Systeme. Auch hier gilt, dass sich die Sites funktionell kaum voneinander unterscheiden und auf einem gemeinsamen Funktionspool basieren. Allerdings ist zu beachten, dass aufgrund unterschiedlicher gesetzlicher Bestimmungen sich in manchen Bereichen massive Unterschiede sowohl auf der Länder-Website als auch in der Nutzung der API ergeben. Auch werden manche Funktionalitäten nicht in allen Ländern genutzt – so ist etwa der Bereich
schnell + kompakt
31
3 – eBay für Techniker
Immobilienangebote bisher nur in den USA und – in reduzierter Form – auch in Deutschland verfügbar. Sämtliche weltweiten Benutzerkonten können sich an einer beliebigen Site anmelden und sowohl für Verkäufe als auch für Einkäufe genutzt werden.
Organisation in Sites Sämtliche eBay-Sites werden intern mithilfe einer Nummer der so genannten Site-ID verwaltet. Hierbei hat die Mutter-Site (USA) die Site-ID 0, Deutschland die 77, Österreich die 16, die Schweiz die 193. Zurzeit existieren hier 24 unterschiedliche Site-IDs. Bei der Nutzung von API-Aufrufen ist die Site-ID stets mit anzugeben – daneben muss teilweise die „Textform“ der Site z.B. „Germany“ zusätzlich definiert werden.
Standard-Sites, Rest-World-Sites Intern nutzt eBay zwei unterschiedliche Systeme. Sämtliche „großen“ Sites, und dazu gehört natürlich auch die deutsche, arbeiten mit der „Standardversion“; kleinere eBay-Länder nutzen so genannte „Rest-World-Sites“. Als kleine Geschwister unterscheiden sich diese funktionell massiv vom Standardsystem, sie ermöglichen aber einen schnellen Start im eBay CI. Im Laufe der Zeit wird hier in der Regel der Umstieg auf das Standardsystem angestrebt. Die Nutzung der API ist auf den Rest-World-Sites nur eingeschränkt möglich.
Versionierung und Compatibility-Level Die Funktionen des eBay-Systems befinden sich in einem stetigen Fluss. Entsprechend ändert sich auch die API in regelmä-
32
Sandbox und Production
ßigen zeitlichen Abständen. Da die Softwareentwicklung der Website und der API nicht direkt miteinander verzahnt sind, entstehen vielleicht Zeiträume, in denen Funktionen der Website nicht oder noch nicht in der API abgebildet sind. Daneben bietet die API teilweise Möglichkeiten, welche die Website nicht oder nicht mehr besitzt. Unschön ist es, wo sich das eBay-API-Team entschlossen hat, Funktionen nicht in die API aufzunehmen, oder wo sich die Abläufe massiv unterscheiden. Die Funktionen der Website sowie der API werden eBay-intern mit Versionsnummern verwaltet. Für den API-Entwickler ist hierzu der so genannte Compatibility-Level wesentlich, der sozusagen die Version der API darstellt. Interessant ist hier, dass die API durchaus parallel in unterschiedlichen Versionen ansprechbar bleibt – eine neue Version ersetzt also nicht sämtliche älteren Versionen, sondern diese bleiben für einen längeren Zeitraum erhalten (+/– zwölf Monate). Sinnvoll ist es allerdings, zeitnah auf neuere Versionen umzusteigen, soweit sich dadurch keine funktionellen Probleme ergeben.
3.2 Sandbox und Production Insbesondere für Einsteiger oder für den Test von neuen Funktionalitäten stellt eBay die so genannte Sandbox zur Verfügung. Funktionell identisch mit den Produktionssystemen stellt die Sandbox einen (auch in Bezug auf Listingkosten und Verkaufsgebühren) kostenfreien Testbereich zur Verfügung. Zu beachten ist allerdings, dass Sandbox und Production unterschiedliche Datenbanksysteme nutzen. Dadurch sind etwa Artikel der Production auf der Sandbox nicht sichtbar, sondern nur solche Artikel, die andere Entwickler oder Sie selbst eingestellt haben. Das Gleiche gilt auch für sämtliche Benutzerkonten.
schnell + kompakt
33
3 – eBay für Techniker
Im Rahmen der Entwicklung ist es daher sinnvoll, auf der Sandbox eine Reihe von Testkonten (Verkäuferkonten, Käuferkonten und/oder Kombinationen) anzulegen. Für die Nutzung der API gilt, dass die API-Server jeweils unterschiedliche URLs nutzen und auch nur mit den richtigen Keys (siehe unten) arbeiten. Die Sandbox ist eben nur ein kleiner Bruder der Production und arbeitet dementsprechend nur mit einem Bruchteil der Hardware des „echten“ Production-Systems. Hieraus ergibt sich natürlich auch, dass die Performance der Sandbox nur Sandkastenniveau erreicht.
3.3 Keys und Zertifizierung Sobald ein API Call genutzt werden soll, fordert das eBay-System die Nutzung von drei Keys. Mit einem davon wird der Entwickler (Developer ID), mit dem nächsten dessen Anwendung (Application ID) und mit dem dritten schließlich die Berechtigung (Certificate) geprüft. Zu beachten ist, dass sich Zertifikat und Anwendungs-ID für die Sandbox und die Production unterscheiden. Im Rahmen einer Entwicklung kann zunächst automatisiert die Anmeldung am Entwicklerprogramm (http://developer.ebay.com) vorgenommen werden. Als Ergebnis werden hier sofort die drei notwendigen Schlüssel für die Sandbox-Umgebung bereitgestellt. Für die Nutzung der Anwendung auf der Produktionsumgebung wird ein neues Key Triple benötigt, das nach einer „Selbstzertifizierung“ generiert werden kann. War die Nutzung der API und die Production-Zertifizierung bis Ende 2005 noch kostenpflichtig, ist nun das Verfahren deutlich vereinfacht und kostenlos. Im Wesentlichen gilt es zunächst, ein HTML-Formular auszufüllen. Hiernach wird automatisiert ein Key Triple generiert, mit dessen Hilfe ein Bestätigungscode aus einer E-Mail abgeru-
34
Token
fen werden kann. Zunächst hat dieses Key Triple die Eigenschaft, dass die Anzahl der Aufrufe auf 10.000 Abrufe je Tag beschränkt ist. Erst nach einer aufwändigeren echten Zertifizierung, in der auch die Anzahl der erwarteten Spitzenlast je Tag spezifiziert werden muss, werden die Keys auf ein Call-Limit von 1,5 Millionen Aufrufe täglich freigeschaltet.
3.4 Token Bestimmen die API-Keys den Entwickler, dient der so genannte Token dazu, einen bestimmten Benutzer zu identifizieren und zu autorisieren. Letztlich hat der Token damit eine ähnliche Funktion wie die eBay-ID und das zugehörige Passwort auf der eBayWebsite. Der Unterschied besteht zum einen darin, dass der Token nur mit den API-Keys arbeitet, für die die Autorisierung ausgestellt wurde, und eben ein interaktiver Login auf der eBayWebsite nicht möglich ist. Ein API-Benutzer kann somit einen Token für einen API-Entwickler ausstellen und diesen damit ermächtigen, in seinem Auftrag Artikel einzustellen oder Transaktionsdaten abzurufen. Der API-Entwickler kann aus dem Token das Passwort des Benutzers nicht extrahieren, und mittlerweile ist die Nutzung des Token auch dann noch möglich, wenn der Benutzer sein eBay-Passwort zwischenzeitlich ändert. Der Token hat allerdings keine unbeschränkte Haltbarkeit. Zum einen kann ein eBay-Benutzer jederzeit im „My eBay“-Bereich die Ermächtigung zurückziehen, zum anderen gilt ein Token zunächst für 18 Monate und muss danach eventuell erneuert werden. Das Verfahren für die Ausstellung des Token nennt eBay „Auth& Auth“ (Authentication and Authorization). Das Auth&Auth-Verfahren erfordert zunächst ein Setup für eine bestimmte API-Anwendung (App-ID). Hierbei hinterlegt der
schnell + kompakt
35
3 – eBay für Techniker
API-Entwickler mithilfe eines so genannten RuName (ReturnURL-Name) bei eBay die Bereitschaft zur Teilnahme am Auth & Auth-Verfahren. Wird nun ein Token benötigt, kann eine besondere eBay-Login-Seite unter Angabe des RuName aufgerufen werden (z.B. durch einen Link in einer Anwendung). Der Benutzer loggt sich danach im eBay-System ein und bestätigt die Weitergabe des Token an den API-Entwickler. Je nach Verfahren führt das „Auth & Auth“-System nun einen HTTP-Redirect auf eine hinterlegte HTTPS-Adresse durch und übergibt dabei den Token, oder der API-Entwickler kann den Token mithilfe einer speziellen Methode (FetchToken) abholen. Wird nur ein einziger Token benötigt, kann dieser – praktisch auch für Tests – über ein spezielles Tool im eBay-Entwicklerbereich erzeugt werden (http://developer.ebay.com/tokentool/).
3.5 URLs Für Nutzung der API werden je nach „Umgebung“ (Sandbox oder Production) unterschiedliche URLs genutzt. Auch in den meisten SDKs muss diese URL zunächst festgelegt werden. Die URLs lauten (jeweils für die Nutzung von SOAP) https://api.sand box.ebay.com/wsapi für die Sandbox und https://api.ebay.com/wsapi für die Produktionsumgebung. Weitere Informationen, wie etwa die Site-ID oder unser Key Triple, werden später mit Parametern bzw. speziellen HTTP-Requestheadern definiert.
3.6 Initialer Start und Testbenutzer Der erste Weg führt zunächst zur Anmeldung im eBay-Entwicklerprogramm (http://developer.ebay.com). Hierzu ist ein „normales“ eBay-Konto (Production-eBay-ID) erforderlich. Als Ergebnis erhalten Sie das Key Triple für das Sandbox-System.
36
Initialer Start und Testbenutzer
Bei der Nutzung der Sandbox (http://www.sandbox.ebay.de) empfiehlt es sich, eine Reihe von Testkonten anzulegen, um später die Geschäftsabläufe simulieren zu können. Hilfreich ist dabei die Nutzung des Sandbox User Registration Tool (http://developer. ebay.com/DevZone/sandboxuser.asp). Hierbei kann der Benutzer bereits (simuliert) einer Heimat-eBay-Site zugeordnet werden; daneben können auch das Anmeldedatum und der FeedbackLevel initialisiert werden. Hier ist die Erzeugung unterschiedlicher Kontentypen sinnvoll, da sich teilweise aus diesen Angaben ja die Berechtigung für spezielle Features der eBay-Plattform ableitet. Im nächsten Schritt sollten die „Standard“-Werte des neuen Benutzers angepasst werden (http://cgi4.sandbox.ebay.de/ws1/ eBayISAPI.dll?ChangeRegistrationShow). Hierbei ist zu beachten, dass zunächst NUR Name und Vorname des Benutzers geändert und gespeichert werden und erst danach in einem weiteren Update das Land und die Adresse angepasst werden; ansonsten haben Ihre Benutzer den „Standardnamen“ Heribert Varli. Alle weiteren Angaben wie die Vorgabe der Versandadresse, das Einstellen des Verkäuferkontos etc. können dann über die „My eBay“-Funktionen der Sandbox angepasst werden. Teilweise ist die Sandbox allerdings nicht ein vollwertiges funktionsfähiges System und Sie werden sicherlich feststellen, dass viele Funktionen gar nicht oder nur hin und wieder funktionsfähig sind. Im Rahmen einer umfangreichen Entwicklung sollten daher sämtliche Funktionen auch auf dem Produktionssystem getestet werden. Suchen Sie einmal in der Knowledgebase auf developer.ebay.com nach dem Begriff „Test Sellers“. Hier finden Sie eine Reihe von „automatisierten“ Benutzern, die regelmäßig Artikel einstellen, kaufen und verkaufen. Nach der Erzeugung der Tokens für die hier angegebenen Benutzerkonten können auch diese sehr gut für den Test einer Entwicklung dienen.
schnell + kompakt
37
KAPITEL 4 SDK oder nicht SDK 4.1
Dokumentation
40
4.2
SOAP
40
4.3
REST
43
4.4
Direkter Zugriff
43
Die eBay API unterliegt wie die eBay-Plattform einer stetigen Veränderung. Viele neue Funktionen ergeben sich durch neue Features auf der Plattform oder dienen der Integration der vielen „aggregierten“ Websites oder Länder-Sites. Hinzu kommen auch Anpassungen der API selbst, die teilweise nur aus dem Hinzufügen oder dem Wegfall von Attributen bestehen, teilweise aber auch massive strukturelle Anpassungen sind. In der Vergangenheit hat eBay zunächst ein sehr „eigenes“ XML-Format genutzt, das Mitte 2006 durch das so genannte Unified-Schema ersetzt wurde. Hiermit nutzen nun sämtliche APIs zumindest ähnliche Strukturen in Bezug auf die Datentypen und Benennungen der Felder. Mittlerweile existieren eine Reihe von SDKs für unterschiedliche Programmiersprachen, die idealerweise davor schützen, dass die API-internen Anpassungen auch direkt innerhalb einer Anwendung nachvollzogen werden müssen. Daneben beinhalten die SDKs – außer Beispielcode – teilweise Hilfsroutinen, welche die direkte Arbeit mit der API deutlich vereinfachen können.
schnell + kompakt
39
4 – SDK oder nicht SDK
Ein kleiner Nachteil der SDKs ist, dass diese nicht sofort nach einer API-Änderung bereitstehen, sondern mit einem kleinen zeitlichen Verzug.
4.1 Dokumentation Die Dokumentation der API ist faktisch nicht für alle SDKs explizit vorhanden, sondern leitet sich jeweils aus der SOAP-Dokumentation ab. Ein guter Einstiegspunkt sind hier die mitgelieferten Beispiele, die einen schnellen Start in die Nutzung des entsprechenden Systems ermöglichen. Allen SDKs ist gemein, dass die Nutzung kostenfrei ist, und zumindest in Teilen werden die Systeme im Sourcecode geliefert oder sind an sich Open Source.
4.2 SOAP Mit der Einführung des Unified-Schemas werden wohl die allermeisten Anwendungen entweder direkt die SOAP Web Services oder eines der darauf aufsetzenden SDKs nutzen. Die direkte Nutzung von SOAP hat den Vorteil, stets Up-to-dateÄnderungen an der API mitvollziehen zu können. Parallel dazu hat das dann vielleicht auch den Nachteil, dass sich Seiteneffekte ergeben könnten, die nur mit einem tiefen Verständnis der gesamten API vorhersehbar sind. Die Autorisierung der Anwendung erfolgt in unterschiedlichen Feldern. Zum einen wird die Anwendungs-ID (App-ID) in der URL neben anderen als Parameter angegeben. Daneben wird ein SOAP Header genutzt, der das gesamte Key Triple und Token bzw. User/Passwort enthält. Daneben muss die Endpoint-URL je nach zu nutzender Methode angepasst werden. Damit kann der Aufruf innerhalb der eBay-
40
SOAP
API-Webfarm einfach geroutet werden. Das Verfahren muss allerdings recht aufwändig bei der direkten Nutzung von SOAP abgebildet werden, da normalerweise – etwa unter .NET – von einer einzigen Endpoint-URL für einen Web Service ausgegangen wird. Die SDKs kapseln diese Einstellungen allerdings automatisch; die oben stehenden Vorbereitungen sind nur bei der direkten Nutzung von SOAP notwendig.
Windows SDK Das Windows SDK nutzt intern die SOAP und bildet diese in Hilfsklassen unter .NET nach. Wesentlich ist dabei die Klasse ApiContext für das Key Triple und den zu nutzenden Token. Für jeden API Call wird eine entsprechende „xxxCall“-Klasse bereitgestellt, sämtliche Datentypen der eBay API werden in entsprechenden Klassen abgebildet. Die mitgelieferten Beispiele, die teilweise bereits höchst komplexe Anwendungen darstellen, sind zwar interessant, aber sehr stark auf den amerikanischen Markt ausgerichtet. Die Anwendungen lassen sich zwar auch auf der deutschen Sandbox oder Produktion zum Leben erwecken, allerdings nur mit teilweise massivem Eingriff in den Sourcecode. Das SDK wird fast vollständig im Sourcecode geliefert. Die vorbereiteten Assemblies wurden mit VS.2003 und somit .NET 1.1 erstellt. Ein Upgrade auf .NET 2.0 ist aber problemlos möglich. Die Nutzung des eBay Picture Service ist durch die Assembly eBayPictureService.dll möglich, wobei diese weder direkt dokumentiert noch im Sourcecode geliefert wird. Mithilfe der Interop-Funktionalität von .NET können die Assemblies auch mit COM-fähigen Sprachen, wie etwa VB 6.0 oder VBA (Office), genutzt werden. Eine Batch-Datei zur Registrierung (RegSDK.bat) liegt vorbereitet im Hauptordner des SDK.
schnell + kompakt
41
4 – SDK oder nicht SDK
Neben dem reinen SDK wird eine weitere Bibliothek – die IntegrationLib – mitgeliefert. Diese stellt einen Connector zwischen einer Datenbank und der eBay API dar. Leider wurde hier nur die Bindung an MS-Access bzw. OLE-Db realisiert.
Java SDK Auch das Java SDK basiert auf der SOAP-Schnittstelle. Die hier entstandene Hülle ist allerdings recht dünn und die Menge an Hilfsklassen und Funktionalitäten hält sich stark in Grenzen. Interessant ist die Fähigkeit, die API multithreaded zu nutzen.
eBay PHP Accellerator Toolkit Nicht ganz uneigennützig wird hier auch das eBay PHP Accelerator Toolkit (kurz: Ebat) vorgestellt, da der Autor maßgeblich an der Entwicklung beteiligt ist. Wie auch bei den anderen SDKs ist die Basis des Ebat der SOAP Web Service. Das Toolkit ähnelt in seinem Grundaufbau dem aktuellen Windows .NET SDK. Es existieren PHP-Klassen für alle Datentypen der API. Die Verwaltung der Basisdaten erfolgt mithilfe der Klasse EbatNs_Session, sämtliche Methoden der API stehen in der Klasse EbatNs_ServiceProxy zur Verfügung. Das System arbeitet mit einer proprietären, (auf das eBay-System) optimierten SOAP-Schnittstelle und kann daher ohne weitere Zusatzsoftware unter PHP 4 und PHP 5 genutzt werden. Auch hier wird eine Vielzahl von Beispielen geliefert. Darunter finden sich spezielle Anpassungen für den deutschen Marktplatz, aber auch fortgeschrittene Aufbauten, z.B. für die Nutzung von Attributen, die Bindung an eine (MySQL-)Datenbank oder die Entgegennahme von Notifications. Der Download findet sich unter http://www.intradesys.de.
42
REST
4.3 REST Die REST-Schnittstelle ist ein System, das ursprünglich dediziert für eBay Affiliates mit einem vereinfachten Zugriffsverfahren gestartet ist. Mittlerweile gilt auch hier für Rückgabewerte das Unified-Schema. Die Eingabeparameter werden aber – wie bei REST üblich – mithilfe von einfachen CGI-Parametern formuliert. Die REST-API stellt allerdings nur einen Subset aller API-Funktionen bereit – im Wesentlichen nur Suchfunktionen, wie sie in einer Affiliate-Anwendung benötigt werden. Da die REST-Server wohl eine eigene dedizierte Infrastruktur darstellen, ist die Nutzung etwa des GetItem-Call hier teilweise deutlich performanter als auf den „normalen“ API-Servern.
4.4 Direkter Zugriff Neben den SDKs oder der Nutzung des SOAP Web Service stellt eBay weiterhin eine so genannte XML-Schnittstelle bereit. Hierbei werden die Anforderungen mittels eines HTTP-Post-Befehls übergeben. Letztlich ist dies ein ähnlicher Aufbau wie bei SOAP, allerdings ohne den SOAP-Envelope. Das Verfahren ist aber nur wenig unaufwändiger als SOAP und bietet sich nur bei Anwendungen an, die direkt auf der Nutzung von XML aufsetzen sollen.
schnell + kompakt
43
KAPITEL 5 eBay API – Technical Basics 5.1
Auth&Auth
45
5.2
Poll and Push
48
5.3
Compatibility Levels
49
5.4
Detail Level und Granularity Level
50
5.5
Paginierung
51
5.6
Behandlung von Datums- und Zeitwerten
51
5.7
Lookup-Werte
52
5.8
Aufbau eines Call
54
5.1 Auth&Auth Soll eine Anwendung mit mehr als einem Benutzerkonto arbeiten, sollte das Auth&Auth-Verfahren für die Ausstellung eines Token genutzt werden. Für eine einfache Anwendung ist es sicherlich unaufwändiger, den Token eines Benutzers über das Token-Tool auf der Entwickler-Website zu erstellen.
ReturnURL Für die Teilnahme am Auth&Auth-Verfahren muss zunächst je Anwendung mindestens eine Return-URL definiert werden. Die entsprechende Methode (SetReturnURL) benötigt einen so genannten RuName, der weltweit eindeutig sein muss. Falls die persönliche Kreativität hier nicht ausreicht, kann eventuell die Methode GetRuName genutzt werden. Der RuName wird nun zusammen mit einer Redirect-URL im eBay-System hinterlegt – wichtig ist, dass hier nur HTTPS-
schnell + kompakt
45
5 – eBay API – Technical Basics
Adressen genutzt werden dürfen. Für einen Test oder eine lediglich interne Nutzung kann hierbei auf ein offizielles SSL-Zertifikat verzichtet werden. In einer Browser-Anwendung wird hier zwar eine Sicherheitswarnung gezeigt, eBay hingegen prüft das Zertifikat nicht und akzeptiert alles, was mit https:// beginnt. Der Parameter „TokenReturnMethod“ definiert mit „Redirect“ oder „FetchToken“ die Übergabemethode des Token. Eine Besonderheit von SetReturnURL ist, dass diese Methode als einzige keinen Token, sondern eine Kombination aus eBay-ID und Passwort benötigt – wobei diese eBay-ID völlig beliebig sein kann, es geht hier lediglich um die Lösung des Henne/Ei-Problems, sprich: Wie komme ich an einen Token ohne Token? Nach dem Setup kann ein Benutzer, der einen Token ausstellen soll, auf die Auth&Auth-Seite weitergeleitet werden – für die Sandbox bzw. lokale Ländersites muss die Basis-URL entsprechend angepasst werden. https://signin.ebay.com/ws/ eBayISAPI.dll?SignIn&runame=MeinRuName[&sid=xxx]
Anstelle von MeinRuName nutzen Sie den zuvor definierten und mit SetReturnURL übergegebenen ReturnURL-Namen. Bei einer Nutzung von FetchToken braucht es noch ein SecretID im Parameter sid (siehe unten). Nach dem Durchlaufen des Login-Prozesses und einer Bestätigungsseite generiert das Auth&Auth-System den Token für die Kombination Anwendung und Benutzer. Je nach „TokenReturnMethod“ unterscheidet sich nun die weitere Verarbeitung.
46
Auth&Auth
Auth&Auth Redirect Im Falle eines Redirect leitet das Auth&Auth-System den Benutzer nach der Token-Generierung auf die mit SetReturnURL angebene „AcceptURL“ weiter. Dabei wird ein einfacher HTTP-403 Redirect genutzt. Der Token wird als Request-Parameter in ebaytkn, der Benutzername in username übergegeben. In einer Webanwendung kann damit der Token einfach entgegengenommen und verarbeitet werden.
Auth & Auth Fetchtoken Ist die API keine Webanwendung oder steht kein HTTPS-Server zur Verfügung, bietet sich das FetchToken-Verfahren an. Hierbei wird nach der Anmeldung kein Redirect durchgeführt, sondern der generierte Token lediglich für 48 Stunden bei eBay hinterlegt. Bei der initialen Login-Prozedur ist eine so genannte SID („geheime“ ID) mit zu übergeben, in der Regel ein Wert, der mit einem UUID-Algorithmus erstellt wurde. Nach dem erfolgten Login kann der Token mithilfe der Methode FetchToken unter Angabe des Benutzernamens und der SID proaktiv abgeholt werden. Achtung: FetchToken nutzt keine „echte“ Autorisierung; es wird kein Token und kein eBay-Passwort, aber der eBay-Benutzername (in Korrelation mit der SID) im Autorisierungsbereich angegeben.
Redirect ohne Token Neben den beiden oben genannten Verfahren existiert eine Kombination. Hierbei findet zwar ein Redirect statt, es wird allerdings nur die SecretID und der Benutzername, aber nicht der Token übergeben. Hiernach kann dann der FetchToken-Aufruf erfolgen. Vorteil dieser Methode ist, dass der Token nicht in der Browser-Adresszeile sichtbar wird und damit nicht zu – unbe-
schnell + kompakt
47
5 – eBay API – Technical Basics
gründeten – Sicherheitsbedenken bei unbedarften Benutzern führt.
5.2 Poll and Push Grundsätzlich bietet eBay zwei unterschiedliche Verfahren der API-Nutzung. Zum einen können die Methoden im Polling-Verfahren genutzt werden. Für die proaktiven Aktionen wie „Einstellen von Artikeln“ oder „Eröffnen eines Disputs“ kann nur dieses Verfahren genutzt werden. Der Abruf von Transaktionen erfolgt oft auch im Polling-Verfahren. Die Anwendung prüft hier in regelmäßigen Abständen (etwa alle 30 Minuten) und ruft die entsprechenden Daten ab. Hier können alternativ die eBay Platform Notifications (EPN) genutzt werden. Dabei liefert der API-Server die Daten im PushVerfahren, sobald neue Daten vorliegen. Die entsprechenden Datenstrukturen sind fast vollständig gleich. Letztlich basiert das Verfahren darauf, dass der Notification-Service automatisch die entsprechende API-Methode aufruft und die Ergebnisdaten einfach an eine hinterlegte URL weiterleitet. Nach dem heutigen Stand der EPN können beliebig viele unterschiedliche Anwendungen die Daten empfangen und verarbeiten. In der Anfangszeit war dies nur der Anwendung möglich, die einen Artikel mittels der API eingestellt hatte.
Notifications Die eBay Notifications unterteilen sich in verschiedene Gruppen, die entsprechend mit den unterschiedlichen Daten und Ereignissen, die während des eBay-Geschäftsprozesses auftreten können, verbunden sind.
48
Compatibility Levels
Im Wesentlichen sind dies „verkaufsbezogene“, käuferbezogene Nachrichten- und Dispute-Daten. Eine Anwendung kann die entsprechenden Nachrichten anwenderspezifisch abonnieren und entsprechend weiterverarbeiten. Das Setup ist hier zunächst anwendungsbezogen durchzuführen. Dabei hinterlegt die Anwendung eine URL bei eBay und definiert damit die „Rückruf“-Adresse. Interessant ist, dass hier auch URLs in der Form „mailto://“ möglich sind und damit eine Weiterleitung in eine Mailbox erfolgen kann. Für jeden Benutzer muss danach ein weiteres Setup erfolgen, wobei hier die gewünschten Benachrichtigungen und der Token des entsprechenden Benutzers anzugeben sind. Das einmalige Setup der Anwendung und das Setup der Benutzerkonten erfolgt jeweils mithilfe der API-Methode SetNotificationPreferences. Wesentlich für die Nutzung von Notifications ist, dass Ihr Empfangsserver eine hohe Verfügbarkeit aufweist. Kann der Server einmal nicht erreicht werden, versucht das EPN-System zwar, die Auslieferung zu wiederholen, es schaltet sich allerdings nach einer gewissen Zeit aus und das gesamte Setup muss wiederholt bzw. der eBay Developer Support muss bemüht werden.
5.3 Compatibility Levels Um den fortlaufenden Änderungen gerecht zu werden, welche die eBay-Plattform und die API ständig durchlaufen, muss bei jedem API-Aufruf eine Versionskennung – der Compatibility Level – mitgegeben werden. Die unterschiedlichen Versionen der API existieren ca. zwölf Monate und können mit dem Compatibility Level entsprechend aktiviert werden. Somit ist es möglich, dass die API-Anwendungen unterschiedlicher Entwickler mit den entsprechenden Versionen der API arbeiten können.
schnell + kompakt
49
5 – eBay API – Technical Basics
Neue Versionen erscheinen etwa alle zwei bis drei Wochen, mit teilweise massiven Anpassungen der vorhergehenden Version, neuen Calls oder auch nur mit kleineren Anpassungen – etwa in der Dokumentation. Es ist dann die Aufgabe des Entwicklers, zu entscheiden, ob das Upgrade sofort oder erst zu einem späteren Zeitpunkt stattfinden soll. Der Compatibility Level ist nicht direkt linear. Die Versionskennung steigt also nicht immer in einzelnen Nummern an, sondern es gibt vielfach Sprünge von drei oder fünf Zählern. Also muss man sich keine Sorgen machen, dass man vielleicht eine Version verpasst hat. Der genutzte Compatibility Level kann jeweils für jeden Call getrennt gesetzt werden, wobei dies selten geschieht und normalerweise die Nutzung des Versionskennzeichens in einem SDK gekapselt ist. In Ausnahmesituationen – etwa bei einem Problem bei eBay selbst – kann eventuell das temporäre Downgrade ein Ausweichweg sein.
5.4 Detail Level und Granularity Level Eine Reihe von Funktionen liefert teilweise sehr viele Daten zurück, die in einer bestimmten Anwendung vielleicht nur partiell benötigt werden. Mithilfe des so genannten Detail Level kann die zurückgegebene Datenmenge eingeschränkt werden. Der Detail Level ist ein Textwert (normalerweise ist der Standard hier ReturnAll), der Call-bezogen definiert sein kann. Zur Einschränkung sollte dann der entsprechende Wert genutzt werden, der am besten zu den eigenen Anforderungen passt. Einige Calls definieren daneben das Feld „Granularity Level“. Die Funktion ist sehr ähnlich dem Detail Level mit den möglichen Werten „coarse“ (wenig Daten), „medium“ und „fine“ (für viele Daten). Ob ein Call nun Detail oder Granularity Level oder vielleicht
50
Paginierung
auch beides unterstützt, ist leider nicht eindeutig definiert, sondern muss jeweils in der Dokumentation nachgelesen werden.
5.5 Paginierung Viele der eBay-API-Methoden liefern eine Liste von unter Umständen sehr vielen Einträgen zurück. Grundsätzlich ist die Menge an gelieferten Daten je Call aber beschränkt. Eine Suchfunktion liefert so etwa nicht alle Artikel einer bestimmten Kategorie, sondern zunächst nur 100 oder 200 Listeneinträge. Mithilfe des standardisierten Paginierungsverfahrens wird die Ergebnismenge in Seiten unterteilt. Mit weiteren Aufrufen kann dann jeweils unter Angabe von Seitengröße und gewünschter Seite die Gesamtliste heruntergeladen werden. Intern arbeiten die meisten Calls, die größere Datenmengen liefern, mit einer Paginierung. Dabei werden dann zunächst Default-Werte genutzt. Typisch ist eine Seitengröße von 200 und der Default 1 für die Seitennummer. Leider ist dies aber nicht bei allen Calls gleich, der häufig genutzte Call GetSellerTransactions etwa nutzt hier den Default 0. Entsprechend beginnt die Seitenzählung auch bei 0 und nicht bei 1. Ob die Nutzung der Paginierung sinnvoll oder möglich ist, kann man in der API-Dokumentation für jeden Call erfahren.
5.6 Behandlung von Datums- und Zeitwerten Grundsätzlich werden alle Datums- und Zeitangaben in der eBay API auf der Basis von UTC-Zeitstempeln ausgedrückt. Somit sind alle empfangenen Angaben mithilfe einer geeigneten Methode von GMT in die entsprechende eigene Zeitzone umzurechnen. Das Gleiche gilt umgekehrt auch für sämtliche Zeit-
schnell + kompakt
51
5 – eBay API – Technical Basics
werte, die als Parameter in der API genutzt werden. Neben der Planungszeit bei einem vorgeplanten Artikel sind dies häufig Zeiträume, die zur Einschränkung der Ergebnisdaten genutzt werden können.
5.7 Lookup-Werte Eine Vielzahl von Werten, die in der API genutzt werden, besteht aus Vorgabewerten in Text- oder numerischer Form. Mit der Einführung des Unified-Schemas wurden viele der bisherigen numerischen Vorgabewerte durch eine Textform ersetzt (Enums). Leider bieten nicht alle Programmiersprachen ein solches Konstrukt und auf der anderen Seite wären numerische Werte bei der Speicherung in einer Datenbank wesentlich praktischer, aber die textuelle Form ist in einem Programmtext sicherlich deutlich lesbarer. Die typische Kategorien-ID, die zur Einsortierung von Artikeln genutzt wird, bleibt allerdings weiterhin ein numerischer Wert. Bei allen nachfolgenden Elementen ist zu beachten, dass sich auch die Lookup-Werte in einem ständigen Wandel befinden. So werden etwa Kategorien in weitere Unterkategorien unterteilt, oder man entscheidet sich dafür, auf eine Unterkategorisierung in Zukunft zu verzichten und sich stattdessen rein auf Attribute zu verlassen. Wichtig ist nun, regelmäßig die Daten abzurufen und gegen die eigene aktuelle Version zu testen sowie bei Bedarf die neuen Werte zu übernehmen. Ungeschickt ist die Nutzung von hart kodierten Werten, da sich dadurch eine ständige Pflege dieser Werte ergibt und eine Anwendung hierdurch kaum stabilisiert werden kann.
52
Lookup-Werte
Kategorie und Features Der Kategorienbaum lässt sich jeweils unter Angabe der Site-ID abrufen (GetCategories). Hierbei ist es sinnvoll, zunächst mit der Angabe eines entsprechenden Detail Level zunächst nur die Versionskennung und erst danach eventuell die neuen Daten abzurufen. Grundsätzlich müssen hier immer alle Daten abgerufen werden, auch wenn sich faktisch nur einige wenige Einträge geändert haben. Der Kategorienbaum ist schon im reinen XML-Format über 20 MB groß und damit macht eine Optimierung hier Sinn. Zunächst sollte sichergestellt sein, dass das zugrunde liegende HTTP-Modul die Nutzung eines komprimierenden Stream (GZIP oder compressed) unterstützt. Daneben kann es sinnvoll sein, den vollen Baum in Teilstücken (z.B. jeweils unter Angabe der IDs der Hauptkategorien) abzurufen. Bei einer Änderung (z.B. dem Wegfall von Kategorien) wird ein entsprechendes Mapping bereitgestellt. Hiermit werden dann Artikel, die in nicht mehr vorhandene Kategorien eingestellt werden, automatisch in andere übertragen. Das entsprechende Mapping kann mit GetCategoryMappings abgerufen werden. Zu jeder Kategorie lässt sich nun ein Feature Set abrufen (GetCategoryFeatures), dazu gehören etwa spezielle Listing-Formate oder auch die erlaubten Zeiträume für die Listings in dieser Kategorie.
CharacteristicsSets Die CsSets einer eBay-Website können mit GetAttributesCS abgerufen werden. Die Zuordnung zu einzelnen Kategorien kann mit GetCategory2CS festgestellt werden. Wichtig ist hier, dass GetCategory2CS zum einen die Kategorien angibt, für die ein bestimmtes CsSet gilt, zum anderen aber auch Ausschlüsse der SideWide CsSets.
schnell + kompakt
53
5 – eBay API – Technical Basics
Bei Bedarf kann eventuell mit GetAttributesXSL ein Stylesheet für die XSL-Transformation des CharacteristicsSet abgerufen werden.
eBay-Details Die Mehrzahl der textuellen Vorgabewerte werden als Teil der WSDL für den SOAP Web Service geliefert und in der Regel innerhalb etwa eines SDK als Enum-Werte oder Konstanten bereitgestellt. Darüber hinaus können weitere Daten mit der Methode GeteBayDetails abgerufen werden. Hierzu gehören etwa bestimmte URLs für die Verlinkung zurück in die eBay-Website, Informationen über Versandoptionen, Zahlungsmethoden, aber auch die „Regionen“ (größere Städte und Landkreise), die bei der Einstellung genutzt werden können.
5.8 Aufbau eines Call Obwohl wahrscheinlich die wenigsten Anwendungen direkt auf den rohen SOAP Web Services aufsetzen, ist es doch interessant, die technischen Details zumindest grob zu kennen. Nachfolgend wird die Basisstruktur anhand des – sehr einfachen – Call GeteBayOfficalTime erläutert. Zusätzlich zu den hier beschriebenen XML-Daten sind im HTTP Header mindestens die Felder „Content-Type“ und „SOAPAction“ zu setzen. Bitte beachten Sie auch, dass die hier gezeigten XML-Daten (aus Platzgründen) um die Namespace-Deklarationen gekürzt wurden und somit nur schematisch den Aufbau der SOAP-Nachrichten zeigen.
54
Aufbau eines Call
SOAP XML Request Listing 5.1: SOAP XML Request
<soapenv:Envelope> <soapenv:Header> … <soapenv:Body> 405
Der Grundaufbau der SOAP-Request-Nachricht besteht aus dem Soap-Envelope mit der eBay-spezifischen Soap-Header-Erweiterung für die Autorisierungsprüfung. Der SOAP-Body enthält das entsprechende Request-Objekt mit der Versionskennung und eventuell weiteren Call-spezifischen Eingabedaten.
schnell + kompakt
55
5 – eBay API – Technical Basics
Token Listing 5.2: Basis SOAP Header mit einem Token
<soap:Header> <ebl:RequesterCredentials soapenv:mustUnderstand="0"> <eBayAuthToken> ... TOKEN ... YourAppId YourDevId YourCertId
Bei der Nutzung der Token-Authentifizierung enthält der SOAP Header zum einen den Token, daneben ein Element mit dem Key Triple. Alternative mit Username und Passwort: Listing 5.3: Alternative Authentifizierung mit Benutzername und Passwort
<soap:Header> <ebl:RequesterCredentials soapenv:mustUnderstand="0"> <AppId>YourAppId YourDevId YourCertId <Username>UserID <Password>UserPassword
56
Aufbau eines Call
Einige wenige Calls (SetReturnURL und FetchToken) nutzen eine abweichende Authentifizierung mit Username und eventuell auch dem eBay-Passwort. Beide sind Unterelemente von Credentials.
HTTPs Call Listing 5.4: Aufbau der Request-URL
string string string string string
endpoint = "https://api.sandbox.ebay.com/wsapi"; callName = "GeteBayOfficialTime"; siteId = "77"; // Deutsche eBay Site appId = "yourAppId"; version = "467";
// Build the request URL string requestURL = endpoint + "?callname=" + callName + "&siteid=" + siteId + "&appid=" + appId + "&version=" + version + "&routing=default";
Die Request-URL (der SOAP Endpoint) muss Call-spezifisch konstruiert werden – hier ein Aufbau in C#, der das Grundkonstrukt zeigt. Die Angabe von SiteId, Version und AnwendungsID gibt dem eBay-Web-Service die Möglichkeit, den Aufruf schon auf der URL-Ebene an den entsprechenden Server weiterzurouten.
schnell + kompakt
57
5 – eBay API – Technical Basics
Response Listing 5.5: XML SOAP Response
<soapenv:Envelope> <soapenv:Body> <Timestamp>2005-05-02T00:07:22.895Z Success ... 405 <Build>20050422132524
Die Antwortdaten des eBay-Web-Service enthalten eine Reihe von Standardelementen und die Call-spezifischen Daten. Im Fall von GeteBayOfficalTime erhalten wir nur Standardelemente, das Element Timestamp enthält die aktuelle „eBay-Zeit“, die auch bei allen anderen Calls Teil des Ergebnis-XML ist.
58
KAPITEL 6 eBay API – can do 6.1
Einstellen von Artikeln
59
6.2
Verkaufsabwicklung
62
6.3
Suchen von Artikeln
64
6.4
Dispute
66
Die nachfolgenden Abschnitte zeigen exemplarisch typische Aufgaben, die mit der eBay API gelöst werden können. Dabei liegt das Augenmerk eher auf dem prinzipiellen Vorgehen und den Besonderheiten der zu nutzenden Methoden als auf konkreten Kodierungsbeispielen.
6.1 Einstellen von Artikeln Die Basis für das Einstellen ist die Methode AddItem. Bevor allerdings auch nur ein einfacher Aufruf abgesetzt werden kann, wird neben dem Key Triple und einem Token mindestens auch eine Kategorien-ID benötigt. Die weiteren Angaben wie Titel und Beschreibung oder Startpreis sind sicherlich vorhanden. Des Weiteren sind mindestens eine Zahlungsmethode, der Artikelstandort und die Art des Artikels (ListingType) zu setzen. Dazu kommen eventuell das entsprechende CharactericsticsSet oder das SideWide CsSet für das Rückgaberecht bzw. den Artikelzustand.
schnell + kompakt
59
6 – eBay API – can do
Vor einem echten Einstellen können sämtliche Parameter mit der Methode VerifyAddItem getestet werden. Diese Methode durchläuft die gesamte Einstelllogik, bricht allerdings kurz vor der tatsächlichen Einstellung ab und dient damit lediglich zur Überprüfung, ob ein AddItem-Aufruf erfolgreich gewesen wäre. Beide Methoden haben sehr ähnliche Eingabeparameter, und auch in einer Produktionsumgebung ist es unter Umständen sinnvoll, jeweils zunächst mit einem vorgeschalteten „Verify“ zu prüfen. Das Ergebnis eines AddItem-Call ist im Wesentlichen die ItemID des neuen Artikels. Diese ID wird auch dann zurückgeliefert, wenn der Artikel mithilfe des eBay-Scheduling erst in der Zukunft gestartet werden soll. Neben der ID liefert AddItem eine Liste mit Gebühren für die Einstellung, also die vom Startpreis abhängige Einstellgebühr und sämtliche Extragebühren für Features wie Fett, Galerie etc.
Crosspromoting Mithilfe der ID können bei Bedarf Crosspromoting-Einstellungen zu anderen Auktionen oder Artikeln im eigenen eBay Shop definiert werden. Dies funktioniert auch für Artikel, die „vorgeplant“ sind. Hierzu ist die Methode SetPromotionRules zu nutzen.
Ending Items Mithilfe der API können Artikel jederzeit durch Einsatz der Methode EndItem beendet werden. Hierbei ist allerdings im Fall einer normalen Auktion zu beachten, dass eine Streichung von Geboten mithilfe der API nicht möglich ist. Sprich: Wird eine laufende Auktion beendet, auf die bereits ein eBay-Mitglied geboten hat, entspricht dies dem Verkauf des Artikels an den Höchstbieter. Für die Streichung von Geboten hingegen muss die entsprechende Funktion auf der eBay-Website genutzt werden.
60
Einstellen von Artikeln
Revise Laufende Auktionen können mittels der Methode ReviseItem vollständig überarbeitet werden. Welche Eigenschaften des Artikels verändert werden können und ob es eventuell zeitliche Limitationen gibt (z.B. maximal möglich bis zwölf Stunden vor Ablauf), ist listingtyp- und kategorienabhängig. Unabhängig davon können mit der Methode AddToItemDescription Anmerkungen an den Beschreibungstext angefügt werden, allerdings auch nur bis maximal zwölf Stunden vor Ablauf einer Auktion.
Relist Ist eine Auktion oder ein Festpreisartikel abgelaufen, ohne dass sich ein Käufer gefunden hat, kann der Artikel einmalig erneut mit einer Gebührenreduzierung eingestellt werden. Hierzu dient die Methode RelistItem. Im einfachsten Fall reicht hier die Angabe der Artikelnummer des abgelaufenen Artikels aus. Bei Bedarf können hiermit aber auch Änderungen bis hin zu einer vollständigen Überarbeitung vorgenommen werden.
SecondChance Das so genannte Angebot an unterlegene Bieter kann mit der Methode AddSecondChanceItem erzeugt werden. Hierbei findet faktisch ein Relist und eine Änderung des Listingtyps statt. Der Artikel verbleibt dann für einen begrenzten Zeitraum – nur sichtbar für den unterlegenen Bieter – auf der Plattform. Bei einem Verkauf dieses Artikels muss dann entsprechend die neue Artikelnummer beachtet werden, die nicht mit dem Ursprungsartikel übereinstimmt. Auch hier existiert mit VerifyAddSecondChanceItem eine Version zur vorschaltbaren Prüfung.
schnell + kompakt
61
6 – eBay API – can do
Messaging Während einer laufenden Auktion können eBay-Mitglieder mithilfe einer Funktion Fragen und Nachrichten an den Verkäufer senden. Im Fall des besonderen Immobilienformats ist dies sogar der einzige Zweck des Artikels. Zurzeit befindet sich das Messaging-System in einer Umstellungsphase. Neue Anwendungen sollten direkt auf die neuen Methoden umsteigen und die ältere (AddMemberMessage) zunächst nicht mehr nutzen. Ein initialer Versand einer Nachricht ist zunächst nur über die Website möglich. Ein Verkäufer kann dann zunächst mit GetMemberMessages bzw. MyMessages aktuell vorliegende Fragen abrufen. Alternativ können hier Notifications genutzt werden. Mithilfe von AddMemberMessageRTQ kann ein Verkäufer auf eine Nachricht antworten. Alternativ steht die Methode AddMemberMessageAAQToPartner zur Verfügung, allerdings erst nachdem eine „Transaktion“ existiert, an der der Käufer bzw. der Verkäufer beteiligt ist, sprich: nachdem ein Verkauf stattgefunden hat. Für die Zukunft plant eBay, das Verfahren auszudehnen und mithilfe von „Einmal-E-Mail-Adressen“ auch eine anonyme Kommunikation über das eBay-Nachrichtensystem zu ermöglichen. Dabei ist dann auch die API obsolet, da hier ein normales E-MailProgramm genutzt werden kann.
6.2 Verkaufsabwicklung Die Nutzung der API im Rahmen der Verkaufsabwicklung ist sicherlich einer der Einsatzzwecke, der nach der Einstellung von Artikeln am häufigsten genutzt wird. Wesentlich ist hier die Nutzung einer Kombination aus ArtikelNr (ItemID) und Trans-
62
Verkaufsabwicklung
aktionsNr. Beide zusammen beschreiben dabei eindeutig einen Verkaufsvorgang.
Abruf von Transaktionen Der Abruf von Transaktionen kann entweder gesammelt für einen Verkäufer (GetSellerTransactions) oder jeweils einzeln für einen bestimmten Artikel (GetItemTransactions) erfolgen. Zur Reduktion des Call-Volumens kann zunächst über GetMyeBaySelling oder GetSellerEvents geprüft werden, ob neue Verkaufsaktivitäten vorliegen. Bei allen Calls kann der Zeitraum für die Ergebnisliste mit zwei Feldern eingeschränkt werden. Daneben ist eventuell auch die Nutzung der Paginierung notwendig, falls das Synchronisationsintervall relativ groß ist und die Anzahl der Transaktionen das Maximallimit von 200 übersteigt. Insbesondere wenn die eBay-eigene Verkaufsabwicklung genutzt wird, sollte beachtet werden, dass die Transaktion nach dem Ablauf einer Auktion oder bei einem Sofortkauf im Augenblick des Kaufs erzeugt wird. Diese kann dann auch direkt abgerufen werden, enthält aber vielleicht noch nicht die gewünschten Daten, da der Käufer eventuell die Verkaufsabwicklung noch nicht genutzt hat. Auch hier kann mithilfe der Notifications das Datenvolumen drastisch gesenkt werden. Die Transaktionen erscheinen mehr oder minder automatisch, somit entfällt auch die gesamte Polling-Logik inklusive der Beachtung von Überschneidungen. Daneben werden die Notifications erst dann ausgeliefert, nachdem die gewünschten Daten wirklich vorliegen – also im Beispiel von oben, wenn der Käufer die Verkaufsabwicklung vollständig abgeschlossen hat.
schnell + kompakt
63
6 – eBay API – can do
Order, Combined Payment Kauft ein eBay-Mitglied mehr als einen Artikel eines bestimmten Verkäufers, kann der Käufer nach Belieben alle Artikel zusammengenommen bezahlen bzw. verwalten. Hierbei erstellt das eBay-System zunächst eine Order (Bestellung) und kombiniert hierin sämtliche Artikel – genauer eigentlich die Transaktionen der Artikel. Mittels der API können zunächst die Bestellungen und die hiermit eventuell verbundenen gemeinsamen Daten abgerufen werden (GetOrder). Daneben ist es auch möglich, die Gruppierungsfunktion zu einer Bestellung vorzunehmen (AddOrder). Diese „Verkäufer-generierte Bestellung“ ist aber sicherlich ein selten genutztes Feature der API.
Feedback Nach dem erfolgten Abschluss einer Transaktion werden gegenseitige Bewertungen abgegeben. Mit der API kann das Einlaufen von Bewertungen (GetFeedback) ermittelt werden oder man verlässt sich auf die eBay Notifications. Daneben kann mit der Methode LeaveFeedback oder mit der Methode CompleteSale die Bewertung für einen Käufer abgegeben werden. Eine Prüfung auf Artikel, für die eine Bewertungsabgabe möglich ist, kann mit GetItemsAwaitingFeedback erfolgen.
6.3 Suchen von Artikeln Die Suche in der eBay-Artikeldatenbank ist eine typische Anwendung, die von eBay Affiliates genutzt wird. Das Suchsystem wird mit den allermeisten Funktionen, die auch direkt auf der eBay-Website zur Verfügung stehen, über die Methode GetSearchResults implementiert. Stellt die Website aber bestimmte
64
Suchen von Artikeln
Artikel (Featured oder Gallerie Featured) immer oben zuerst dar, so liefert die API-Suche die Ergebnisse immer in der gewählten Sortierung. Die Suchfunktion gibt auch bei einfachen Anfragen oft sehr viele Artikel zurück; entsprechend sollte hier die Paginierungsfunktion genutzt werden. Auch die GetSearchResults-Methode beherrscht, ähnlich wie die Website, die Expansion auf Artikel auf anderen eBay-Sites, falls nur wenige Ergebnisse geliefert werden. Die Aufzählung aller Parameter würde an dieser Stelle den Rahmen sprengen, interessant ist aber noch – als letzte Spezialität – die Unterstützung von Wildcards (*-Joker) und die Nutzung von logischen Verknüpfungen. Eine Liste von Artikeln in einer bestimmten Kategorie kann zwar auch mit GetSearchResults ermittelt werden, aber eigentlich sollte hier die spezielle Methode GetCategoryListings genutzt werden. Beiden Methoden haftet allerdings der Makel an, dass nicht alle Daten der Artikel in der Ergebnisliste geliefert werden. Eventuell kann dann die Methode GetItem genutzt werden, die die komplette Datenmenge eines Artikels liefert. Für die Suche auf eBay Express steht mit GetSearchResultsExpress eine spezielle Methode zur Verfügung. Die Organisation der Artikel auf eBay Express entspricht allerdings nicht der typischen Kategorienstruktur; vielmehr wird hier eine Unterscheidung in Abteilungen (Departments), Gänge (Aisles) und Produktgruppen (Product Types) vorgenommen. Die Einteilung eines Artikels erfolgt dabei automatisch und kann nicht direkt vom Verkäufer gesteuert werden. Daneben führt eBay Express intern einen eigenen Produktkatalog der teilweise mit dem eBay-Produktkatalog übereinstimmt. Vermutlich werden sich hier in Zukunft Anpassungen ergeben, da eBay Express noch sehr jung ist.
schnell + kompakt
65
6 – eBay API – can do
6.4 Dispute Das so genannte Dispute-Management ist eine spezielle Sektion im eBay-API-Call, die nur dann benötigt wird, falls irgendetwas bei der Abwicklung eines Verkaufs schief gelaufen ist. Das Verfahren heißt auf Deutsch „Streitigkeit wegen eines nicht bezahlten Artikels“ oder „Streitigkeit wegen eines nicht erhaltenen oder von der Beschreibung abweichenden Artikels“. In der API heißt es dann einfacher UPI (Unpaid Item) oder INR (Item Not Received). Der erste Vorgang ist dabei verkäuferinitiiert; der zweite wird von einem Käufer gestartet. In Bezug auf die API stehen nur die verkäuferbezogenen Funktionen zur Verfügung. Ein Verkäufer kann also einen UPI-Vorgang starten und eventuell abschließen; auf einen INR kann ein Verkäufer nur reagieren. Der Zweck des UPI-Vorgangs – aus der Sicht eines Verkäufers – ist es, die Verkaufsgebühren, die eBay bei einem erfolgten Verkauf erhoben hat, zurückerstattet zu bekommen. Im Wesentlichen gibt es hier zwei Gründe, den Vorgang zu starten. Neben der sicherlich eher seltenen Auslösesituation, dass sich ein Käufer nach einem Verkauf gar nicht oder nur mit viel Verzug meldet, ist hier die Inanspruchnahme des Rückgaberechts eine häufige Ursache. Oft sind es aber auch nur die Unerfahrenheit eines Käufers oder etwa Probleme mit dem eingesetzten Mail-System. Das Dispute-Verfahren ist letztlich einfach nur eine Plattform, um die Kommunikation zwischen Käufer und Verkäufer direkt über das eBay-Nachrichtensystem in geordneten Bahnen mit definierten zeitlichen Fristen sicherzustellen.
UPI – Unpaid Item Ein UPI Dispute kann frühestens sieben Tage nach dem Vorliegen einer Transaktion gestartet werden. Verkäuferseitig wird der Dispute mit der Methode AddDispute gestartet. Hierbei sind die
66
Dispute
ItemID, die TransaktionID und der Grund für den Dispute anzugeben. Nachfolgend kann mittels der Methode AddDisputeResponse in Textform auf eventuelle Antworten des Käufers zu dem entsprechenden Vorgang reagiert werden. Respektive kann mit der Methode GetDispute der gesamte Vorgang inklusive des vorhandenen Nachrichtenaustauschs heruntergeladen werden. Hier stehen alternativ auch Notifications zur Verfügung, die die Daten automatisch bei Vorliegen einer neuen Nachricht liefern. In den meisten Fällen kann ein Dispute nach einer Einigung schnell wieder geschlossen werden; auch hier wird AddDisputeResponse genutzt. Der Verkäufer beantragt dabei die Rückerstattung der Verkaufsgebühr und das Verfahren nimmt automatisch seinen Lauf. Kann keine Einigung erreicht werden, delegiert das System den Vorgang eventuell an den eBay-Kundensupport, wo eine Entscheidung darüber getroffen wird, ob der Käufer verwarnt und vielleicht als „Wiederholungstäter“ vom Handel ausgeschlossen wird.
INR – Item Not Received Der „umgekehrte“ Dispute-Vorgang ist der INR – hier reklamiert ein Käufer, dass ein Artikel ordnungsgemäß bezahlt, aber nicht geliefert wurde, oder dass der Artikel nicht der Artikelbeschreibung entspricht. Dieser Vorgang kann nur über die Website initiiert werden, die eBay API bietet hierzu keine Funktion. Die Reaktion eines Verkäufers erfolgt wiederum mit der Methode AddDisputeResponse. Typischerweise reagiert ein Verkäufer zunächst mit der hoffentlich vorhandenen Paket-Tracking-Nummer seines Versanddienstleisters. Das Verfahren ist für normale Verkäufer damit schon fast zu Ende, jeder andere Status des INR ist eher bei schwarzen Schafen anzutreffen. Letztlich delegiert das System hier automatisch an
schnell + kompakt
67
6 – eBay API – can do
das eBay-Käuferschutzprogramm und natürlich den Kundensupport. Für einen Verkäufer ist es daher sinnvoll, zeitnah auf einen INR zu reagieren. Auch hier kann mit einer Notification schnell auf einen gestarteten Vorgang eines Käufers reagiert werden.
68
KAPITEL 7 eBay API – Technical Advanced 7.1
Versandoptionen national und international
69
7.2
Attribute und Kataloge
70
7.3
eBay Shops
73
7.4
Verwalten von Bildern
74
7.1 Versandoptionen national und international Bei der Einstellung von Artikeln ist insbesondere die Angabe der Versandkosten elementar. Grundsätzlich ist es einem Verkäufer freigestellt, ob die Versandkosten einfach nur als Text, als Teil der Artikelbeschreibung oder mithilfe der API-Strukturen angegeben werden. Allerdings ergibt sich erst durch die Nutzung der API-Felder eine „Berechtigung“ etwa für „Neu & Sofort“ oder auch die Darstellung in eBay Express. Eigentlich unterscheidet eBay grundsätzlich in berechnete und feste Versandkosten. Die so genannten „Calculated Shippingfees“ stehen allerdings bisher nur in den USA zur Verfügung. Für alle anderen Sites können wir uns auf die festen Versandkosten beschränken. Insgesamt lassen sich jeweils drei Versandoptionen für den Versand „im Land“ (domestic) und weitere drei für den Auslandsversand (international) angeben. Nach einem Verkauf kann der Käufer aus diesen die gewünschte Option auswählen. Die Be-
schnell + kompakt
69
7 – eBay API – Technical Advanced
schränkung auf drei Optionen ist leider schon bei einfachen Situationen (z.B. versichert, unversichert, Express) ausgereizt. Grundsätzlich gilt, dass internationale Optionen nur bei Angabe mindestens einer domestic Option genutzt werden können. Jede Versandoption besteht zunächst aus der Versandart (oder dem genutzten Carrier) und den dabei entstehenden Kosten. Daneben können jeweils die Kosten für weitere Artikel angegeben werden, falls ein Käufer gleich mehrere Artikel kaufen möchte. Hinzu kommt optional eine Angabe über die Extrakosten für eine Versicherung (falls dies bei der entsprechenden Versandoption möglich und sinnvoll ist) und hiermit dann auch eine Option für den Käufer, dass die Versicherung hinzugefügt werden kann. Bei den internationalen Optionen wird daneben eine so genannte ShipToLocation angegeben. Dies ist entweder ein ISO-Länderkürzel (z.B. CH, GB, US) oder eine der vordefinierten Gruppen (z.B. Europa, Worldwide etc.). Hierbei ist zu beachten, dass die „Versanddestinationen“ nicht nur bei den Versandoptionen, sondern auch für den Artikel selbst angegeben werden müssen (siehe ShipToLocation im Item). Die Versandoptionen selbst bestehen aus Textwerten, die mit der Methode GeteBayDetails abgerufen werden können.
7.2 Attribute und Kataloge Durch die steigende Anzahl von Artikeln auf dem eBay-Marktplatz ergab sich das Problem, dass Artikel innerhalb der Kategorien kaum noch auffindbar waren. Als Reaktion hätte eBay das Kategoriensystem massiv ausbauen können. Es wurde jedoch eine andere Lösung realisiert, die zwar zunächst deutlich komplexer wirkt, aber zeitnah auf geänderte Anforderungen reagieren kann.
70
Attribute und Kataloge
Die so genannte Attributierung realisiert dabei eine Reihe von Funktionen parallel. Zum einen kann mithilfe eines so genannten AttributeSet eine „Sub-Kategorisierung“ abgebildet werden. Daneben können Artikeln beliebige weitere Merkmale hinzugefügt werden – wobei einschränkend gesagt werden muss, dass „beliebig“ nur aus der Sicht von eBay zutrifft. Das eBay-Team, das für eine bestimmte Kategorie zuständig ist, definiert hierbei für die entsprechende Kategorie ein so genanntes CharacteristicsSet (CsSet). Das CsSet besteht dabei aus einer Menge von Attributen, die einem Artikel in einer bestimmten Kategorie hinzugefügt werden können, und wird jeweils eindeutig mit einer ID definiert. In der Kategorie „Automobile“ sind dies – neben einer Vielzahl anderer – der Hersteller und das Modell eines PKW. Hierbei definiert das CsSet eine Menge von vordefinierten Werten und eine Abhängigkeit zwischen Modell und Hersteller. Daneben wird eine Reihe von „freien“ Attributen definiert, z.B. die KW-Zahl oder das Datum der Erstzulassung. Auch die Attribute erhalten wiederum eindeutige Attribute-IDs. Das CsSet definiert also eine Vorlage für einen wirklichen Artikel. Sobald die Werte dann einem Artikel zugeordnet sind, hat der Artikel ein AttributeSet. Im einfachsten Fall der vordefinierten Werte ist dies dann eine Kombination aus CsSet-, Attributeund Attribute-Value-ID. Neben den ID-Werten können im CsSet auch „freie Werte“ definiert sein. Dazu gehören etwa Datumsangaben oder auch freie Texteingaben (normalerweise zusätzliche Daten, die nicht standardisiert sind, z.B. spezielle Sonderausstattungen eines PKW). Diese Arten werden dann als so genannte Value-Literals angegeben; letztlich einfach nur Texte, die in der Liste von Werten eines Attributs anzugeben sind. Speziell behandelt werden auch Attribute, die mehrere Werte definieren. Besondere Ausstattungsmerkmale – etwa einer Immo-
schnell + kompakt
71
7 – eBay API – Technical Advanced
bilie – werden nicht als multiple Attribute, sondern lediglich als ein einziges Attribut mit mehreren Werten definiert. Ein weiteres Feature eines CsSet besteht darin, dass beliebige (auch multiple) Abhängigkeiten zwischen Attributen und Werten anderer Attribute definiert werden können. Hiermit wird etwa definiert, dass dem Benutzer nach der Auswahl eines PKW-Herstellers nur die Produktpalette des entsprechenden Herstellers gezeigt wird. Eine andere häufig vorkommende Abhängigkeit ist, dass nach der Auswahl des Wertes „Sonstige“ ein weiteres Eingabefeld für den Wert gezeigt wird. Das Attributierungssystem wird auf der eBay-Plattform an unterschiedlichen Stellen mit jeweils anderen Funktionen genutzt. Zunächst kann ein Verkäufer bei der Vorbereitung eines Artikels die gewünschten Attribute für den neuen Artikel zusammenstellen. Die Artikelseite für einen solchen Artikel zeigt dann den entsprechenden HTML-Block vor der Artikelbeschreibung an. Daneben wird das gleiche CsSet im „Produktfinder“ gezeigt; hier können Käufer Suchanfragen formulieren und entsprechende Artikel mit den korrespondierenden Attributen finden. Eine weitere Anwendung ist die Suche (und auch die Verkaufsfunktion) im eBay-Produktkatalog. Soll das Attributierungssystem im Rahmen einer API-Anwendung genutzt werden, ist zunächst das entsprechende CsSet – kategorienabhängig – zu laden. Hierbei führt eBay zu jedem CsSet eine Versionsnummer mit. Das CsSet wird hier leider nur mit einem großen XML-Block geliefert. Ein Schema oder ein Zugriffsweg auf die einzelnen Elemente liefert eBay nicht mit. Das PHP-Ebat definiert eine Erweiterung, die das CsSet mithilfe eines XSD-Schemas in eine PHP-Objektstruktur wandeln kann. Der eBay-eigene Weg nutzt hier ein XSLT-Stylesheet, mit dem das CsSet – jeweils in einer der oben genannten Formen – in eine
72
eBay Shops
HTML-Darstellung umgewandelt werden kann. Für eine Nutzung im eigenen CI oder auch in Skripting-Umgebungen wie PHP muss die XSL-Datei aber massiv angepasst werden. Eine Besonderheit der deutschen eBay-Plattform ist, dass hier auch der Artikelzustand (neu/gebraucht) und die Angaben zum Rückgaberecht mithilfe von Attributen dargestellt werden. Zu beachten ist dabei, dass zunächst für alle Kategorien ein so genanntes SideWide CsSet definiert ist, das die jeweiligen IDs der Attribute und deren Value-IDs definiert. Dieses Set ist immer dann zu nutzen, wenn für die entsprechende Kategorie kein eigenes CsSet definiert wurde. Falls allerdings die Kategorie über ein spezifsches CsSet verfügt, dann müssen die Angaben zum Artikelzustand mit den Daten aus dem spezifischen Set belegt werden. In der Regel werden hier dann auch weitere Werte definiert (z.B. „Runderneuert“ im Bereich „Autoreifen“ oder „Neu mit Etikett“ in den Bekleidungkategorien). Dies gilt allerdings nicht für das CsSet mit Rückgaberecht. Ein Artikel in einer solchen Kategorie besitzt dann oft mehrere AttributSets; das spezifische für die Kategorie inklusive des Artikelzustands und daneben das SideWide AttributSet mit den Angaben zum Rückgaberecht. Das System hat eine recht hohe Komplexität und wird vermutlich in Zukunft einer Generalüberholung unterzogen und vereinfacht.
7.3 eBay Shops Für die Verwaltung von eBay Shops steht in der API eine Reihe von Methoden zur Verfügung. Hiermit ist allerdings nicht die Bestückung eines eBay Shops mit Artikeln gemeint; dafür steht die Standardmethode AddItem unter Angabe eines bestimmten Listingtyps zur Verfügung.
schnell + kompakt
73
7 – eBay API – Technical Advanced
Im Wesentlichen kann das Grundlayout eines eBay Shops beeinflusst werden und es könnnen Optionen gesetzt werden, wie etwa eine Abwesenheit aufgrund von Urlaub. Interessanter ist die Beeinflussung der Crosspromotions sowie die Verwaltung der Shop-Kategorienhierarchie.
7.4 Verwalten von Bildern Die Verwaltung von Bildern zu einem Artikel ist unterschiedlich, je nachdem, welche Form des Bilderhosting und welche eBayBilderpräsentation genutzt werden sollen. Im einfachsten Fall entscheidet sich ein Verkäufer dafür, alle Bilder selbst auf einem eigenen Server zu hosten. Hierbei werden die Bilder einfach mithilfe von normalen HTML-IMG-Tags in der Beschreibung mit den Artikeln verbunden. Sinnvoll ist es allerdings, zumindest das erste Bild unter Zuhilfenahme der API mit dem Artikel zu verbinden. Bei der Einstellung kann dabei das Feld „PictureDetails.PictureURL“ auf die entsprechende URL gesetzt werden. Hierbei bleibt das Bild allerdings immer auf dem „externen“ Bilderserver. Bei einer Ablage der URL im Feld „PictureDetails.GalleryURL“ hingegen wird das Bild einmalig mithilfe eines Robot geladen und dann auf den eBay-eigenen Systemen gehostet. Soll eine der kostenpflichtigen eBay-Bilderoptionen genutzt werden, können anstatt einer URL entsprechend mehr Bilder angegeben werden. Auch hierbei verbleiben die Bilder auf dem externen Server, obwohl der Preis der Bildoption auch das Hosting einschließt. Für die Nutzung des Bilderhosting bei eBay direkt, dem so genannten eBay Picture Service (EPS), müssen sämtliche Bilder zunächst auf die entsprechenden Server geladen werden. Die Bilder werden dann in unterschiedlichen Größen skaliert und mit
74
Verwalten von Bildern
einem Wasserzeichen versehen. Solange diese URLs in einer der Bildoptionen in irgendeinem Artikel genutzt werden, verbleiben die Bilder auf dem EPS (und weitere 90 Tage über das Ende des Artikels hinaus). Das Verfahren für das Hochladen der Bilder auf den EPS ist allerdings nicht öffentlich dokumentiert und kein Bestandteil der offiziellen eBay API. Das Windows SDK und das PHP Ebat liefern allerdings Module für die Nutzung des EPS mit. Zusammengenommen ist die Bildverwaltung bei eBay selbst aber noch höchst unbefriedigend und durch die API nur schwer realisierbar.
schnell + kompakt
75
KAPITEL 8 Code-Beispiele 8.1
Installation und Basisparameter
78
8.2
Proxy, Session und Request
78
8.3
Artikelsuche
79
8.4
Artikel einstellen
82
8.5
Transaktionen abrufen
84
8.6
Kommunikation mit Käufer und Verkäufer
85
8.7
Rechnung schicken
86
8.8
Feedback hinterlassen
87
8.9
Kategorien abrufen
88
Dieser Abschnitt enthält eine Reihe von Code-Beispielen für typische Anwendungsfälle der eBay API. Leider stand hier nur ein begrenzter Platz zur Verfügung, daher war es nicht möglich, alle in Frage kommenden Entwicklungssprachen zu zeigen. Aufgrund der persönlichen Präferenz des Autors für PHP finden sich hier lediglich Beispiele in eben dieser Sprache. Beispiele für .NET (VB.NET bzw. C#) finden sich im entsprechenden SDK; Gleiches gilt auch für Java. Andere Sprachen mit der Möglichkeit der Microsoft-COM-Bindung (z.B. Visual Basic 6.0) werden mithilfe des .NET SDK sowie durch die Nutzung von COM-Interop bedient. Grundsätzlich ist der Ablauf der API-Nutzung vielfach sehr ähnlich. Die untenstehenden Techniken lassen sich bei Anpassung an die Syntax entsprechend auch in allen Sprachen nachvollziehen.
schnell + kompakt
77
8 – Code-Beispiele
8.1 Installation und Basisparameter Für die nachfolgenden Code-Beispiele wird das eBay Acellerator Toolkit for PHP (EbatNs) genutzt. Dieses kann unter http:// ebatns.codebase.ebay.com heruntergeladen und danach installiert werden. Wesentlich ist die Aufnahme des Installationsordners in den „include_path“ innerhalb der php.ini der PHP-Installation. Das Keys-Triple (Sandbox bzw. Produktion) kann in einer Config-Datei (ebay.config.php) abgelegt werden. Ein Token, der sich mit dem Token-Test-Tool erzeugen lässt (http://developer.ebay.com/ tokentool), sollte hiernach in einer weiteren Datei gespeichert werden. Der Pfad auf diese Datei ist danach in der Config-Datei anzugeben. Die Anforderungen an die Betriebssystem-Software sind zwar grundsätzlich gering, allerdings ist neben PHP (ab Version 4.3) auch das PHP-Modul cURL inklusive OpenSSL und zLib notwendig. Daneben wird die XML-Erweiterung xml expat benötigt, wobei dies eine „Standarderweiterung“ von PHP ist und daher nur in Ausnahmefällen fehlt. CURL ist allerdings nicht bei allen Providern vorhanden; vor der Nutzung ist dies daher bei der Verwendung eines Webservers, der nicht unter der eigenen Verwaltung steht, entsprechend zu prüfen und eventuell zu konfigurieren.
8.2 Proxy, Session und Request Die objektorientierte PHP-Klassenstruktur des EbatNs kapselt die Authentifizierungsdaten (Key-Triple und Token) in der Klasse EbatNs_Session. Diese Daten werden in der Regel durch die Config-Datei (bzw. die verwiesene Token-Datei) bereitgestellt. Bei Bedarf können die Daten auch anderweitig, etwa durch Abfrage aus einer Datenbank oder auch direkte Benutzereingaben, gesetzt werden.
78
Artikelsuche
Das Session-Objekt wird hiernach zur Initialisierung eines Objekts der Klasse EbatNs_ServiceProxy verwendet. Diese Klasse ist für die SOAP-Kommunikation mit dem eBay-Web-Service verantwortlich. Für die Ausführung eines API-Call muss nun noch ein RequestObjekt erzeugt werden, das die methodenabhängigen Parameter speichert. Der Service-Proxy bietet nun für jeden API-Call eine Methode, der das entsprechende Request-Objekt zu übergeben ist. Das Ergebnis (und somit der Rückgabewert) ist stets ein Response-Objekt. Im Fall eines fehlerfreien Verlaufs enthält dieses die angeforderten Daten, ansonsten aber zumindestens den Grund des Scheiterns in Form einer Fehler-Collection.
8.3 Artikelsuche
Grundsätzlich ist das Einstellen von Artikeln einfach. Nach der üblichen Vorbereitung für die Erzeugung des ServiceProxy wird ein entsprechendes Request-Objekt erzeugt (AddItemRequestType). Zuvor wird ein Objekt des Typs ItemType erzeugt und mit den minimal notwendigen Daten gefüllt. Abschließend folgt die Platzierung im „Request“-Objekt. Schließend das Absetzen des Calls. In einem „echten“ System wird der Aufbau deutlich komplexer sein müssen. Hier sind weitere Daten im „Item“ zu definieren, wie Informationen zu den angebotenen Versandarten, weitere Zahlungsmethoden, aber auch Angaben zum Rückgaberecht bzw. zum Artikelzustand. Sicherlich wird die Beschreibung dann deutlich umfangreicher ausfallen; wobei hier selbstverständlich auch HTML-Code genutzt werden kann.
schnell + kompakt
83
8 – Code-Beispiele
8.5 Transaktionen abrufen
Die hier dargestellte Form berücksichtigt lediglich die Verkäufe zu einem ganz bestimmten Artikel, daneben existiert auch eine Methode, die alle Verkäufe eines bestimmten Verkäufers miteinbezieht (GetSellerTransactions). Das Verfahren ähnelt sich in beiden Fällen: Es muss jeweils ein Datumsbereich (ModTime) angegeben werden. Hierbei ist zu beachten, dass die eBay API grundsätzlich mit Zeitangaben in der GMT/UTC-Zeitzone arbeitet.
84
Kommunikation mit Käufer und Verkäufer
Die so genannte ModificationTime einer Transaktion (= Verkauf) stellt den Zeitpunkt dar, zu dem eine Veränderung vorgenommen wurde. Zunächst ist dies der Zeitpunkt des Verkaufs; später, während und nach der Verkaufsabwicklung, der Zeitpunkt der letzten Datenänderung bzw. Datenergänzung, die der Käufer bzw. der Verkäufer vorgenommen hat. Bitte beachten Sie, dass die ItemID hier sicherlich nicht mehr auf einen gültigen Artikel verweisen wird, wenn Sie das Beispiel ausprobieren.
8.6 Kommunikation mit Käufer und Verkäufer
Die Kommunikation mit einem anderen eBay-Mitglied über das eBay-eigene Nachrichtensystem wird in der API zwar unterstützt, allerdings ist wegen der Vermeidung von Spam der initiale Start einer Kommunikation nicht möglich, ohne dass bereits eine „geschäftliche“ Beziehung zwischen den Parteien besteht. Ein Verkäufer kann – unter Angabe einer Artikelnummer – mit einem Mitglied Kontakt aufnehmen, das als Käufer des entsprechenden Artikels bekannt ist. Daneben kann problemlos auf Nachrichten geantwortet werden.
8.7 Rechnung schicken
Den Abschluss einer Transaktion kann die Versendung einer Rechnung per E-Mail bilden. Hierbei ist die Artikelnummer (ItemID), aber auch eine so genannte TransactionID anzugeben. Bei normalen Auktionen ist diese ID immer „0“. Bei anderen Artikelformaten (Anzahl ist größer 1) kann es ja mehr als eine Transaktion je Artikel geben, entsprechend variiert hier die TransactionID.
8.8 Feedback hinterlassen
Das Hinterlassen von Bewertungen mittels der API ist recht einfach. Achtung, das Feld TransactionID ist tückisch. Zunächst vermutet man die TransactionID des entsprechenden Verkaufs. Hier muss allerdings die „FeedbackID“ einer durch einen Käufer hinterlassenen Bewertung genutzt werden. Somit ist das Hinterlassen von Feedback eines Verkäufers durch die API bei einem „Artikel mit der Anzahl größer 1“ erst nach Vorliegen der Käuferbewertung möglich.
8.9 Kategorien abrufen $session = new EbatNs_Session('config/ebay.config.php'); $cs = new EbatNs_ServiceProxy($session); $handler = new handlerMethods($cs); $req = new GetCategoriesRequestType(); $req->CategorySiteID = 77; $req->LevelLimit = 1; $req->DetailLevel = 'ReturnAll'; $res = $cs->GetCategories($req);
88
Kategorien abrufen
class handlerMethods { function handlerMethods(& $cs) { $cs->setHandler('CategoryType', array(& $this, 'handleCategory')); } function handleCategory($type, & $Category) { echo $Category->CategoryID . "/" . $Category>CategoryParentID[0] . $Category->CategoryName . "
"; return true; } }
Der regelmäßige Abruf des Kategorienbaums ist sinnvoll, wenn nicht nur mit festgelegten Kategorien-IDs gearbeitet werden soll. Die Daten sollten dabei in einer geeigneten Form (z.B. einer Datenbank) abgelegt werden. Achtung, die Datenmenge hier ist enorm und stellt Anforderungen insbesondere an den Arbeitsspeicherverbrauch. Aus diesem Grund sollte hier das dargestellte Verfahren genutzt werden. Dabei werden die Daten mithilfe des Handler-Features des EbatNs jeweils – ressourcenschonend – zeilenweise an die HandlerMethode durchgereicht und können dort gespeichert werden.
schnell + kompakt
89
ANHANG Kurzbeschreibung zu jedem API-Call
AddDispute: Eröffnet einen Dispute (UPI oder INR) mit der Angabe einer Artikelnummer und einer Transaktionsnummer. Der Dispute kann frühestens acht Tage nach Ende einer Auktion eröffnet werden, wenn Käufer und Verkäufer sich nicht einigen konnten. AddDisputeResponse: Fügt einem bestehenden Dispute eine Nachricht bzw. eine Antwort hinzu oder schließt den Dispute. Das Schließen kann nur vom Verkäufer initiiert werden. AddItem: Wird zum Einstellen von Artikeln genutzt. Das Ergebnis sind eine neue ItemID sowie die Gebühren für die Einstellung. AddLiveAuctionItem: Definiert eine Live-Auktion; zurzeit nur auf eBay.com; ansonsten identisch zu AddItem. AddMemberMessage: Antwort auf eine „Frage an den Verkäufer“. Die Antwort landet im „Meine Nachrichten“-Postfach des eBay-Benutzers. Wird ersetzt durch AddMemberMessageRTQ. AddMemberMessageAAQToPartner: Ermöglicht den Nachrichtenaustausch über das eBay-„Meine Nachrichten“-System.
schnell + kompakt
91
Anhang – Kurzbeschreibung zu jedem API-Call
Die Nutzung ist aber nur bis maximal 90 Tage nach Ende der Auktion möglich. AddMemberMessageRTQ: Antwortet auf die Frage eines potenziellen Käufers zu einem aktiven Artikel. Die Nachricht wird im eBay-Nachrichtensystem abgelegt. AddMemberMessagesAAQToBidder: Ermöglicht einem Verkäufer die anonyme Kommunikation mit einem Bieter oder Mitgliedern, die ein „Best Offer“-Angebot gemacht haben. Die Nachricht wird im eBay-Nachrichtensystem abgelegt. AddOrder: Kombiniert zwei oder mehr Transaktionen in einer Bestellung. Die Bestellung erhält eine eindeutige OrderID und Käufer können danach die gemeinsame Einstellung oder eine Kombizahlung vornehmen. AddSecondChanceItem: Ein Verkäufer kann hier unterlegenen Bietern ein Angebot unterbreiten, z.B. in dem Fall, dass noch mehr gleichartige Artikel auf Lager sind oder der Höchstbieter zurückgetreten ist. Das Ergebnis ist ein „neuer“ Artikel, der nur von den entsprechenden Mitgliedern erworben werden kann. AddToItemDescription: Erlaubt das Hinzufügen von weiteren Textanmerkungen an das Ende einer bestehenden Artikelbeschreibung. Sinnvoll bei marginalen Fehlern, die eine komplette Überarbeitung nicht lohnen, AddToWatchList: Fügt einen Artikel der Beobachtungsliste eines eBay-Mitglieds hinzu. AddTransactionConfirmationItem: Beendet einen Artikel und fügt einen neuen „Transaction Confirmation Request“ (TCR) für einen Artikel hinzu. Aktuell wird der Call nur für eBay Motors USA benötigt.
92
Kurzbeschreibung zu jedem API-Call
ApproveLiveAuctionBidders: Erlaubt die Teilnahme eines Bieters an einer eBay-Live-Auktion. Live-Auktionen sind bisher nur auf eBay.com möglich. CompleteSale: Erlaubt den Abschluss einer Transaktion inklusive des Hinterlassens einer Bewertung für den Käufer, des Setzens des Bezahlt- oder des Versendet-Status in „Mein eBay“ oder eine Kombination der Aktionen. DeleteMyMessages: Löscht Nachrichten oder Warnungen aus dem eBay-Nachrichtensystem. EndItem: Erlaubt einem Verkäufer das vorzeitige Beenden einer Auktion oder eines anderen Artikels. Achtung, bei Auktionen mit aktiven Bietern führt dies zum Verkauf an diesen zum aktuellen Gebot. FetchToken: Ruft einen hinterlegten Token für einen Benutzer ab. Die Hinterlegung muss mithilfe des Auth&Auth-Prozesses zuvor gestartet werden. GetAccount: Ruft die Kontodaten eines eBay-Benutzers ab. Hier werden sämtliche Kontobewegungen (Gebühren, Gutschriften und Zahlungen) gelistet. Bei Bedarf können Übersichten oder detaillierte Informationen abgerufen werden. GetAdFormatLeads: Holt die Kontaktinformationen von Mitgliedern ab, die sich auf eine Immobilienanzeige gemeldet haben. Alternativ kann der Abruf auch über das eBay-Nachrichtensystem erfolgen. Das Ad-Format steht mittlerweile auch in anderen als der Immobilienkategorie zur Verfügung. GetAllBidders: Ermöglicht den Abruf der Bieter einer Auktion. Im Wesentlichen kann mit der Liste die Funktion „Angebot an unterlegene Bieter“ genutzt werden. GetApiAccessRules: Ruft eine Statistik über die eBay-API-Nutzung für eine bestimmte Anwendung ab.
schnell + kompakt
93
Anhang – Kurzbeschreibung zu jedem API-Call
GetAttributesCS: Ruft das CharacteristicsSet für eine bestimmte Kategorie ab. In manchen Kategorien ist die Nutzung des CsSet obligatorisch, für andere optional. Der Call liefert neben den nutzbaren Attributen auch deren eventuell vorhandene Vorgabewerte. Daneben wird eine Darstellungsvorschrift geliefert, mit der die Reihenfolge der Elemente sowie etwaige Abhängigkeiten untereinander definiert werden. Die Daten werden jeweils mit einer Versionskennung geliefert; durch Nutzung eines entsprechenden Detail-Level kann auch nur diese Kennung abgerufen werden. GetAttributesXSL: Ruft ein XSL-Stylesheet ab, das zur Transformation eines CsSet und dessen HTML-Darstellung genutzt werden kann. Das resultierende HTML-Fragment ähnelt der Darstellung im Verkaufsprozess auf der eBay-Website. GetBestOffers: Ruft die Informationen über das Best-OfferFeature (Preisvorschlag) von laufenden oder beendeten Auktionen ab. GetBidderList: Ruft eine Liste von Artikeln ab, auf die ein eBayBenutzer geboten hat. Dies schließt laufende, aber auch „gewonnene“ oder gekaufte Artikel mit ein. GetCategories: Ruft den eBay-Kategorienbaum ab. Jede Kategorie enthält dabei neben einem Klartextnamen auch die KategorienID und Kennzeichen über übergeordnete (Parents) Kategorien. Mithilfe von Filtern und Detail-Levels kann bestimmt werden, ob sich die Hierarchie geändert hat und somit ein erneuter Abruf notwendig ist. GetCategory2CS: Ermittelt das Mapping zwischen einer Kategorie und einem (oder mehreren) CharacteristicsSets. GetCategory2FinanceOffer: Abruf von Finanzierungsoptionen in einer bestimmten Kategorie. Steht nur auf eBay.com zur Verfügung.
94
Kurzbeschreibung zu jedem API-Call
GetCategoryFeatures: Ermittelt die nutzbaren Optionen für das Einstellen eines Artikels in einer bestimmten Kategorie. Dazu gehören die nutzbare Dauer, die besonderen Versandoptionen oder auch spezielle Features wie etwa Best-Offer. GetCategoryListings: Ermöglicht den Abruf einer vollständigen Liste von Artikeln einer bestimmten Kategorie. Die Daten können nach einer Vielzahl von Kriterien gefiltert bzw. sortiert werden. GetCategoryMappings: Für Kategorien, die entfernt oder geändert wurden, lässt sich das Mapping abrufen, welches das System bei Nutzung der alten Kategorie vornehmen wird. GetChallengeToken: Ermöglicht die Erzeugung und den Abruf eines Captchas (Bild und Ton). Dieser Call steht nur speziell freigeschalteten Anwendungen zur Verfügung. GetCharities: Führt eine Suche nach „Charity“-Organisationen durch. Nur auf eBay.com. GetContextualKeywords: Durchsucht eine externe URL und ermittelt eine Liste von Suchwörtern. Die Liste kann danach als Ausgangspunkt für eine eBay-Suche dienen. GetCrossPromotions: Ruft die Crosspromotion-Artikel ab, die auf der Artikelseite oder der nachfolgenden Verkaufsabwicklung für einen bestimmten Artikel in der „Promotionbox“ gezeigt werden. GetDescriptionTemplates: Lädt Layout- und Themenvorlagen, die in einer Auktion (kostenpflichtig) genutzt werden können. Der Call gibt die Möglichkeit, die Vorschau einer Artikelbeschreibung zu konstruieren. GetDispute: Lädt den vollständigen Dispute-Vorgang inklusive aller Nachrichten und eventuell „Lösungen“.
schnell + kompakt
95
Anhang – Kurzbeschreibung zu jedem API-Call
GeteBayDetails: Lädt eine Reihe von Vorgabendaten, die spezifisch für eine bestimmte eBay-Site sind. GeteBayOfficialTime: Ruft die aktuelle Referenz-Uhrzeit (in GMT/UTC) aus dem eBay-System ab. GetFeedback: Ermöglicht einem Benutzer (Käufer oder Verkäufer), seine Bewertungshistorie abzurufen. Je nach Detail-Level werden dabei lediglich eine Übersicht oder die gesamte Historie inklusive aller Texte und Antworten geliefert. GetFinanceOffers: Ergibt eine Liste aller auf einer Site verfügbaren Finanzierungsoptionen. Auf eBay.de nicht aktiv. GetHighBidders: Ruft die Ergebnisbieterliste einer Power-Auktion ab. Hierbei wird die Liste der erfolgreichen Bieter mit der Artikelanzahl, die den entsprechenden Bietern zugeordnet wurde, inklusive des festgelegten Preises geliefert. GetItem: Ermittelt den vollständigen Datensatz zu einem Artikel. Dies beinhaltet neben der Artikelbeschreibung die gesetzten Attribute, Versandoptionen, Zahlungsmethode und die genutzten Features. Bei einer laufenden Auktion lässt sich der eventuelle Höchstbieter ersehen; bei einer beendeten Auktion werden eventuell bereits ausgewählte Optionen der Verkaufsabwicklung gezeigt. Die Menge der Daten kann mit dem Detail-Level oder dem Granularity-Level bei Bedarf eingeschränkt werden. GetItemRecommendations: Der Call ruft „Empfehlungen“ ab, die zu einem besseren Verkaufserfolg führen sollen. Dabei wird ein Artikel in der gleichen Form wie bei einem Listing übergeben. GetItemsAwaitingFeedback: Ermittelt eine Liste von Artikeln, für die die Abgabe von Bewertungen möglich ist. GetItemShipping: Ruft Daten für eine Kalkulation von Versandkosten zu einem bestimmten Artikel ab. Da auf eBay.de nur
96
Kurzbeschreibung zu jedem API-Call
„Flat“-Shipping möglich ist, beschränkt sich die Funktion auf die Rückgabe der bei dem entsprechenden Artikel gesetzten Versandoption. GetItemTransactions: Ermittelt eine Liste der vorliegenden Transaktionen zu einem bestimmten Artikel. Dabei werden keine, eine einzige oder mehrere Transaktionen geliefert, in Abhängigkeit von Status und Typ des Artikels. Die Methode ermöglicht die sinnvolle Einschränkung auf das Datum der letzten Modifikation einer Transaktion. GetLiveAuctionBidders: Ruft eine Liste von Bietern ab, die sich für die Teilnahme an einer Live-Auktion gemeldet haben. Nur auf eBay.com. GetLiveAuctionCatalogDetails: Ruft den Live-Auktionskatalog und die geplanten Auktionszeiten für einen Verkäufer ab. Nur auf eBay.com. GetMemberMessages: Liefert eine Liste von „Fragen zu einem Artikel”, die für einen Verkäufer vorliegen. Verkäufer können mit der Methode AddMemberMessage diese beantworten. GetMyeBay: Der Call steht in Kürze nicht mehr zur Verfügung; nutzen Sie bitte stattdessen GetMyeBayBuying bzw. GetMyeBaySelling. GetMyeBayBuying: Liefert die Daten für die Darstellung des „Mein eBay“-Bereichs für Käufer, also Listen mit beobachteten Artikeln, gewonnenen und verlorenen Auktionen, aktuellen Geboten, aber auch gespeicherte Suchen und Verkäufer. GetMyeBayReminders: Ruft „Erinnerungen“ (z.B. für Artikel oder das eBay-Konto betreffend) für ein Mitglied ab. GetMyeBaySelling: Liefert die Daten für die Darstellung des „Mein eBay“-Bereichs für Verkäufer, also Listen mit aktuell lau-
schnell + kompakt
97
Anhang – Kurzbeschreibung zu jedem API-Call
fenden Artikeln, abgelaufenen Artikeln und Informationen über verkaufte Artikel. GetMyMessages: Ermöglicht den Zugriff auf das eBay-Nachrichtensystem. GetNotificationPreferences: Ermittelt die Einstellungen für die Nutzung der Notifications (anwendungs- bzw. nutzerspezifisch). GetNotificationsUsage: Liefert eine Statistik über die Notifications, die das eBay-System an eine bestimmte Anwendung versendet, und deren Verarbeitungsstatus. Hilfreich für das Debugging einer Anwendung, die Notifications nutzt. GetOrders: Ermittelt alle Bestellungen, an denen ein Nutzer (als Käufer oder Verkäufer) beteiligt ist. GetOrderTransactions: Ruft die Bestellungen inklusive der untergeordneten Transaktionen nutzerspezifisch ab. GetPictureManagerDetails: Ermittelt die Einstellungen im eBay PictureManager für einen bestimmten Benutzer. Der Call lässt auch die Umstruktierung der Daten (Organisation von Ordnern) zu, aber nicht den Upload von Dateien. GetPictureManagerOptions: Ermitteln die Vorgabedaten für den eBay PictureManager. Diese Informationen sind nicht benutzerspezifisch. GetPopularKeywords: Ermittelt eine Liste von Suchwörtern, die von Käufern in einer bestimmten Kategorie häufig genutzt wurden. GetProductFamilyMembers: Bietet ein Interface für den Abruf von Produktdaten aus dem eBay-Katalog. Dieser Call wird für den Drilldown in eine Produktfamilie genutzt.
98
Kurzbeschreibung zu jedem API-Call
GetProductFinder: Ermöglicht den Abruf von Meta-Informationen (XML-Dokument) für den Aufbau eines „ProductFinder“ (Suche mithilfe von Attributen). Nutzen Sie diese Methode zusammen mit GetProductSearchResults für eine Suche. GetProductFinderXSL: Lädt ein XSL-Stylesheet für eine Transformation des durch GetProductFinder gelieferten XML-Dokuments in HTML. GetProductSearchPage: Der Call liefert einen vereinfachten ProductFinder für die Suche im eBay-Katalog. Mit einer resultierenden Benutzereingabe kann die Suche in einer Kategorie durchgeführt werden. GetProductSearchResults: Sucht innerhalb einer bestimmten Kategorie nach Artikeln, die mithilfe von „vordefinierten Artikelmerkmalen“ (eBay-Produkt-Katalog) eingestellt wurden. Achtung: keine Suche in den Attributen. GetProductSellingPages: Ruft die „vordefinierten Produktmerkmale“ (= Attribute) für ein bestimmtes Produkt ab. Diese Daten können für das Einstellen eines Artikels genutzt werden. Die gelieferten Daten können direkt (oder nach einer Ergänzung bzw. Anpassung) als AttributeSet für einen neuen Artikel genutzt werden. GetPromotionRules: Die Methode zeigt die aktuell definierten Regeln für die Crosspromotion eines bestimmten Artikels oder einer eBay-Shop-Kategorie. GetRecommendations: Der Call steht in Kürze nicht mehr zur Verfügung, bitte nutzen Sie stattdessen GetItemRecommendations. GetReturnURL: Liefert die definierten RuNamen, die von einer Anwendung für die Nutzung des Auth&Auth-Verfahrens hinterlegt worden sind.
schnell + kompakt
99
Anhang – Kurzbeschreibung zu jedem API-Call
GetRuName: Generiert einen weltweit eindeutigen RuNamen, der als Eingabeparameter für SetReturnURL genutzt werden kann. GetSearchResults: Führt eine Suche auf der eBay-Artikeldatenbank aus. Dabei können die meisten Funktionalitäten genutzt werden, die auch einem Benutzer der eBay-Website zur Verfügung stehen. Hierzu gehört auch die Suche mit Wildcards, in eBay Shops oder die Einschränkung auf bestimmte Artikelarten oder besondere Features. Normalerweise findet die Suche nur in Titel und Untertitel statt, sie kann aber auf die Artikelbeschreibung ausgedehnt werden. GetSearchResultsExpress: Ermöglicht die Suche in Artikeln, die auf eBay Express gelistet sind. Daneben wird eine Statistik über die Verteilung der Artikel in den eBay Express Departments, Aisles und Product Types geliefert. GetSellerEvents: Liefert eine Kurzübersicht über die Aktionen, die innerhalb der letzten 48 Stunden auf den Artikeln eines Verkäufers stattgefunden haben. Hierzu gehören Preisänderungen, Gebote und beendete bzw. gestartete Artikel. GetSellerList: Ruft eine detaillierte Liste der Artikel eines bestimmten Verkäufers ab. Die Liste enthält die wesentlichen Informationen, aber keine Artikelbeschreibungen und keine Zahlungs- bzw. Versandmethoden. GetSellerPayments: Ruft eine Übersicht ausstehender Zahlungen für einen Verkäufer für Half.com-Artikel ab. Half.com hat bisher keine deutsche Niederlassung, gehört aber mit zur eBayGruppe. GetSellerTransactions: Ermittelt eine Liste von Transaktionen eines Verkäufers. Diese enthält detaillierte Informationen der Käufer und eventuell auch deren Liefer- und Registrierungsadressen.
100
Kurzbeschreibung zu jedem API-Call
GetStore: Die Methode ruft detaillierte Informationen für die Konfiguration eines eBay Shops ab. Für den Abruf von speziellen Seiten muss die Methode GetStoreCustomPage genutzt werden. GetStoreCategoryUpdateStatus: Nach der Änderung von eBayShop-Kategorien mit SetStoreCategories werden diese asynchron verarbeitet. Dieser Call dient der Überprüfung des aktuellen Änderungsstatus. GetStoreCustomPage: Ruft eine spezielle Custom-Page eines eBay-Shop-Betreibers ab. Die Möglichkeit, solche Seiten zu verarbeiten, ist abhängig vom gebuchten eBay Shop. GetStoreOptions: Liefert die aktuellen eBay-Shop-Optionen. Hierzu gehören Logos, Farbschemas und der aktuell gebuchte eBay-Shop-Typ. GetStorePreferences: Ruft die aktuellen Voreinstellungen eines eBay Shops ab. Im Wesentlichen ist dies der „Urlaubsstatus“ des Shop-Besitzers. GetSuggestedCategories: Liefert eine Liste der Top10-Kategorien, in denen Artikel gelistet wurden, die einem Suchbegriff entsprechen. GetTaxTable: Ermöglicht die Ausgabe einer Steuertabelle für eine bestimmte eBay-Site. In Deutschland wird dieser Call nicht benötigt, da es keine steuerlichen Unterschiede (Mehrwertsteuer) in den Bundesländern gibt. GetUser: Liefert Informationen über ein bestimmtes eBay-Benutzerkonto. Achtung: Die Daten sind Retrieves data for one eBay user. Falls es keine Transaktion zwischen einem Käufer bzw. Verkäufer in Bezug auf eine anzugebende Artikelnummer gibt, sind die Daten massiv eingeschränkt. GetUserContactDetails: Liefert Kontaktinformationen für Bieter oder Mitglieder, die einen Preisvorschlag (Best Offer) gemacht
schnell + kompakt
101
Anhang – Kurzbeschreibung zu jedem API-Call
haben. Grundsätzlich wird keine E-Mail-Adresse geliefert, die Kommunikation kann aber via AddMemberMessagesAAQToBidder über das eBay-Nachrichtensystem erfolgen. GetUserDisputes: Der Call erzeugt eine Liste von Disputes, in denen ein eBay-Mitglied als Käufer oder Verkäufer involviert ist oder innerhalb der letzten fünf Jahre involviert war. GetUserPreferences: Liefert eine Reihe von Voreinstellungen für einen Benutzer (Kombinierte Zahlung, Crosspromotion, E-Mails am Ende der Auktion, Artikelmerkliste, eBay Express, Verkäufereinstellungen). GetWantItNowPost: Liefert detaillierte Informationen über eine eBay-Suchanzeige. GetWantItNowSearchResults: Führt eine Suche in den eBaySuchanzeigen durch. IssueRefund: Rückerstattung einer Zahlung auf Half.com. Half.com hat bisher keine deutsche Niederlassung, gehört aber zur eBay-Gruppe. LeaveFeedback: Ermöglicht das Hinterlassen einer Bewertung für einen Verkaufsvorgang. PlaceOffer: Ermöglicht das Bieten auf eine Auktion. Achtung: Dieser Call steht nicht öffentlich zur Verfügung, sondern benötigt eine spezielle Freischaltung. RelistItem: Stellt einen abgelaufenen und nicht verkauften Artikel erneut ein. Dabei ist der erste Relist kostenreduziert in Bezug auf die Einstellgebühren, solange keine neuen erweiterten Features genutzt werden. RemoveFromWatchList: Entfernt einen Artikel aus der Beobachtungsliste.
102
Kurzbeschreibung zu jedem API-Call
RespondToBestOffer: Ermöglicht dem Verkäufer eines Artikels, für den die Preisvorschlagsoption aktiviert ist, die Antwort auf einen solchen Vorschlag. RespondToFeedback: Auf einen Bewertungseintrag kann mit dieser Funktion geantwortet werden. RespondToWantItNowPost: Ermöglicht es, zu einer eBay-Suchanzeige einen Artikel mit einer „Antwort“ zu erstellen. ReviseCheckoutStatus: Ändert den „Bezahlt“-Status einer Transaktion oder Bestellung. ReviseItem: Erlaubt es einem Verkäufer, einen aktuell laufenden Artikel zu überarbeiten. Dabei können neben der Beschreibung die meisten Datenfelder angepasst werden. Teilweise bestehen hier Restriktionen in Bezug auf die änderbaren Felder. Grundsätzlich ist eine Überarbeitung bis zwölf Stunden vor Ablauf des Artikels möglich, wobei hier in bestimmten Kategorien andere Regeln gelten können. Daneben ist die Änderungsmöglichkeit eingeschränkt, falls auf Auktionen bereits Gebote vorliegen. ReviseLiveAuctionItem: Erlaubt die Änderung einer Live-Auktion. Nur auf eBay.com. ReviseMyMessages: Beeinflusst die Änderung des „gelesen“Status auf Nachrichten im eBay-Nachrichtensystem. ReviseMyMessagesFolders: Ermöglicht die Bearbeitung der Ordnerstruktur im eBay-Nachrichtensystem. SellerReverseDispute: Ermöglicht das Zurückziehen eines Dispute. Der Dispute muss zuvor geschlossen werden. SendInvoice: Erzeugt eine E-Mail-Rechnung und sendet diese an den Käufer. SetNotificationPreferences: Definiert Voreinstellungen für die Nutzung der eBay Notifications. Hierbei können sowohl anwen-
schnell + kompakt
103
Anhang – Kurzbeschreibung zu jedem API-Call
dungsweite Einstellungen als auch die Abonnierung einer bestimmten Notification für einen Benutzer festgelegt werden. SetPictureManagerDetails: Setzt Einstellungen für das PictureManager-Abo eines Benutzers. SetPromotionRules: Definiert eine Crosspromotion-Regel für einen bestimmten Artikel oder eine eBay-Shop-Kategorie. SetRedirectionDetails: Setzt die URL für einen Checkout Redirect. Kann nur von speziellen freigeschalteten Anwendungen genutzt werden. SetReturnURL: Setzt die ReturnURL, die im Rahmen des Auth& Auth-Verfahrens genutzt wird. SetStore: Definiert die Voreinstellungen eines eBay Shop. SetStoreCategories: Der Call ermöglicht die Veränderung von eBay-Shop-Kategorien. Die Änderungen werden hierbei asynchron durchgeführt. SetStoreCustomPage: Ermöglicht den Upload einer speziellen Custom-Page in den eBay Shop eines Benutzers. Diese kann dabei auch aus freien HTML-Inhalten bestehen. SetStorePreferences: Setzt die Einstellungen eines eBay-ShopBesitzers; im Wesentlichen die Urlaubseinstellungen. SetTaxTable: Definiert eine Steuertabelle. Auf eBay.de weder möglich noch sinnvoll. SetUserNotes: Fügt einem Artikel in einer der „My eBay“-Listen eine freie Bemerkung hinzu. SetUserPreferences: Setzt eine Reihe von benutzerspezifischen Einstellungen (siehe GetUserPreferences).
104
Kurzbeschreibung zu jedem API-Call
ValidateChallengeInput: Validiert die Benutzereingabe nach einem zuvor generierten Captchas. Dieser Call steht nur speziellen freigeschalteten Anwendungen zur Verfügung. ValidateTestUserRegistration: Testmethode zur Manipulation der Benutzerdaten. Steht nur auf der eBay Sandbox zur Verfügung. VerifyAddItem: Erlaubt die Überprüfung eines Artikels vor der wirklichen Einstellung. Die Eingabeparameter entsprechen hierbei AddItem. Die Methode liefert ähnliche Ausgabedaten, aber keine Artikelnummer. VerifyAddSecondChanceItem: Erlaubt die Überprüfung eines „Angebots an einen unterlegenen Bieter“ vor der wirklichen Einstellung.
schnell + kompakt
105
Stichwortverzeichnis .NET 41
A AcceptURL 47 AddDispute 66 AddDisputeResponse 67 AddItem 59, 82 AddMemberMessage 62 AddMemberMessageAAQToPartner 62, 85 AddMemberMessageRTQ 62 AddOrder 64 AddSecondChanceItem 61 AddToItemDescription 61 Angebot an unterlegene Bieter 28 Application ID 34 Artikelbeschreibung 19 Artikelzustand 20, 73 Attribute 20, 70 AttributeSet 71 Auktionsdauer 21 Ausstattungsmerkmale 71 Auth & Auth 35
B Best Offer 28 Bestellung 26, 64 Bilder 22 Bold 22 Border 22
C calculated shipping 20 Certificate 34 CharacteristicsSet 20, 53, 71
schnell + kompakt
CheckoutRedirect 26 Chinese-Auction 19 Combined Payment 64 Compatibility Level 32, 49 CompleteSale 64 Crosspromotion 60 CsSets 20, 53
D Detail Level 50 Developer ID 34 Diashow 23 Dispute 27, 66 domestic shipping 20, 69 Dutch-Auction 19
E Ebat 78 EbatNs ServiceProxy 42 Session 42 eBay Affliates 64 Applikationsverzeichnis 14 Entwicklerprogramm 11 Express 10, 18, 29 Kategorien 53 Notification 48 Partnerprogramm 14 Passwort 57 Picture Service 23 Produktkatalog 72 Shop 73 Suchanzeigen 29 eBay ID 17 eBay Picture Service 74
107
Stichwortverzeichnis
Einstellkosten 27 EndItem 60 EPN 49 EPS 23, 41
H
F
I
Feedback 26, 64 Festpreis 18 FetchToken 36, 46, 47 Fettschrift 22 Final Value Fee 27 flat shipping 20 FVF 27
INR 27, 66 international shipping 69 Item 18 Item Not Received Dispute 27 ItemID 23, 87
Heribert Varli 37 Hinterlassen von Bewertungen 26
J Java 42
G Galeriebild 23 GalleryFeatured 22 GetAttributesCS 53 GetAttributesXSL 54 GetCategories 53, 88 GetCategoryFeatures 53 GetCategoryListings 65 GetCategoryMappings 53 GeteBayDetails 54, 70 GeteBayOfficalTime 54 GetFeedback 64 GetItem 65 GetItemsAwaitingFeedback 64 GetItemTransactions 63, 84 GetItFast 29 GetMyeBaySelling 63 GetOrder 64 GetRuName 45 GetSearchResults 64, 79 GetSearchResultsExpress 65 GetSellerEvents 63 GetSellerTransactions 51, 63, 84 GMT 51 Granularity Level 50
108
K Kataloge 70 Kategorie 19
L LeaveFeedback 64, 87 Listen 18 Listingfees 27 ListingType 19 lot 22
M Menge 21 MyMessages 62
N NowAndNew 29
O Order 26, 64
P Paginierung 51, 63 PayPal 21 PHP 42 Accelerator Toolkit 42
Stichwortverzeichnis
PictureDetails 74 Power-Auktion 19 Production 33
SofortKauf-Option 18 SYI 18
T R Rahmen 22 Real Estate Ad 24 Region 54 Registrierungsadresse 25 Relist 61 RelistItem 61 Research-API 14 REST 43 ReviseItem 24 Rückgaberecht 20, 73 RuName 36, 45
Token 35, 56 Tool 12 TransactionID 87 Transaktion 24 Turbolister 18
U Unpaid Item Dispute 27 Untertitel 22 UPI 27, 66 UTC 51
V S Sandbox 33 User Registration Tool 37 SDK 39 SecondChance 28, 61 SecretID 46 Selbstzertifizierung 34 SellYourItem 18 SendInvoice 86 SetNotificationPreferences 49 SetPromotionRules 60 SetReturnURL 45 ShipToLocation 70 Shop-Artikel 18 SideWide CsSet 20, 73 Site-ID 32 SOAP 40 Sofort und Neu 29
schnell + kompakt
VerifyAddItem 60 VerifyAddSecondChanceItem 61 Verkaufsabwicklung 25, 62 Extern 26 Versandadresse 25 Versandkosten 20 Versandoption 54, 70 Versionierung 32
W WantItNow 29 Web 2.0 13
Z Zahlungsbedingungen 21 Zahlungsmethode 21, 54 Zertifizierung 34
109
