VERSION 1.7 - idealo Blog

Transcription

WEBSERVICE
ANGEBOTSAKTUALISIERUNG
VERSION 1.7
idealo internet GmbH | HRB 76749 - Amtsgericht Charlottenburg
Geschäftsführer: Dr. Albrecht von Sonntag, Dr. Philipp-Christopher Peitsch
Ritterstraße 11 | 10969 Berlin | Tel.: +49 30 403 010 - 33 | Fax: +49 30 319 89 25 - 02 | [email protected] | www.idealo.de
Inhaltsverzeichnis
1.Allgemeines................................................................................................................3
2. updateOffers..............................................................................................................3
2.1. Beispiele.............................................................................................................4
2.2. Beschreibung der XML Elemente und Attribute der Anfrage.............................7
offers.offer.............................................................................................................7
offers.updateTimestamp.......................................................................................7
offers.testMode.....................................................................................................7
offers.offer.command............................................................................................7
offers.offer.sku.......................................................................................................8
offers.offer.revision................................................................................................8
offers.offer.title.......................................................................................................8
offers.offer.productTitle.........................................................................................8
offers.offer.url........................................................................................................9
offers.offer.delivery................................................................................................9
offers.offer.price....................................................................................................9
offers.offer.basePrice............................................................................................9
offers.offer.listPrice................................................................................................9
offers.offer.attributes...........................................................................................10
offers.offer.image................................................................................................10
offers.offer.shipping.............................................................................................10
offers.offer.shippingComment.............................................................................11
offers.offer.category.............................................................................................11
offers.offer.brand.................................................................................................11
offers.offer.oen....................................................................................................11
offers.offer.formerPrices......................................................................................12
offers.offer.deposits.............................................................................................12
offers.offer.ean....................................................................................................12
offers.offer.han....................................................................................................13
offers.offer.pzn....................................................................................................13
offers.offer.description.........................................................................................13
offers.offer.merchant...........................................................................................13
offers.offer.used..................................................................................................13
offers.offer.rebuild...............................................................................................14
offers.offer.contract.............................................................................................14
offers.offer.downloadable....................................................................................14
offers.offer.expireDate.........................................................................................14
offers.offer.voucherCode.....................................................................................14
offers.offer.eCommerce......................................................................................15
offers.offer.eCommerce.checkoutApproved.......................................................15
Offers.offer.eCommerce.checkoutLimit..............................................................16
Offers.offer.eCommerce.fulfillmenttype..............................................................16
Offers.offer.eCommerce.fulfillmentOptions.........................................................16
Offers.offer.eCommerce.fulfillmentOptions.twoManHandling.............................16
Offers.offer.eCommerce.fulfillmentOptions.disposal..........................................17
2.3. Attribute der Angebotselemente:......................................................................18
context (verschiedene Angebotselemente)........................................................18
type (Angebotselement shipping).......................................................................18
2.4. Die Antwort des updateOffers - Webservice....................................................20
1 / 29
2.5. Beschreibung der XML Elemente und Attribute der Antwort...........................21
offerResponses.error..........................................................................................21
offerResponses.offerResponse.id......................................................................21
offerResponses.offerResponse.sku....................................................................21
offerResponses.offerResponse.status................................................................21
offerResponses.offerResponse.statusMsg.........................................................22
3. getOffers..................................................................................................................22
3.1 Beschreibung der XML Elemente und Attribute der Antwort............................25
offers.offer...........................................................................................................25
offers.offer.sku.....................................................................................................25
offers.offer.revision..............................................................................................25
4. Notes.......................................................................................................................26
Version 1.7..............................................................................................................28
Version 1.6..............................................................................................................28
Version 1.5..............................................................................................................28
Version 1.4..............................................................................................................28
Version 1.3..............................................................................................................29
Version 1.2..............................................................................................................29
Version 1.1..............................................................................................................29
2 / 29
1. Allgemeines
idealo stellt Ihnen zwei Webservices zur Verfügung, mit denen Sie die Daten Ihrer Angebote in
Echtzeit aktualisieren (updateOffers), sowie Ihre aktuell an idealo übermittelten Angebote abrufen
können (getOffers).
Für die Nutzung der Webservices müssen Sie von idealo freigeschaltet werden. Hierfür wenden Sie
sich bitte an [email protected]
Die Webservices können über HTTPS mit verschiedenen Programmiersprachen benutzt werden. Eine
beispielhafte Implementierung für Perl und PHP finden Sie im folgenden Abschnitt. Implementierungen
in anderen Programmiersprachen sind ebenfalls einfach zu realisieren.
Eine Liste der Änderungen gegenüber der letzten API-Version finden Sie am Ende dieses Dokuments.
2. updateOffers
Zur Aktualisierung Ihrer Angebote wird an den Webservice ein HTTP-Request mit POST-Daten im
XML-Format gesendet. Dieses XML beinhaltet eine Liste von Angeboten. Jedem dieser Angebote
kann ein Kommando zum Hinzufügen, Ändern oder Löschen mitgegeben werden. Sobald der
Webservice antwortet und für das Angebot der Status OK zurückgeliefert wurde, ist die Änderung
erfolgreich an idealo übermittelt worden. Wird hingegen der Status FAILED zurückgeliefert, konnte das
Angebot nicht korrekt verarbeitet werden. Die Rückgabe des Status OK bedeutet allerdings nicht, dass
die Änderung(en) sofort auf idealo sichtbar werden. Dies geschieht in Abhängigkeit des Kommandos
ggf. erst nach weiteren Bearbeitungsschritten durch das System.
Als Zeitpunkt der letzten Aktualisierung wird immer der Zeitpunkt der letzten erfolgreichen
Webserviceanfrage angegeben, sofern beim Webservice-Aufruf nichts anderes angegeben wurde.
Dies bedeutet, dass idealo davon ausgeht, dass mit dem letzten Request alle Änderungen im Shop an
idealo übergeben wurden. Bei allen Angeboten Ihres Shops wird dann auf idealo der Zeitstempel
dieses letzten Requests angezeigt. Bitte stellen Sie deshalb sicher, dass Sie uns stets alle
Änderungen übermitteln.
Übermitteln Sie uns 3 Tage lang keine Requests, werden Ihre Angebote automatisch auf idealo
deaktiviert.
updateOffers wird über HTTPS aufgerufen:
https://partner.idealo.de/partnerWs/v1/updateOffers
Zur Authentifizierung muss Basic-Authentication verwendet werden. Hierfür benötigen Sie einen Benutzernamen und ein Passwort. Darüber hinaus müssen Sie die Ihnen von idealo vergebene sogenannte shopId als Header-Attribut übermitteln.
Wichtiges zum Thema Encoding: Bitte geben Sie, wenn Sie einen Request stellen, unbedingt das
Encoding im entsprechenden Header-Feld an. Beispielsweise:
Content-Type: application/xml; charset=utf-8
Sie können hier unterschiedliche Encodings angeben (z.B. UTF-8, ISO-8859-1, ISO-8859-15). Das
Encoding muss dem Encoding des XMLs entsprechen. Wie empfehlen Ihnen UTF-8 zu verwenden
(siehe auch Programmierbeispiele auf den folgenden Seiten).
3 / 29
2.1. Beispiele
Beispielimplementation (PHP)
$url = "https://partner.idealo.de/partnerWs/v1/updateOffers";
$xml = '<?xml version="1.0" encoding="UTF-8"?><offers> ... </offers>';
$header = array(
'shopId: 12345',
'Content-Type: application/xml; charset=utf-8',
'Expect:'.''
);
$process = curl_init($url);
curl_setopt($process, CURLOPT_HTTPHEADER, $header);
curl_setopt($process, CURLOPT_USERPWD, '[email protected]:geheimesPasswort');
curl_setopt($process, CURLOPT_TIMEOUT, 30);
curl_setopt($process, CURLOPT_POST, TRUE);
curl_setopt($process, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($process, CURLOPT_POSTFIELDS, $xml);
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
print_r($return);
4 / 29
Beispielimplementation (Perl)
#!/usr/bin/env perl
use strict;
use warnings;
use LWP::UserAgent;
use LWP::Protocol::https;
use HTTP::Request;
my $user = '[email protected]';
my $pass = 'geheimesPasswort';
my $shop = '12345';
my $method = 'POST';
my $url = 'https://partner.idealo.de/partnerWs/v1/updateOffers';
my $response = make_request();
process_response($response);
sub make_request {
my $ua = get_user_agent();
my $request = get_request();
return $ua->request($request);
}
sub get_user_agent {
my $ua = LWP::UserAgent->new;
$ua->agent( 'Idealo Partner WebService Client / libwww-perl' );
return $ua;
}
sub get_request {
my $request = HTTP::Request->new( $method => $url );
$request->authorization_basic($user, $pass);
$request->header('Content-Type' => 'application/xml; charset=utf-8');
$request->header('shopId' => $shop);
$request->content('<?xml version="1.0" encoding="UTF-8"?><offers> ... </offers>');
return $request;
}
sub process_response {
my ($response) = @_;
if ($response->is_success()) {
print $response->decoded_content . "\n";
} else {
print "Unsuccessful: " . $response->status_line . "\n";
5 / 29
}
return 1;
}
Beispiel (Anfrage)
XML mit Angebotsdaten
Der Body der Anfrage enthält XML-Elemente mit bis zu 100 Angeboten und/oder einen Zeitstempel
zum Setzen des Aktualisierungszeitpunkts.
<?xml version="1.0" encoding="UTF-8"?>
<offers>
<offer>
<command>UPDATE</command>
<sku>ABC123</sku>
<price context="DE">22.99</price>
</offer>
<offer>
<command>INSERT</command>
<sku>ABC234</sku>
<title>Casio Exilim 50D</title>
<url context="DE">http://www.shop.de/ABC234.html</url>
<delivery>1-2 Tage</delivery>
<price>225.99</price>
<image>htp://www.shop.de/angebotsbildABC123.png</image>
<shipping context="DE" type="CREDITCARD">2.99</shipping>
<shipping context="DE" type="COD">5.99</shipping>
<shippingComment>Abholung möglich</shippingComment>
<category><![CDATA[Unterhaltungselektronik > Digitalkameras]]></category>
<brand>Casio</brand>
<ean>247395875646</ean>
<description>Digitalkamera mit 8 Megapixel</description>
</offer>
<offer>
<command>DELETE</command>
<sku>ABC567</sku>
</offer>
</offers>
6 / 29
2.2. Beschreibung der XML Elemente und Attribute der Anfrage
Die erlaubten XML-Elemente werden im Folgenden beschrieben:
offers.offer
erlaubte Werte
Beschreibung
Beispiel
(optional) XML-Element, kann mehrfach enthalten sein
Beinhaltet die Daten für ein Angebot
-
offers.updateTimestamp
erlaubte Werte
(optional) Zeitstempel
Beschreibung
setzt den im Preisvergleich angezeigten Zeitpunkt „letzte Aktualisierung“
nach erfolgtem Import der Angebote auf den übergebenen Zeitpunkt. Wird
kein Zeitstempel übergeben, so wird der Zeitpunkt des Webserviceaufrufs
angenommen.
Beispiel
2015-02-06T12:44:22
offers.testMode
erlaubte Werte
(optional) Boolean (true/false)
Beschreibung
falls gesetzt (true), wird die Anfrage nur auf Gültigkeit geprüft, aber nicht
tatsächlich ausgeführt.
Beispiel
false
offers.offer.command
erlaubte Werte
Insert, Update, Replace, Delete, InsertOrReplace
Beschreibung
bestimmt, welche Aktion mit dem Angebot durchgeführt wird
Beispiel
Delete
Werte:
Insert
Update
Replace
InsertOrReplace
Delete
Ein neues Angebot wird mit den Daten aus der Anfrage erzeugt. Falls die
SKU bereits vergeben ist, wird eine Fehlermeldung zurückgeliefert.
Aktualisiert bei dem Angebot mit der übergebenen SKU alle ebenfalls
übergebenen Angebotseigenschaften. Nicht übergebene Eigenschaften
bleiben unverändert. Mit Update können derzeit keine Angebote komplett
gelöscht werden, hierzu ist Replace notwendig.
Ersetzt das Angebot mit der übergebenen SKU durch ein neues Angebot
mit den Daten im XML. Falls noch kein Angebot mit der SKU existiert, wird
eine Fehlermeldung zurückgeliefert.
Ersetzt das Angebot mit der übergebenen SKU durch ein neues Angebot
mit den Daten im XML. Falls noch kein Angebot mit der SKU existiert, wird
ein neues Angebot mit den übergebenen Daten erzeugt
Löscht das Angebot mit der übergebenen SKU.
7 / 29
offers.offer.sku
erlaubte Werte
Zeichenkette bestehend aus Buchstaben und Zahlen, max. 20 Zeichen
* Verwenden Sie nur die Zeichen a-z, A-Z, 0-9.
Beschreibung
eindeutiger Bezeichner eines Angebots, welcher von Ihnen frei gewählt
werden kann
Beispiel
AB1234
offers.offer.revision
erlaubte Werte
(optional) Zeichenkette bestehend aus Buchstaben und Zahlen, max.
20 Zeichen
Beschreibung
eindeutiger Bezeichner der Version des Angebots, welcher von Ihnen
frei gewählt werden kann.
Beispiel
20100701ab1255
offers.offer.title
erlaubte Werte
Zeichenkette, max. 150 Zeichen
Beschreibung
Bezeichnung des Angebots, wird im Preisvergleich angezeigt.
* Beachten Sie: Zeichen wie "<" und "&" sind nicht valide in XML
Elementen. Falls Sie sie unbedingt benötigen, umschließen Sie sie mit
CDATA. (siehe Beispiel 2).
Beispiel 1
Nintendo Wii (schwarz)
Beispiel 2
<![CDATA[Nintendo Wii (schwarz & weiß)]]>
offers.offer.productTitle
erlaubte Werte
(optional) Zeichenkette, max. 150 Zeichen
Beschreibung
Hier kann eine für die automatische Produktzuordnung optimierte
Produktbezeichnung übergeben werden. Diese enthält optimalerweise
nur eine reduzierte Bezeichnung des Shopangebots ohne Zusätze wie
Grundpreise, techn. Daten, Zertifikate, Hinweise auf Shopaktionen oder
Garantieangaben, welche die Produktzuordnung erschweren würden.
Der Inhalt dieses Feldes wird nicht im Preisvergleich angezeigt. Falls
Ihre Angebotstitel keine zusätzlichen Informationen enthalten, muss die
Information nicht übergeben werden.
Beispiel 1
Nintendo Wii (schwarz)
Beispiel 2
<![CDATA[Nintendo Wii (schwarz & weiß)]]>
8 / 29
offers.offer.url
erlaubte Werte
Beschreibung
URL zur Angebotsseite im Shop
Beispiel
http://www.redcoon.de/index.php/cmd/shop/a/ProductDetail/pid/B17038
8/cid/20018/refId/idealo/
Attribute
context (optional)
offers.offer.delivery
erlaubte Werte
Beschreibung
Lieferzeit des Angebots
Beispiel
Sofort lieferbar
Attribute
context (optional)
offers.offer.price
erlaubte Werte
positiver Zahlenwert
Beschreibung
Preis des Angebots in Euro
Beispiel
189.00
Attribute
context (optional)
offers.offer.basePrice
erlaubte Werte
(optional) positiver Zahlenwert
Beschreibung
Grundpreis
Beispiel
<basePrice measure=“100“ unit=“ml“>0.99</basePrice>
bedeutet: 0.99 EUR / 100ml
Attribute
context (optional), measure (erforderlich), unit (erforderlich)
offers.offer.listPrice
erlaubte Werte
(optional) positiver Zahlenwert
Beschreibung
Listenpreis für ein Produkt
Beispiel
<listPrice context="DE">5.99</listPrice>
Attribute
context (optional)
9 / 29
offers.offer.attributes
erlaubte Werte
name: Zeichenkette, max. 100 Zeichen, nur Buchstaben, Zahlen und
„-“ erlaubt.
value: Zeichenkette, max. 250 Zeichen
Beschreibung
Attribute für ein Produkt
Beispiel 1
<attributes>
<attribute name=“SIZE“>
<value>XL</value>
</attribute>
<attribute name="COLOR">
<value>rot</value>
<value>blau</value>
</attribute>
</attributes>
Beispiel 2
<attributes>
<attribute name="BRAND">
<value><![CDATA[Bang & Olufsen]]></value>
</attribute>
</attributes>
Attribute
name (erforderlich)
offers.offer.image
erlaubte Werte
Beschreibung
URL zum Angebotsbild im Shop
Beispiel
http://ecx.images-amazon.com/images/I/41I0uyRkd2L._AA280_.jpg
Attribute
context (optional)
offers.offer.shipping
erlaubte Werte
(optional) Zahlenwert, nicht negativ
Beschreibung
Versandkosten für die angegebene Zahlungs-/Versandart
Beispiel
2.90
Attribute
context (optional), type (erforderlich)
10 / 29
offers.offer.shippingComment
erlaubte Werte
Beschreibung
Beschreibung: Kommentar zum Artikelversand oder zu Zahlungsweisen
Beispiel 1
Abholung in 10119 Berlin möglich
Beispiel 2
<![CDATA[Abholung in Berlin & Brandenburg möglich]]>
Attribute
context (optional)
offers.offer.category
erlaubte Werte
Beschreibung
frei wählbare Kategoriebezeichnung, welche die Produktgruppe
beschreibt. Hier möglichst keine Hersteller-und Modellbezeichnungen
verwenden.
Beispiel 2
Spiele | Sony | Playstation 3
Beispiel 2
<![CDATA[MP3-Downlo ads > MP3-Alben > Schlager & Volksmusik]]>
offers.offer.brand
erlaubte Werte
Beschreibung
Hersteller des Produktes, verbessert die Zuordnung zum
Produktkatalog
Beispiel 1
Canon
Beispiel 2
<![CDATA[Bang & Olufsen]]>
offers.offer.oen
erlaubte Werte
Beschreibung
(optional) Zahlenwert
Original Ersatzteil Nummer besteht aus dem Herstellerkürzel und dem
Identifier-Code mit Komma getrennt
Beispiel
<oen>
<oenValues>VW,123 615 301</oenValues>
<oenValues>XY,123 456 789</oenValues>
</oen>
offers.offer.kba
11 / 29
erlaubte Werte
Beschreibung
Kraftfahrt-Bundesamt Nummer besteht aus den 4 Ziffern der
Herstellerschluesselnummer (HSN) und den ersten 3 Zeichen der
Typschluesselnummer (TSN)
Beispiel
<kba>
<kbaValues>0600ABC</kbaValues>
<kbaValues>0600920</kbaValues>
<kbaValues>0600AH7</kbaValues>
</kba>
offers.offer.formerPrices
erlaubte Werte
(optional) Zeichenkette
Beschreibung
Sogenannte Streichpreise sind ehemalige Verkaufspreise. Wird
benutzt, um die Differenz zum aktuellen Verkaufspreis darzustellen.
Beispiel
<formerPrices>
<formerPrice context=“DE“>4.99</formerPrice>
<formerPrice context=“FR“>5.19</formerPrice>
</formerPrices>
Attribute
offers.offer.deposits
erlaubte Werte
Beschreibung
context (optional)
Pfandwert, Dezimalzahl, gerundet auf 2 Nachkommastellen
Beispiel
<deposits>
<deposit context=“DE“>4.99</deposit>
<deposit context=“FR“>5.19</deposit>
</deposits>
Attribute
context (optional)
offers.offer.ean
erlaubte Werte
Beschreibung
EAN/GTIN des Angebots, verbessert die Zuordnung zum
Produktkatalog
ISBN-Nummern können ebenfalls hier übergeben werden
Beispiel
45496342067
12 / 29
offers.offer.han
erlaubte Werte
Beschreibung
Von Hersteller vergebene Artikelnummer, verbessert die Zuordnung
zum Produktkatalog
Beispiel
DMC-TZ10EB-K
offers.offer.pzn
erlaubte Werte
Beschreibung
PZN des Angebots (nur bei Apothekenangeboten), verbessert die
Zuordnung zum Produktkatalog
Beispiel
458532
offers.offer.description
erlaubte Werte
Beschreibung
Beschreibung des Angebots, verbessert die Zuordnung zum
Produktkatalog und wird im Preisvergleich angezeigt
Beispiel 1
Digital Foto DMC TZ 10 Digitalkamera mit 12.1 Mio. Pixeln Optischer
Zoom 23,4 facher Optischer Bildstabilisator
Beispiel 2
<![CDATA[Bang & Olufsen Kopfhörer A8 (schwarz)]]>
offers.offer.merchant
erlaubte Werte
Beschreibung
Name des Verkäufers (bei Wiederverkäufern oder Marktplatzhändlern)
Beispiel
Attribute
<merchant id=“0001“>megaSeller</merchant>
id (optional)
offers.offer.used
erlaubte Werte
Beschreibung
Markiert Angebote, welche nicht neu sind (z.B. Retouren,
Vorführprodukte, geöffnete Verpackung, ...)
Beispiel
true
13 / 29
offers.offer.rebuild
erlaubte Werte
Beschreibung
Markiert Angebote, welche ein Nachbau von Produkten anderer
Hersteller sind. Die Markierung ist notwendig, wenn das Originalprodukt
im Angebotstitel vorkommt (z.B. "Qualitätsakku kompatibel zu Canon
HK-2222")
Beispiel
true
offers.offer.contract
erlaubte Werte
Beschreibung
Markiert Angebote, welche nur durch Abschluss eines Vertrages
erworben werden können (z.B. Handys)
Beispiel
true
offers.offer.downloadable
erlaubte Werte
Beschreibung
Markiert Angebote, welche nur per Download erworben werden können
(z.B. Computerspiele)
Beispiel
true
offers.offer.expireDate
erlaubte Werte
(optional) Zeitstempel
Beschreibung
bestimmt ein Ablaufdatum für ein Angebot. Sobald das Datum erreicht
ist, wird das Angebot ausgeblendet.
Beispiel
2010-04-23T15:41:21
offers.offer.voucherCode
erlaubte Werte
Beschreibung
GutscheinCode mit Beschreibung. Bitte unbedingt die Struktur des
Beispiels einhalten → CODE (Beschreibung)
Beispiel
AKTION2013 (10 % Rabatt ab 200 EUR Einkaufswert / gültig bis
31.12.2011).
Attribute
context (optional)
14 / 29
offers.offer.eCommerce
erlaubte Elemente
offers.offer.eCommerce.checkoutApproved,
offers.offer.eCommerce.checkoutLimitPerPeriod,
offers.offer.eCommerce.fulfillmenttype,
offers.offer.eCommerce.fulfillmentOptions
Beschreibung
Wenn Sie Angebote über den idealo-Direktkauf vertreiben wollen, können
Sie Ihre Bedingungen übermitteln. Bitte beachten Sie: zur Zeit (Stand März
2016) ist der Direktkauf nur auf idealo.de verfügbar.
Beispiel
<eCommerce>
<checkoutApproved>true</checkoutApproved>
<checkoutApproved context="FR">true</checkoutApproved>
<checkoutLimitPerPeriod
context="DE">1</checkoutLimitPerPeriod>
<checkoutLimitPerPeriod
context="FR">11</checkoutLimitPerPeriod>
<fulfillmenttype context="DE">Spedition</fulfillmenttype>
<fulfillmentOptions context="DE">
<disposal price="15" />
<twoManHandling price="49.9" />
</fulfillmentOptions>
<fulfillmentOptions context="FR">
<fulfillmentOptions context="AT">
<fulfillmenttype context="FR">Paketdienst</fulfillmenttype>
<checkoutApproved context="AT">false</checkoutApproved>
</eCommerce>
true
optional
offers.offer.eCommerce.checkoutApproved
erlaubte Werte
Boolean (true/false)
Beschreibung
Hiermit geben Sie ein Angebot im Feed für den Direktkauf frei. Nur für
Angebote, die über dieses Datenfeld freigegeben werden, kann im idealo
Direktkauf ein Kaufvorgang gestartet werden. Lassen Sie dieses
Datenfeld weg, gilt das Angebot als nicht freigegeben.
Beispiel
<checkoutApproved context="FR">true</checkoutApproved>
Attribute
context (optional)
optional
true
Offers.offer.eCommerce.checkoutLimit
erlaubte Werte
Positive ganze Zahl
Beschreibung
Hier können Sie idealo den Lagerbestand des Angebots angeben. Dies
15 / 29
Beispiel
Attribute
optional
ist insbesondere bei begrenzten Sonderangeboten sinnvoll oder wenn sie
eine größere Stückzahl eines Artikels in einem Checkout-Vorgang
verkaufen wollen. Bei gesetztem Wert stellt idealo sicher, dass nicht mehr
Angebote verkauft werden, als Sie verfügbar haben. Ohne diese Angabe
bleibt das Angebot im Direktkauf verfügbar, bis das Angebot entweder
gelöscht wird oder über "checkoutApproved" die Freigabe für den
Direktkauf zurückgezogen wird. idealo empfiehlt im Kunden- und
Händlerinteresse, dieses Feld bei allen Angeboten zu setzen.
<checkoutLimitPerPeriod context="FR">11</checkoutLimitPerPeriod>
context (optional)
true
Offers.offer.eCommerce.fulfillmenttype
erlaubte Werte
Zeichenkette
Beschreibung
Geben Sie als Lieferart "Spedition" an, wird beim Verkauf der
entsprechenden Artikel die Telefonnummer des Käufers zur Abstimmung
eines Liefertermins mit dem beauftragten Speditionsunternehmen erfragt.
Nur für Artikel mit der Lieferart "Spedition" können die im folgenden
genannten Zusatzoptionen im idealo Direktkauf angeboten werden.
Lassen Sie dieses Datenfeld weg, wird als Lieferart "Paketdienst"
angenommen.
Beispiel
<fulfillmenttype context="DE">spedition</fulfillmenttype>
Attribute
context (optional)
optional
true
Offers.offer.eCommerce.fulfillmentOptions
erlaubte Elemente
offers.offer.eCommerce.fulfillmentOptions.twoManHandling,
offers.offer.eCommerce.fulfillmentOptions.disposal
Beschreibung
Kosten für zusätzliche Optionen bei Speditionsware
Beispiel
<fulfillmentOptions context="AT">
Attribute
context (optional)
optional
true
Offers.offer.eCommerce.fulfillmentOptions.twoManHandling
erlaubte Werte
Beschreibung
Für Artikel mit der Lieferart "Spedition" kann im idealo Direktkauf vom
Käufer die zusätzliche Dienstleistung "Zwei-Mann-Lieferung bis zu
Aufstellort" bestellt werden. Für Angebote, bei denen Sie die Zwei-MannLieferung anbieten wollen, geben Sie mit diesem Datenfeld den Preis
incl. MwSt. an, der zusätzlich zum Artikelpreis und den Grundkosten für
die Speditionslieferung erhoben werden soll. Lassen Sie dieses
Datenfeld weg, wird die Dienstleistung "Zwei-Mann-Lieferung" im
Checkout des idealo Direktkauf nicht angeboten.
Beispiel
Attribute
price (Preis in EUR)
optional
false
16 / 29
Offers.offer.eCommerce.fulfillmentOptions.disposal
erlaubte Werte
Beschreibung
Für Artikel mit der Lieferart "Spedition" kann im idealo Direktkauf vom
Käufer die zusätzliche Dienstleistung "Altegeräteabholung" bestellt
werden. Für Angebote, bei denen Sie die Altgeräteabholung anbieten
wollen, geben Sie mit diesem Datenfeld den Preis incl. MwSt. an, der
zusätzlich zum Artikelpreis, den Grundkosten für die Speditionslieferung
und den Kosten für die Zwei-Mann-Lieferung erhoben werden soll.
Lassen Sie dieses Datenfeld weg, wird die Dienstleistung
"Altgeräteabholung" im Checkout des idealo Direktkauf nicht angeboten.
Die Altgeräteabholung kann nur in Kombination mit der Zwei-MannLieferung angeboten werden.
Beispiel
Attribute
price (Preis in EUR)
optional
true
17 / 29
2.3. Attribute der Angebotselemente:
context (verschiedene Angebotselemente)
erlaubte Werte
DE, AT, UK, FR, IT, ES, PL, IN
Beschreibung
schränkt den Gültigkeitsbereich einer Information ein (z.B.
Versandkosten, Lieferzeit), falls ihr Shop auf mehr als einem Land bei
idealo freigeschaltet ist. Informationen ohne optionales context-Attribut
sind für alle Länder gültig.
Beispiel
DE
Werte:
DE
Deutschland (idealo.de)
AT
Österreich (idealo.at)
UK
England (idealo.co.uk)
FR
Frankreich (idealo.fr)
IT
Italien (idealo.it)
ES
Spanien (idealo.es)
PL
Polen (idealo.pl)
IN
Indien (idealo.in)
type (Angebotselement shipping)
erlaubte Werte
PREPAID, COD, DIRECTDEBIT, PAYPAL, INVOICE, CREDITCARD,
SOFORTUEBERWEISUNG, GIROPAY, MONEYBOOKERS,
CLICKANDBUY, PAYSAFECARD, GOOGLECHECKOUT,
POSTALORDER, EPS, ICLEAR
Beschreibung
bestimmt, für welche Zahlungs-/Versandart der übergebene Preis gültig
ist. Eine Kombination mit dem context-Attribut ist möglich.
Beispiel
CREDITCARD
Werte:
PREPAID
Vorkasse / Vorabüberweisung
COD
Zahlung bei Lieferung (Nachnahme)
DIRECTDEBIT
Lastschrift / Bankeinzug
PAYPAL
Paypal
INVOICE
Zahlung nach Erhalt einer Rechnung
CREDITCARD
Kreditkarte (direkt, nicht über PayPal o.ä.)
SOFORTUEBERWEIS
UNG
Sofortüberweisung
GIROPAY
http://www.giropay.de/
MONEYBOOKERS
http://www.moneybookers.com/app/
CLICKANDBUY
http://www.clickandbuy.com/DE_de/bezahlen/
PAYSAFECARD
http://www.paysafecard.com/de/
18 / 29
GOOGLECHECKOUT
http://checkout.google.com/support/?hl=de
POSTALORDER
Postüberweisung
EPS
e-payment standard (Österreich)
ICLEAR
https://www.iclear.de/
19 / 29
2.4. Die Antwort des updateOffers - Webservice
Das Aktualisieren Ihrer Angebotsdaten per updateOffers wird mittels XML quittiert. Anhand der XMLANTWORT lässt sich für jedes Angebot das Ergebnis der Verarbeitung bei idealo auswerten.
Bitte beachten Sie, dass der Webservice erst nach der Verarbeitung der Angebote bei idealo
antwortet. Dies hängt unter anderem davon ab, wie viel Angebote in der Anfrage enthalten waren. Wir empfehlen in Ihrer Applikation einen Timeout von 2 Sekunden pro Angebot einzuplanen.
Beispiel (Antwort):
<?xml version="1.0" encoding="UTF-8"?>
<offerResponses>
<offerResponse>
<id>357985368</id>
<sku>ABC123</sku>
<status>OK</status>
<statusMsg/>
</offerResponse>
<offerResponse>
<id>3579898369</id>
<sku>ABC234</sku>
<status>FAILED</status>
<statusMsg>Invalid Content for Attribute: image</statusMsg>
</offerResponse>
<offerResponse>
<id>35798983610</id>
<sku>ABC2345</sku>
<status>IGNORED</status>
<statusMsg>There is nothing to update</statusMsg>
</offerResponse>
<offerResponse>
<id>35798983611</id>
<sku>ABC23456</sku>
<status>IGNORED</status>
<statusMsg>Failed to deactivate Offer with sku 17450651. No offer with given sku
found.
</statusMsg>
</offerResponse>
<offerResponse>
<id>35798983612</id>
<sku>ABC23457</sku>
<status>FILTERED</status>
<statusMsg>FILTERED</statusMsg>
</offerResponse>
</offerResponses>
Erläuterung der Antwort-XML:
20 / 29





Das erste Angebot ist erfolgreich verarbeitet worden.
Das zweite Angebot schlug fehl wegen ungültiger Bild-Url (image-url).
Das dritte Angebot wurde ignoriert, da alle Daten bereits aktuell waren.
Das vierte Angebot konnte nicht gelöscht werden, da es gar nicht existierte
(deshalb IGNORED).
Das fünfte Angebot wurde gefiltert, weil beispielsweise der Verkäufer auf idealo gesperrt ist.
2.5. Beschreibung der XML Elemente und Attribute der Antwort
offerResponses.error
Beschreibung
Generelle Fehler, die den ganzen Request betreffen.
Attributes
message: Eine kurze Beschreibung des Fehlers.
code: Request error code z.b. 400, 403, 404, 500,511,512
Beispiel
<error>
<message>UpdateTimestamp is older than 10 days.</message>
<code>512</code>
</error>
offerResponses.offerResponse.id
Beschreibung
ID von dem Angebot.
Beispiel
1037481673
offerResponses.offerResponse.sku
Beschreibung
SKU von dem Angebot, wie vom Shop geliefert.
Beispiel
198430791
offerResponses.offerResponse.status
Beschreibung
Ergebnis des Verarbeitens durch den WebService.
Beispiel
OK
Werte:
OK
Alles okay.
IGNORED
Request wäre nicht notwendig gewesen. Dies kann vorkommen falls:

versucht wird, etwas zu löschen, was bei idealo bereits gelöscht ist.

die Angebotsdaten bereits genauso bei idealo vorhanden sind.

das Angebot innerhalb derselben Anfrage mehrfach vorhanden ist.
FILTERED
Angebot wurde gefiltert, also gelöscht. Dies kann folgende Ursachen
haben:

Das Angebot enthält Wörter oder Begriffe, die aus
rechtlichen oder idealo-internen Gründen gesperrt sind.
21 / 29

FAILED
Bei Marktplatz Shops ist der Verkäufer gesperrt.
Fehler liegt vor. Entweder stimmt etwas mit dem geschickten XML
nicht, oder es liegt ein internes Problem vor.
offerResponses.offerResponse.statusMsg
Beschreibung
Eine kurze Beschreibung des Fehlers.
A brief command execution status message.
Beispiel 1
There is nothing to update (IGNORED)
Beispiel 2
Failed to deactivate Offer with sku XXXXXXX. No offer with given sku
found. (IGNORED)
Beispiel 3
Offer with sku: XXXXX. When using command Insert or Replace a title
is necessary! (FAILED)
3. getOffers
Mit dem Webservice getOffers sind Sie in der Lage, Ihre derzeit an uns übermittelten Angebote abzufragen. Falls Sie die Verwendung des updateOffers Webservices vorübergehend ausgesetzt haben
oder hierbei Probleme aufgetreten sind, können Sie mit geringem Aufwand die Angebotsliste in Ihrer
Datenbank mit der bei uns hinterlegten Angebotsliste vergleichen und Änderungen ggf. nachreichen.
getOffers wird über HTTPS aufgerufen:
https://partner.idealo.de/partnerWs/v1/getOffers?pageNumber=1&pageSize=10
Zur Authentifizierung muss Basic-Authentication verwendet werden. Hierfür benötigen Sie einen Benutzernamen und ein Passwort. Darüber hinaus müssen Sie die Ihnen von idealo vergebene sogenannte shopId als Header-Attribut übermitteln.
Bitte beachten Sie, dass es einige Zeit dauern kann bis der Webservice antwortet. Dies kann
vorkommen, wenn Sie als pageSize-Parameter beispielsweise 10000 gewählt haben.
Anfrage-Parameter:
pageSize (Get-Parameter)
Anzahl der Angebote, welche pro Aufruf zurückgeliefert werden sollen. Es werden maximal 10000 Angebote pro Aufruf zurückgeliefert. Größere Werte für den pageSize-Parameter sind nicht zulässig.
PageNumber (Get-Parameter)
22 / 29
Falls auf Grund Ihrer Angebotsanzahl nicht alle Angebote innerhalb einer Anfrage zurückgeliefert werden können, können Sie hiermit die Seite angeben, die zurückgeliefert werden soll. Erlaubt sind Zahlenwerte >= 1.
Beispiel (Anfrage)
https://partner.idealo.de/partnerWs/v1/getOffers?pageNumber=1&pageSize=4
23 / 29
Beispiel (Antwort):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<offers>
<offer>
<sku>ABC123</sku>
</offer>
<offer>
<sku>ABC234</sku>
<revision>2010-09-02 11:59:59.808</revision>
</offer>
<offer>
<sku>ABC235</sku>
</offer>
<offer>
<sku>ABC444</sku>
</offer>
</offers>
24 / 29
3.1 Beschreibung der XML Elemente und Attribute der Antwort
offers.offer
erlaubte Werte
(optional) XML-Element, kann mehrfach enthalten sein
Beschreibung
Beinhaltet die Daten für ein Angebot
Beispiel
-
offers.offer.sku
erlaubte Werte
Zeichenkette bestehend aus Buchstaben und Zahlen, max. 20 Zeichen
* Verwenden Sie nur die Zeichen a-z, A-Z, 0-9.
Beschreibung
eindeutiger Bezeichner eines Angebots, welcher von Ihnen frei gewählt
werden kann
Beispiel
AB1234
offers.offer.revision
erlaubte Werte
(optional) Zeichenkette bestehend aus Buchstaben und Zahlen, max.
20 Zeichen
Beschreibung
eindeutiger Bezeichner der Version des Angebots, welcher von Ihnen
frei gewählt werden kann.
Beispiel
20100701ab1255
25 / 29
4. Notes
Falls das Zeitfenster, in dem ein Angebot aktualisiert wird, sehr klein ist (z.B. mehrere Updates desselben Angebots innerhalb weniger Sekunden), können wir nicht die Einhaltung der Reihenfolge gewährleisten, in welcher die Aktualisierungen vorgenommen werden. Dies könnte dazu führen, dass nicht
der gewünschte Datensatz angezeigt wird.
Wenn Sie uns Requests in sehr kurzen Zeitabständen übermitteln (mehrere Requests innerhalb weniger Sekunden), können wir nicht gewährleisten, dass die Angebote, welche uns in dem jew. Request
übermittelt wurden, auch in der ursprünglichen Reihenfolge ins System übernommen werden. Dies
könnte zu unerwarteten Ergebnissen führen, insbesondere, wenn in den verschiedenen Requests die
gleichen Angebote enthalten sind.
26 / 29
5. FAQ
Q: In der XML-Antwort taucht für Angebot X der Status „IGNORED“ auf. Was bedeutet das?
A:
 Das Angebot war bereits aktuell bei idealo (die gesendeten Angebotsdaten enthielten keine Änderungen).
 In einer Anfrage war ein und dasselbe Angebot mehrfach vorhanden. (In diesem Fall wird das erste Offer einlesen und für weitere identische SKUs ein IGNORED in die Response geschrieben.)
 In einer Anfrage war ein und dasselbe Angebot mehrfach vorhanden und die Daten (z. B. Preis)
sind unterschiedlich. In diesem Fall wird für alle identischen SKUs mit einem IGNORED geantwortet, da unklar ist, welche SKU die aktuellsten Daten enthält.
 Bitte achten Sie deshalb darauf, dass Sie uns in einer Anfrage jedes Angebot nur einmal übermitteln.
Q: In der XML-Antwort taucht für Angebot X der Status „FILTERED“ auf. Was bedeutet das?
A:


Das Angebot enthält Wörter oder Begriffe, die aus rechtlichen oder idealo-internen Gründen gesperrt sind.
Bei Marktplatz-Shops ist der Verkäufer gesperrt.
Q: Ich bekomme als Antwort keine XML-Antwort sondern den HTML-Status 403 (Forbidden).
A: Die Authentifizierung ist fehlgeschlagen. Überprüfen sie Username und Passwort oder wenden Sie
sich an [email protected].
Q: Ich bekomme als Antwort keine XML-Antwort sondern den HTML-Status 400 (Bad Request).
A: Die Anfrage war fehlerhaft. Meist durch invalides XML.
Q: Ich bekomme als Antwort keine XML-Antwort sondern den HTML-Status 503 (Service Unavailable).
A: Der Server ist im Moment überlastet oder es gibt ein idealo-internes Problem. Bitte versuchen Sie
es später noch einmal.
Q: Werden Angebote, die im testMode verschickt werden, bei idealo gespeichert oder angezeigt?
A: Nein. Der testMode dient nur dazu, die Erreichbarkeit des Webservice und die syntaktische Korrektheit der Anfrage zu überprüfen.
Q: Der Webservice antwortet nicht oder der Webservice braucht sehr lange bis er antwortet.
A: Bitte beachten Sie, dass es einige Zeit dauern kann bis der Webservice antwortet. Dies hängt unter
anderem davon ab, wie viele Angebote in der Anfrage enthalten waren. Wir empfehlen in Ihrer Applikation einen Timeout von 2 Sekunden pro Angebot einzuplanen.
27 / 29
6. Changelog / Änderungen
Version 1.7
- offers.offer.expireDate Format wurde geändert
- offer.updateTimestamp Format wurde geändert
- Brand Beispiel in offers.offer.attributes Beispiel ersetzt
- context erweitert um Kontexte für weitere Länder
- Erläuterungen zum Direktkauf wurden hinzugefügt
Version 1.6
- Hinweis zum Encoding im Request-Header eingefügt.
- Booleanfelder eingeschränkt auf die Werte true und false.
Version 1.5
- Basic Authentifizierung wurde eingeführt und damit auch die URL geändert
- Beispiele in Dokumentation wurden an die Authentifizierung angepasst
- Neue Rückgabestatus IGNORED, FILTERED eingeführt
- In der SKU zulässige Zeichen eingeschränkt.
- Timeout: 2 Sekunden per Angebot berücksichtigen.
Version 1.4
updateOffers:
- offer.oen: neu hinzugefügt
- offer.kba: neu hinzugefügt
- offer.formerPrices: neu hinzugefügt
- offer.deposits: neu hinzugefügt
- offer.title: CDATA unterstützt
- offer.productTitle: CDATA unterstützt
- offer.attributes: CDATA unterstützt
- offer.shippingComment: CDATA unterstützt
- offer.category: CDATA unterstützt
- offer.brand: CDATA unterstützt
- offer.description: CDATA unterstützt
Antwort XML neu hinzugefügt.
offerResponses:
- offerResponses.error: neu hinzugefügt
- offerResponse.id: neu hinzugefügt
- offerResponse.sku: neu hinzugefügt
- offerResponse.status: neu hinzugefügt
- offerResponse.statusMsg: neu hinzugefügt
28 / 29
Version 1.3
updateOffers:
- offers.offer.listPrice: neu hinzugefügt
- offers.offer.attributes: neu hinzugefügt
Version 1.2
updateOffers:
- context Italien (IT) hinzugefügt
- weitere Zahlarten: SOFORTUEBERWEISUNG, GIROPAY, MONEYBOOKERS, CLICKANDBUY,
PAYSAFECARD, GOOGLECHECKOUT, POSTALORDER, EPS, ICLEAR
Version 1.1
updateOffers:
- offers.offer.revision: neu hinzugefügt
- offers.testMode: neu hinzugefügt
getOffers:
- Neu in Version 1.1
29 / 29

VERSION 1.7 - idealo Blog

Transcription

Documents pareils

Sind Sie an zusätzlichen Vorteilen interessiert?

CONDITION Last Minute

chinese checkers - Jim Thompson Fabrics

saree stripe - Jim Thompson Fabrics

Lafuma Bodenschoner Grau 4er lfm 2418-1229 - ToolTeam

Fahrzeug- Erfassung

Duravit M#bel-Waschtisch VERO 850x490mm 1

Keramag Aufsatzwaschtisch PRECIOSA d=460mm

Stadt Viersen Familienzentrum/Städt. Kindertageseinrichtung

You are teaching a Leistungskurs class at the beginning of year 12