Benutzer-Werkzeuge


Navigation

09 API Dokumentation

Was ist die Rakuten Shop-API?

Die Rakuten Shop-API (= Application Programming Interface) ermöglicht es, über eine Programmierschnittstelle auf Daten Ihres Rakuten-Shops zuzugreifen. So kann z.B. ein Warenwirtschafts-System angebunden werden, um Ihre Produkt-Daten im Rakuten-System zu aktualisieren oder in Ihrem Rakuten-Shop eingegangene Bestellungen abzurufen. Der Austausch der Daten erfolgt im XML-Format (alternativ JSON oder PHP-Serialisiert) über das HTTP-Protokoll. Dadurch kann eine Anbindung in jeder beliebigen Programmiersprache erfolgen.

API nutzen


Die API-Schnittstelle aktivieren Sie im BackOffice unter Connect! → Shop:API

Mit der API-Schnittstelle können Sie z.B.

  • Produkte einstellen, bearbeiten und löschen
  • Kategorien erstellen, bearbeiten und löschen
  • Bestellungen abholen

Plentymarkets benötigt beispielsweise den API-Schlüssel, um Bestellungen bearbeiten zu können.

Schlüssel erstellen

Um einen API-Schlüssel - gelegentlich auch Händlerschlüssel Händler-Key, Shop-Key genannt - zu erstellen, wählen Sie zunächst das externe Shop- bzw. Warenwirtschaftssystem aus, das Sie anbinden möchten.

Haben Sie ein System, das hier nicht in der Liste aufgeführt ist, wählen Sie bitte den Punkt Eigenentwicklung / andere Schnittstelle.

sie können zwischen folgenden Schnittstellen (teilweise über Drittanbieter) wählen:

  • 4Sellers (logic-base GmbH)
  • Actindo (actindo GmbH)
  • Amicron Faktura (Amicron Software)
  • Auction Studio (Anton Röckenwagner Auction Management Solutions)
  • auktionmaster (ChannelAdvisor GmbH)
  • brickfox (brickfox GmbH)
  • cateno AuctionSync (cateno GmbH & Co. KG)
  • cateno ShopSync (cateno GmbH & Co. KG)
  • CleverReach (CleverReach GmbH & Co. KG)
  • Cludes (cludes GmbH)
  • DreamRobot (CDN Consulting & Development Network GmbH)
  • Globalsys Datacenter (Globalsys GbR)
  • Globalsys individuelle Middleware (Globalsys GbR)
  • Inooga Solutions (Inooga Solutions GmbH)
  • Lexware Faktura/Warenwirtschaft (Haufe-Lexware GmbH & Co. KG)
  • Magnalister (RedGecko GmbH)
  • Mauve System 3 (Mauve Mailorder Software GmbH & Co KG)
  • novomind (novomind AG)
  • Oktopus Pro (SLU GmbH)
  • OscWare (NetConnections GmbH)
  • PlentyMarkets (plentymarkets GmbH)
  • Plugin GoRakuten für Shopware (arboro UG)
  • Shopgate (Shopgate GmbH)
  • Speed4Trade CONNECT
  • TB.one (Tradebyte Software GmbH)
  • tricoma (IPResearch GmbH)
  • unicorn 2 (marcos software)
  • unicorn 1 (marcos software)
  • whBook (w + h GmbH)
  • XT:Multiconnect (RedGecko GmbH)
  • Eigenentwicklung / andere Schnittstelle (Eigene Entwicklung)

Nachdem Sie die Schnittstelle gewählt haben, vergeben Sie die Rechte für

  • Produkte
  • Bestellungen
  • Kategorien

Die Rechte für das externe Programm sind:

  • keine (die Daten dürfen nicht gelesen werden)
  • lesen (die Daten dürfen gelesen werden)
  • lesen & schreiben (es dürfen die Daten gelesen und zu Rakuten übertragen werden)

Wie funktioniert sie?

Eine API-Methode wird immer mit einer Anfrage über das HTTP-Protokoll aufgerufen. Die Shop-API gibt daraufhin eine Antwort in einem maschinenlesbaren Format zurück. Die Antwort kann dann in Ihrem System ausgewertet und weiterverarbeitet werden.

Sie benötigen zum Start keine Anmeldung!

Für den Start Ihrer Implementierung steht Ihnen nichts im Wege. Mit der Testumgebung der Rakuten-Shop-API können Sie schon jetzt ohne Anmeldung damit beginnen Ihre Anbindung zu erstellen und zu testen.

Diese Punkte sollten Sie bei der Anbindung beachten:

Folgend finden Sie alles was Sie zur Implementierung benötigen. Vom Aufbau der URL bis hin zur Fehlerverarbeitung finden Sie hier alle Informationen.

1. URL

Aufbau

Die URL zu einer API-Methode setzt sich folgendermaßen zusammen:

http://webservice.rakuten.de/ version /merchants/ group / method

version

Die Version der API-Methode. Als Standard-Wert ist „v1“ hinterlegt und muss daher nicht mit in der URL angegeben werden.

Wenn es eine neue Version der API-Methode gibt, muss die Version entsprechend mit angegeben werden. Welche Version gerade aktuell ist, sehen Sie auf der entsprechenden Detail-Seite der API-Methode.

group

Die Methoden-Gruppe in der sich die API-Methode befindet.
Bitte beachten Sie die entsprechende Gruppe zur API-Methode.

Derzeit gibt es die Gruppen „products“, „orders“, „categories“ und „misc“.

method

Der Name der API-Methode.

Beispiel

URL zur API-Methode getProducts (ohne Parameter):

http://webservice.rakuten.de/v2.05/merchants/products/getProduct

2. Parameter
Wie Sie Informationen aus Ihrem System beim Aufruf der API-Methode übergeben, erfahren Sie hier.

Beschreibung

Als Parameter werden die Daten bezeichnet, die Sie beim Aufruf der API-Methode übergeben. Die Parameter können mit HTTP-GET oder auch mit HTTP-POST übergeben werden. Welche Parameter die einzelnen API-Methoden benötigen finden Sie auf der entsprechenden Detailseite der API-Methode.

Grundsätzlich sind beide Verfahren bei jeder API-Methode anwendbar. Zu jeder API-Methode wird eine entsprechende Übertragungs-Methode auf der Detailseite empfohlen. Überflüssige Parameter werden ignoriert.

Beispiel mit HTTP-GET

So sieht Ihre URL aus, wenn Sie z.B. die Parameter search und search_field mit HTTP-GET der API-Methode übergeben wollen:

http://webservice.rakuten.de/merchants/products/getProducts?search=apple&search_field=producer

3. Datentypen
Hier erfahren Sie, welche Datentypen in den Parametern zu den API-Methoden vorkommen dürfen.

Beschreibung

Alle Parameter einer API-Methode besitzen einen genauen Datentyp.
Auf der Detailsseite der API-Methode wird beim jedem Parameter immer der entsprechende Datentyp angegeben.

Die Rakuten-Shop-API benutzt folgende Datentypen:

int

Der Wert besteht nur aus einer Zahl.

Beispiel: 2010

float

Mit Punkt getrennte Zahl. Kein Tausender-Trennzeichen vorhanden.

Beispiel: 15123.99

string

Text aus beliebigen Zeichen.

Beispiel: Hallo Welt!

boolean

Nur die Werte „1“ und „0“ sind erlaubt.

Beispiel: 1

date

Eine Datum im Format YYYY-MM-DD HH:MM:SS.

Beispiel: 2010-05-12 12:10:30

url

Das Protokoll „http:“ muss vorhanden sein. Beispiel: http://www.rakuten.de

4. Authentifizierung
Wie Sie Ihre Berechtigung zum Benutzen der Rakuten-Shop-API bekommen und anwenden, können Sie hier nachsehen.

Beschreibung

Ein Zugriff auf die Rakuten-Shop-API benötigt eine Berechtigung.

Die Authentifizierung erfolgt zwingend über den sog. Händler-Schlüssel.
Diesen Schlüssel müssen Sie als Parameter key bei jedem Aufruf einer API-Methode mit übergeben.

Den Händler-Schlüssel bekommen Sie von dem entsprechenden
Rakuten-Händler, für den Sie eine Anbindung entwickeln.
Dieser erstellt den Schlüssel in seinem Admin-Bereich und stellt hierfür die entsprechende Berechtigung ein.

Beispiel:

Der Händler-Schlüssel als Parameter key beim Aufruf einer API-Methode:

http://webservice.rakuten.de/merchants/products/getProducts?key=c86cea54c71sbb05a5f8297bed641944

Berechtigung

Der Händler kann Ihnen für jede Methoden-Gruppe entweder Lese-, oder Lese und Schreib-Rechte gewähren. So kann es vorkommen, dass Sie Produkt-Daten bearbeiten können aber Bestelldaten nur auslesen dürfen.

Beispiel:

Hier dürfen Sie Produkte bearbeiten, Kategorien auslesen und haben für Bestell-Daten keine Rechte:

products orders categories
keine Rechte X OK X
Lesen X X OK
Lesen-Schreiben OK X X

Limitierung

Die Anzahl der Aufrufe der Rakuten-Shop-API ist auf 10.000 pro Tag und Shop begrenzt. Wenn Sie mehr Anfragen benötigen, so können wir Ihnen nach einer kurzen Rücksprache das Limit erhöhen.


5. Antwortformate
Hier wird Ihnen gezeigt, wie Sie das Antwort-Format eines Aufrufs nach Ihren Anforderungen festlegen können.

Beschreibung

Sie können mit dem Parameter format entscheiden, welches Format die Antwort einer API-Methoden Aufrufs haben soll.

Folgende Formate stehen zur Verfügung:

XML

Parameter-Wert: xml

Beispiel: http://webservice.rakuten.de/merchants/products/getProductLinks?format=xml

<?xml version="1.0" encoding="utf-8"?>
<result>
  <success>1</success>
  <links>
    <link>
   <link_id>2</link_id>
      <title>Hersteller</title>
      <url>http://www.hersteller.de</url>
    </link>
    <link>
      <link_id>3</link_id>
      <title>Google</title>
      <url>http://www.google.de</url>
    </link>
  </links>
</result>

JSON

Parameter-Wert: json

Beispiel: http://webservice.rakuten.de/merchants/products/getProductLinks?format=json

{"result":{"success":"1","links":{"link":[{"link_id":"2","title":"Hersteller","url":"http:\/\/www.hersteller.de"},{"link_id":"3","title":"Google","url":"http:\/\/www.google.de"}]}}}

PHP-Serialized

Parameter-Wert: php

Beispiel: http://webservice.rakuten.de/merchants/products/getProductLinks?format=php

a:1:{s:6:"result";a:2:{s:7:"success";s:1:"1";s:5:"links";a:1:{s:4:"link";a:2:{i:0;a:3:{s:7:"link_id";s:1:"2";s:5:"title";s:10:"Hersteller";s:3:"url";s:24:"http://www.hersteller.de";}i:1;a:3:{s:7:"link_id";s:1:"3";s:5:"title";s:6:"Google";s:3:"url";s:20:"http://www.google.de";}}}}}
6. Erfolgsmeldung
Wie Sie erfahren, ob Ihre Anfrage erfolgreich war, wird Ihnen hier erklärt.

Beschreibung

Sie können einfach ermitteln, ob Ihre Anfrage erfolgreich war, indem Sie das success-Element der Antwort auswerten.

Beispiel in XML

<?xml version="1.0" encoding="utf-8"?>
<result>
  <success>1</success>
</result>
Element Datentyp Bedeutung
result Container Container mit angeforderten Daten
success Boolean
1 - erfolgreich
0 - erfolgreich (keine Datensätze gefunden)
-1 - fehlerhaft

Steht im success-Element der Wert „1“, so war Ihre Anfrage erfolgreich.

Ist der Wert „0“ vorhanden, so war Ihre Anfrage auch erfolgreich, jedoch wurden keine Datensätze gefunden.

Wenn der Wert „-1“ vorhanden ist, so hat Ihre Anfrage einen Fehler erzeugt.


7. Fehlerbehandlung
Hier wird Ihnen gezeigt, wie Sie Fehler verarbeiten können und wie Sie weitere Informationen erhalten, um das Problem zu lösen.

Beschreibung

Wenn Ihre Anfrage nicht erfolgreich war, bekommen Sie Fehler-Informationen zurückgegeben. Diese sind im errors-Element vorhaden.

Beispiel in XML

<?xml version="1.0" encoding="utf-8"?>
<result>
  <success>-1</success>
  <errors>
    <error>
      < code>40< /code>
      <message>Der benötigte Parameter "name" konnte nicht gefunden werden</message>
      <help>http://www.google.de</help>
    </error>
    <error>
      < code>40< /code>
      <message>Der benötigte Parameter "price" konnte nicht gefunden werden</message>
      <help>http://www.google.de</help>
    </error>
  </errors>
</result>
Element Datentyp Bedeutung
result Container Container mit angeforderten Daten
success Boolean
1 - erfolgreich
0 - erfolgreich (keine Datensätze gefunden)
-1 - fehlerhaft
errors Container Container mit Fehlermeldungen
error Container Container mit Fehlerdaten
code Integer Fehler-Code
message String Fehlermeldung
help Url URL zu einer Hilfe-Seite

Es liegen Fehler vor, wenn im success-Element der Wert „-1“ vorhanden ist. Ist dies der Fall, so gibt es zusätzlich immer das errors-Element.

Allgemeine Fehler

Hier finden Sie alle allgemeinen Fehler, die beim Aufruf einer API-Methode auftreten können. In jeder API-Methode können zusätzlich methoden-spezifische Fehler auftreten. Die dazugehörigen Fehlermeldungen finden Sie auf der entsprechenden Detailseite der API-Methode.

Code Bedeutung
10 Der Aufbau der URL zur API-Methode ist ungültig
12 Das angegebene Antwort-Format ist ungültig
13 Diese IP ist für Anfragen nicht freigegeben
15 Der Händler-Schlüssel ist ungültig
16 Der Händler-Schlüssel konnte nicht gefunden werden
18 Der Händler-Schlüssel ist vom Rakuten-Händler gesperrt worden
20 Das tägliche Anfrage-Limit wurde erreicht
30 Die API-Methode konnte nicht gefunden werden
35 Die API-Methode ist momentan nicht verfügbar
37 Die API-Methode kann wegen fehlenden Leserechten nicht ausgeführt werden
38 Die API-Methode kann wegen fehlenden Schreibrechten nicht ausgeführt werden
39 Interner Fehler beim Aufruf der API-Methode
40 Der benötigte Parameter „parameter“ konnte nicht gefunden werden
41 Der Parameter „parameter“ besitzt einen ungültigen Wert


8. Testumgebung
Beginnen Sie sofort mit der Nutzung der Rakuten-Shop-API und finden heraus wie Sie Ihre Anbindung testen können.

Beschreibung

Damit Sie die Anbindung an die Rakuten-Shop-API testen können, haben wir eine sog. Sandbox eingerichtet. Dies bedeutet, dass Sie alle API-Methoden aufrufen können, ohne in das Live-System von Rakuten zu gelangen.

Der Aufruf der API-Methode bleibt gleich. Auch die Parameter-Übergabe sowie die jeweilige Antwort bleibt in der Testumgebung identisch.

Dies ermöglicht auch ohne einen Händler-Schlüssel eine komplett funktionsfähige Anbindung zu erstellen.

Zum Testen ist lediglich der Sandbox-Schlüssel erforderlich. Dieser besitzt den gleichen Aufbau, sowie die gleiche Anwendung wie der Händler-Schlüssel. So muss in der Anwendung bei der Veröffentlichung nur der Sandbox- mit dem Händler-Schlüssel ausgetauscht werden.

Ihr Sandbox-Schlüssel:

123456789a123456789a123456789a12

Beispiel:

Der Sandbox-Schlüssel statt dem Händler-Schlüssel als Parameter key beim Aufruf einer API-Methode:

http://webservice.rakuten.de/merchants/products/getProducts?key=123456789a123456789a123456789a12

9. HTML-Tags
Hier sehen Sie, welche HTML-Tags verwendet werden können und welche nicht.

Im Folgenden finden Sie eine Liste aller nicht erlaubten HTML tags.
Ebenso finden Sie eine Liste aller erlaubten HTML tags, inklusive der zugehörigen Attribute, welche Sie verwenden können.

Nicht erlaubte HTML Tags

Folgende Tags dürfen nicht verwendet werden:

appletbuttonfieldsetformframe
framesetiframeinputselectscript
styletextareaxmp

Erlaubte HTML Tags

<a>hrev rel rev target class id style tabindex title
<b>class id style title
<blockquote>cite class id style title
<br>class id style title
<caption>align
<col>align span vallign width class id style title
<colgroup>align span valign width class id style title
<div>align class id style title
<em>class id style title
<font>color face size class id style title
<h1>align class id style title
<h2>align class id style title
<h3>align class id style title
<h4>align class id style title
<h5>align class id style title
<h6>align class id style title
<hr>align noshade size width class id style title
<i>class id style title
<img>alt src align border height hspace ismap usemap vspace width class id style title
<label>for class id style title
<li>value class id style title
<link>href media rel rev target class id style title
<param>name type value valuetype
<object>align archive boder classid codebase codetype data declare height hspace name standby usemap vspace width class id style tabindex title
<ol>start class id style title
<p>align class id style title
<q>cite class id style title
<s>class id style title
<small>class id style title
<span>class id style title
<strike>class id style title
<strong>class id style title
<style>media title
<table>align bgcolor border cellpadding cellspacing frame rules summary width class id style title
<tbody>align valign class id style title
<td>abbr align axis bgcolor colspan headers height nowrap rowspan scope valign width class id style title
<th>abbr align axis bgcolor colspan height nowrap rowspan scope valign width class id style title
<thead>align valign class id style title
<title>
<tr>align bgcolor valign class id style title
<u>class id style title
<ul>class id style title

Die verschiedenen Calls

Allgemein

Bestellungen

Kategorien

Produkte