REST API
Version vom 20. April 2018, 08:16 Uhr von Admin (Diskussion | Beiträge)
Einführung
Die Rest API ist eine plattformunabhängige Schnittstelle um Daten mit dem Shopsystem auszutauschen. Diese Beschreibung richtet sich an Entwickler mit entsprechendem technischen Wissen zur Nutzung einer Rest API.
Die API ist ohne vorherige Freischaltung oder Installation unter folgendem Endpunkt erreichbar:
https://www.ihre-shopdomain.de/api/rest/v1
Bitte ersetzen Sie dabei Ihre persönliche Domain. Selbstverständlich ist der Zugriff auf die API regelementiert. In der Shopadminstration unter Benutzer->API-Benutzer erstellen Sie dazu einen neuen Benutzer, bei dem der API-Key optional ist. Die Authentifizierung erfolgt pro Aufruf mit Benutzername und Kennwort. Der Abruf erfolgt über eine verschlüsselte Verbindung, sofern für den Onlineshop eine solche aktiv ist.
Ressourcen
In der Version 1 der API, die ab der Shopversion 2.2 zur Verfügung steht, stehen lesende Ressourcen zu folgenden Daten zur Verfügung
Kategorien
- Alle Kategorien im Shop auslesen - als Liste
- Alle Kategorien im Shop auslesen - als Verzeichnisbaum
- Details einer bestimmten Kategorie auslesen
Produkte
- Alle Artikel einer Kategorie auslesen
- Details eines Artikels auslesen
- Liste der Varianten eines Produktes
Bestellungen
- Alle Bestellungen eines Jahres auslesen
- Alle Bestellungen eines Monats auslesen
- Details einer Bestellung auslesen
- Versandtracking setzen
- Bestellung abschließen
Kunden
- Alle Kunden auslesen
- Alle Kunden einer Kundengruppe auslesen
- Details eines Kunden auslesen
API Client
Für den einfachen Einstieg steht eine einfache API Klasse in PHP zur Verfügung. Diese basiert auf CURL, das als Modul zur Verfügung stehen muss.
<?
// SERVERSPOT SHOP API
// Version 1.0 - available at Core Version 2.1
class ServerspotAPI {
protected $api_location;
protected $cURL;
protected $available_methods = array("GET","POST");
public function __construct($url, $user_name, $user_password) {
$this->api_location = rtrim($url, '/') . '/';
$this->cURL = curl_init();
curl_setopt($this->cURL, CURLOPT_RETURNTRANSFER, true);
curl_setopt($this->cURL, CURLOPT_FOLLOWLOCATION, false);
curl_setopt($this->cURL, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($this->cURL, CURLOPT_USERPWD, $user_name . ':' . $user_password);
curl_setopt($this->cURL, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json; charset=utf-8',
));
}
public function call($url, $method = "GET", $data = array()) {
if (!in_array($method, $this->available_methods)) {
throw new Exception('Invalid HTTP-Methode: ' . $method);
}
curl_setopt($this->cURL, CURLOPT_URL, $this->api_location . $url);
return $this->getResult(curl_exec($this->cURL), curl_getinfo($this->cURL));
}
public function get($url) {
return $this->call($url, "GET");
}
public function post($url, $params) {
return $this->call($url, "POST", $params);
}
protected function getResult($json_result, $info) {
if (null === $result = json_decode($json_result, true)) {
echo "Error decoding Result" . json_last_error();
echo "<pre>" . print_r($json_result, true) . "</pre>";
return;
}
if (isset($result['result']) && $result['result']=="ok") {
echo "<h3>Success</h3>";
echo "<pre>" . print_r($result, true) . "</pre>";
return;
}else{
echo "<h3>Error</h3>";
echo "<p>" . $result['message'] . "</p>";
return;
}
return $result;
}
}
?>
Client
Um diese Klasse nutzen zu können wird ein Objekt der Klasse mit folgendem Code erstellt:
<?php
$name = "apiuser"; $password = "supersecretpassword";
$url = "https://www.shopdomain.de/api/rest/v1";
$api = new ServerspotAPI($url,$name,$password);
?>
Die komplette Kommunikation erfolgt in UTF8-Kodierung.
API Anfragen
Die API liefert in jeder Antwort einen Wert für result.
Bei einer korrekten Anfrage, ist result mit ok gesetzt, andernfalls mit error.
Sollte die Anfrage Fehlerhaft sein, so wird unter message ein Grund angegeben.
Beispiel:
(
[result] => error
[message] => No Category with ID 0
)
Kategorien
Alle Kategorien im Shop auslesen - als Liste
<?php
$api->get("categories");
?>
(
[result] => ok
[data] => Array
(
[20] => Array
(
[ID] => 20
[name] => Kategorie Eins
[url] => https://www.shopdomain.de/p/kategorie-eins/0/1
[parent] => 0
[position] => 1
[status] => Y
)
[60] => Array
(
[ID] => 60
[name] => Kategorie Zwei
[url] => https://www.shopdomain.de/p/kategorie-zwei/0/1
[parent] => 0
[position] => 1
[status] => Y
)
Alle Kategorien im Shop auslesen - als Kategoriebaum
<?php
$api->get("categories/recursive");
?>
(
[result] => ok
[data] => Array
(
[20] => Array
(
[ID] => 20
[name] => Kategorie Eins
[urlname] => kategorie-eins
[oberID] => 0
[prodanz] => 0
[subcat] => Array
(
[56] => Array
(
[ID] => 56
[name] => Unterkategorie Eins
[urlname] => unterkategorie-eins
[oberID] => 20
[prodanz] => 4
[subcat] => Array
(
)
)
[21] => Array
(
[ID] => 21
[name] => Unterkategorie Zwei
[urlname] => unterkategorie-zwei
[oberID] => 20
[prodanz] => 1
[subcat] => Array
(
[28] => Array
(
[ID] => 28
[name] => Letzte Kategorie
[urlname] => Letzte-kategorie
[oberID] => 21
[prodanz] => 52
[subcat] => Array
(
)
)
Details einer Kategorie auslesen
<?php
$api->get("category/20");
?>
(
[result] => ok
[data] => Array
(
[ID] => 20
[name] => Kategorie Eins
[url] => https://www.shopdomain.de/p/kategorie-eins/0/1
[google_taxonomy] => Tiere > Haustierbedarf > Hundebedarf
[parent] =>
[position] => 1
[descr] => "<h1>Kategoriebeschreibung</h1><br/><br/><br/>Lorem Ipsum"
[status] => Y
)
)
Produkte
Alle Artikel einer Kategorie auslesen
<?php
$api->get("products/32");
?>
(
[result] => ok
[data] => Array
(
[0] => Array
(
[ID] => 1197
[artnr] => 02MN0003
[artname] => Leine Twister oliv
[url] => https://www.shopdomain.de/leine-twister-oliv
[stock] => 10
[price] => 21.200
[status] => Y
[variants] => N
)
[1] => Array
(
[ID] => 1199
[artnr] => 02MN0007
[artname] => Leine Twister mocca
[url] => https://www.shopdomain.de/leine-twister-mocca
[stock] => 10
[price] => 21.200
[status] => Y
[variants] => Y
)
Details eines Artikels auslesen
<?php
$api->get("product/1197");
?>
(
[result] => ok
[data] => Array
(
[ID] => 1197
[registration] => 1311797166
[artnr] => 02MN0003
[artname] => Leine Twister oliv
[url] => https://www.shopdomain.de/491197/leine-twister-oliv
[description] =>
Hochwertiges Multifilamentgarn aus Polypropylen in Handarbeit gefertigt
farbecht
Karabiner ist aus rostfreiem gebürstetem Nickel
verstärkt mit hochwertigem geölten Leder
Farbe: oliv, braun und beige
Erhältliche Längen:
ca: 100 cm
ca: 150 cm
Durchmesser beider Leinen:
ca.13 mm
[main_characteristics] =>
[pzn] =>
[mpnr] =>
[ean] =>
[isbn] =>
[fsk18] => N
[manufacturer] =>
[weight] => 0.00
[stock] => 10
[price] => 21.200
[content] => 0.00
[contentunit] => ohne
[status] => Y
[deliverytype] => 3
[variants] => Array
(
)
[graduatedprice] => N
[minimumquantity] => 1
[discount] => 0
[discountart] => prozent
[vat] => 19.00
[seo] => Array
(
[title] =>
[keywords] =>
[description] =>
)
[img] => Array
(
[0] => Array
(
[main] => Y
[url_large] => https://www.shopdomain.de/data/pics/shop/large/617db1c8f07e573f48a01f03c386f0e8.jpg
[url_medium] => https://www.shopdomain.de/data/pics/shop/medium/617db1c8f07e573f48a01f03c386f0e8.jpg
[url_small] => https://www.shopdomain.de/data/pics/shop/small/617db1c8f07e573f48a01f03c386f0e8.jpg
)
)
[groupprice] => Array
(
[0] => Array
(
[group_id] => 18
[group_name] => Händler
[preis] => 15.80
)
)
[categories] => Array
(
[0] => 32
)
)
)
Liste der Varianten eines Produktes
<?php
$api->get("productvariants/1199");
?>
(
[result] => ok
[data] => Array
(
[Länge] => Array
(
[100] => 1012
[150] => 1013
)
)
)
Bestellungen
Alle Bestellungen eines Jahres auslesen
<?php
$api->get("orders/2015");
?>
(
[result] => ok
[data] => Array
(
[11682] => Array
(
[ID] => 11682
[userID] => 173
[time] => 1433327365
[per] => Paypal
[payed] => N
[status] => 0
[total] => 743.84
)
[11681] => Array
(
[ID] => 11681
[userID] => 203
[time] => 1433326042
[per] => Paypal
[payed] => N
[status] => 0
[total] => 96.4
)
Alle Bestellungen eines Monats auslesen
<?php
$api->get("orders/2015/5");
?>
(
[result] => ok
[data] => Array
(
[11673] => Array
(
[ID] => 11673
[userID] => 203
[time] => 1432902368
[per] => Klarna Rechnungskauf
[payed] => Y
[status] => 0
)
[11670] => Array
(
[ID] => 11670
[userID] => 203
[time] => 1432812818
[per] => Vorkasse per Überweisung
[payed] => N
[status] => 0
)
Details einer Bestellung auslesen
<?php
$api->get("order/11681");
?>
(
[result] => ok
[data] => Array
(
[time] => 1433326042
[customer] => 14
[email] => max@mustermann.com
[address] => Array
(
[company] => Mustermann GbR
[title] => Herr
[name] => Max Mustermann
[street] => Hellersbergstraße 14
[zip] => 41460
[town] => Neuss
[country] => de
[phone] => 02271888888
)
[invoice] => Array
(
[company] => Mustermann GbR
[title] => Frau
[name] => Erika Mustermann
[street] => Hellersbergstraße 14
[zip] => 41460
[town] => Neuss
[country] => de
[phone] => 02271888888
)
[comment] =>
[status] => 0
[dispatch] => 4.90
[delivery] => Array
(
[service] => 1
[tracking] => 12378128371293827
)
[coupon] => Array
(
[code] =>
[type] =>
[value] => 0.00
)
[payment] => Array
(
[type] => 2
[payed] => N
[fee] => 0.00
)
[cart] => Array
(
[0] => Array
(
[bestell_ID] => 11681
[artID] => 1752
[artnr] => 2WA20
[artname] => Leine CITY CHIC Blüte grün / (Leinenlänge) 110 x 1,3 cm
[anzahl] => 3
[preis] => 15.500
[vat] => 19.00
)
[1] => Array
(
[bestell_ID] => 11681
[artID] => 3240
[artnr] => vsv
[artname] => sev
[anzahl] => 1
[preis] => 45.000
[vat] => 19.00
)
)
)
)
Paketverfolgung setzen
<?php
$api->post("ordertracking/11681",array("delivery" => "DHL", "code" => "00340434174844484564"));
?>
Mögliche Werte für "delivery" sind:
* DHL
* POSTAT
* POSTCH
* DPD
* GLS
* HERMES
* UPS
* FEDEX
* CHARRY
(
[result] => ok
)
Bestellung abschließen
<?php
$api->post("ordersent/11681",array());
?>
(
[result] => ok
)
Kunden
Alle Kunden auslesen
<?php
$api->get("customers");
?>
(
[result] => ok
[data] => Array
(
[173] => Array
(
[ID] => 173
[email] => xxx@email.de
[gender] => Herr
[company] => Mustermann GmbH
[firstname] => Max
[surname] => Mustermann
[address] => Musterweg 1
[zip] => 12345
[town] => Musterstadt
[country] => de
[fon] => 888777
[vat_id] => DE8888888HH
[invoice] => Array
(
[gender] => Frau
[company] =>
[firstname] => Erika
[surname] => Mustermann
[address] => Musterstrasse 3
[zip] => 12345
[town] => Musterdorf
[country] => be
)
[birthday] => 1980-02-18
[account] => Array
(
[holder] => Kontoinhaber
[iban] => MEINEIBAN1234
[swift] => MEINEBIOC555
)
[registration] => 2012-04-04
[group] => 18
[newsletter] => N
)
[174] => Array
(
Alle Kunden einer Kundengruppe auslesen
<?php
$api->get("customers/18");
?>
(
[result] => ok
[data] => Array
(
[173] => Array
(
[ID] => 173
[email] => xxx@email.de
[gender] => Herr
[company] => Mustermann GmbH
[firstname] => Max
[surname] => Mustermann
[address] => Musterweg 1
[zip] => 12345
[town] => Musterstadt
[country] => de
[fon] => 888777
[vat_id] => DE8888888HH
[invoice] => Array
(
[gender] => Frau
[company] =>
[firstname] => Erika
[surname] => Mustermann
[address] => Musterstrasse 3
[zip] => 12345
[town] => Musterdorf
[country] => be
)
[birthday] => 1980-02-18
[account] => Array
(
[holder] => Kontoinhaber
[iban] => MEINEIBAN1234
[swift] => MEINEBIOC555
)
[registration] => 2012-04-04
[group] => 18
[newsletter] => N
)
[174] => Array
(
Details eines Kunden auslesen
<?php
$api->get("customer/173");
?>
(
[result] => ok
[data] => Array
(
[ID] => 173
[email] => xxx@email.de
[gender] => Herr
[company] => Mustermann GmbH
[firstname] => Max
[surname] => Mustermann
[address] => Musterweg 1
[zip] => 12345
[town] => Musterstadt
[country] => de
[fon] => 888777
[vat_id] => DE8888888HH
[invoice] => Array
(
[gender] => Frau
[company] =>
[firstname] => Erika
[surname] => Mustermann
[address] => Musterstrasse 3
[zip] => 12345
[town] => Musterdorf
[country] => be
)
[birthday] => 1980-02-18
[account] => Array
(
[holder] => Kontoinhaber
[iban] => MEINEIBAN1234
[swift] => MEINEBIOC555
)
[registration] => 2012-04-04
[group] => 18
[newsletter] => N
)
)
