Shop Importer Script

Ein großes Thema bei xentral ist die Anbindung und automatische Verarbeitung von Bestellungen in Online-Shops. Obwohl viele Online-Shops bereits einen hohen Automatisierungsgrad besitzen, stellen neue Shopsysteme und deren Anbindung uns immer wieder vor Herausforderungen. Zwar besitzt fast jeder Shop eine Schnittstelle, häufig stellt sich dann aber doch heraus, dass die anzubindenden Schnittstellen nicht kompatibel sind.

Der Importer tritt dabei als sogenannte Middleware auf und übersetzt die Daten der Bestellungen aus dem Shop in ein Format, aus dem xentral dann wiederum Aufträge erstellen kann. Umgekehrt ist der Importer auch dafür zuständig den Bestellstatus, also die Information, ob der Auftrag abgearbeitet und versendet wurde, sowie Artikeldaten und Lagerzahlen an den Shop zu übertragen – ein kompaktes Multitalent sozusagen.

Der Ablauf innerhalb des Importers folgt immer einem festen Schema. Wenn beispielsweise Aufträge aus dem Shop abgeholt werden sollen, wird zunächst geprüft ob eine Verbindung zur Shop-Schnittstelle besteht. Anschließend wird ermittelt ob, beziehungsweise wie viele, Aufträge im Shop abgeholt werden sollen. Wenn es Aufträge abzuholen gibt, werden diese importiert und anschließend im Shop als „In Bearbeitung“ markiert. Wenn Artikel aus dem Shop importiert oder in den Shop exportiert werden sieht das Schema ähnlich aus. Zunächst erfolgt eine Prüfung, ob eine Verbindung zwischen xentral und dem Shop besteht. Anschließend werden die Daten übertragen.

Um einen eigenen Importer zu schreiben benötigt man keine Expertenkenntnisse. Grundlegende PHP-Kenntnisse reichen aus, wenn man sich an die vorgegebene Struktur hält. Im Vorfeld sind jedoch einige Dinge zu klären:

Nachdem die Grundlagen für den Importer erledigt sind, kommt es jetzt zur eigentlichen Verbindung zu Shopware. Natürlich ist es möglich, die komplette Kommunikation in eine eigene Klasse auszulagern oder, im Falle von Shopware, die Klasse aus der Dokumentation zu kopieren. Der Einfachheit halber reicht für dieses Beispiel aber eine kurze Funktion welche die Antwort der API zurückgibt:

protected function call($endpoint, $method, $data=array(),$params=array()){ $queryString = ''; if (!empty($params)) { $queryString = '?'.http_build_query($params); } $url = $this->apiUrl.$endpoint.$queryString; $dataString = json_encode($data);

$curl = curl_init(); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl, CURLOPT_FOLLOWLOCATION, false); curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl, CURLOPT_USERPWD, $this->apiUser . ':' . $this->apiKey); curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json; charset=utf-8']); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method); curl_setopt($curl, CURLOPT_POSTFIELDS, $dataString); return curl_exec($curl); }

Als nächstes wird die Funktion ImportSendListLager() hinzugefügt. Wenn die Option für das Übertragen von Lagerzahlen in den Importeinstellungen aktiviert ist sorgt die Funktion dafür, dass die Bestände im Shop mit dem Beständen in xentral synchronisiert werden. In diesem Beispiel geschieht das über die Artikelnummer. Zu beachten ist, dass für diese Funktion im data-Parameter des Importer-Objekts die Daten für den zu aktualisierenden Artikel vorhanden sind.

public function ImportSendListLager() { $updatedArticles = 0; $tmp = $this->CatchRemoteCommand('data'); foreach ($tmp as $article){ $nummer = $article['nummer']; $lageranzahl = $article['anzahl_lager'];

$updateInStock = [
  'mainDetail' => [
    'inStock' => $lageranzahl
  ]
];

$params = [
  'useNumberAsId'=>true
];

$result = $this->call('articles/'.$nummer, 'PUT',$updateInStock, $params);
if($result['success']){
  $updatedArticles++;
}

} return $updatedArticles; }

Die Funktion ImportSendList() ist im Grunde genommen eine aufgebohrte Version von ImportSendListLager(). Die Funktion überträgt Artikel an den Shop - beziehungsweise aktualisiert deren Daten. Welche Daten und vor allem wie diese übertragen werden können, hängt von der jeweiligen Shop-Schnittstelle ab. So können Artikeleigenschaften oder auch Bilder an den Shop übertragen werden. Dabei sollte man auf die Trennung der beiden Funktionen achten, da ImportSendList nur in zwei Fällen aufgerufen wird:

$articleData = [ 'name' => $name, 'lastStock' => $laststock, 'tax' => $tax, // alternativ 'taxId' => 1, 'supplier' => $supplier, // alternativ 'supplierId' => 2, 'description' => $description, 'descriptionLong' => $description_long, 'keywords' => $keywords, 'metaTitle' => $metatitle, 'highlight' => $topseller, 'mainDetail' => [ 'number' => $articleNumber, 'active' => $active, 'ean' => $ean, 'weight' => $weight, 'width' => $width, 'len' => $length, 'height' => $height, 'supplierNumber' => $supplierNumber, 'inStock' => $lageranzahl, 'prices' => $prices ] ];

In dieser Funktion wird ermittelt, wie viele offene Bestellungen im Shop vorhanden sind und abgeholt werden müssen. Denkbar ist das Abholen über den Status, ab einer bestimmten Bestellnummer oder aber auch über das Bestelldatum. Abhängig von der Shopschnittstelle sind nicht alle Optionen realisierbar.

public function ImportGetAuftraegeAnzahl() { $result = $this->getOrders($this->data);

return count($result['data']); }

Die wichtigste Grundfunktion aller Importer ist das Abholen und Übersetzen der Bestellungen aus dem Shop in das Warenkorbformat von xentral. Nachdem die nächste Bestellung von der Shop API abgeholt wurde, werden im ersten Schritt die Adressdaten des Kunden an den Warenkorb übergeben:

$cart['anrede'] = 'herr'; $cart['strasse'] = $order['data']['billing']['street']; $cart['plz'] = $order['data']['billing']['zipCode']; $cart['ort'] = $order['data']['billing']['city']; $cart['land'] = $order['data']['billing']['country']['iso']; $cart['email'] = $order['data']['customer']['email']; $cart['name'] = $order['data']['billing']['firstName'] . ' ' . $order['data']['billing']['lastName'];

Falls eine abweichende Lieferadresse vorliegt, muss diese logischerweise enebfalls übergeben werden. Ausserdem muss dann das Feld abweichendeliferadresse mit true befüllt werden damit der Auftrag dann auch beim richtigen Empfänger ankommt. Anschließend gibt es eine ganze Reihe wichtiger Daten, die für die weitere Verarbeitung von Bedeutung sind.

$cart['auftrag'] = $orderFromCollection['id']; $cart['gesamtsumme'] = $orderFromCollection['invoiceAmount']; $cart['transaktionsnummer'] = $orderFromCollection['transactionId']; $cart['onlinebestellnummer'] = $orderFromCollection['number']; ... $cart['zahlungsweise'] = $order['data']['payment']['name']; $cart['lieferung'] = $order['data']['dispatch']['name']; $cart['bestelldatum'] = substr($order['data']['orderTime'],0,10); $cart['versandkostennetto'] = $order['data']['invoiceShippingNet'];

foreach ($order['data']['details'] as $article) { $articlearray[] = [ 'articleid' => $article['articleNumber'], 'name' => $article['articleName'], 'price' => $article['price'], 'quantity' => $article['quantity'] ]; }

...

$orderData =[ 'id' => $cart['auftrag'], 'warenkorb' => base64_encode(serialize($cart)), 'warenkorbjson' => base64_encode(json_encode($cart)) ];

Wenn die benötigten Grunddaten der Bestellung an den Warenkorb übergeben wurden, ist es an der Zeit die einzelnen Positionen zum Warenkorb hinzuzufügen. Im Feld articleid wird die Artikelnummer übergeben. In den anderen Feldern steht ihr jeweiliges Äquivalent aus der Bestellposition. Nachdem der Warenkorb mit allen Daten befüllt wurde die aus der Bestellung übergeben werden sollen, gibt die Funktion die Daten zurück. Funktionen ImportDeleteAuftrag / ImportUpdateAuftrag Die aus historischen Gründen ungünstig benannte Funktion ImportDeleteAuftrag wird nicht etwa dazu verwendet um Aufträge aus dem Shop zu löschen. Sie ist stattdessen dafür zuständig eine offene Bestellung als „In Bearbeitung“ zu kennzeichnen. Die Partnerfunktion ImportUpdateAuftrag kennzeichnet die Bestellung als „Versendet“.

public function ImportDeleteAuftrag() { $orderId = $this->data['auftrag']; $update = [ 'orderStatusId' => 1 ];

$this->call('orders/'.$orderId, 'PUT',$update);

return true; }