Entwicklerleitfaden #
Soll ein anderes SHOP-System außer NopCommerce angebunden werden, so kann die Basis-Schnittstelle von EULANDA die Kommunikation mit der EULANDA-Warenwirtschaft und einem FTP-Server übernehmen. Die Basis-Schnittstelle kann Artikel, Kategorien, Kategorie-Zuordnungen, Hersteller, Lieferanten, Bilder, Lagerbestände als XML-Datei auf eine vorgegebene FTP-Verzeichnisstruktur ablegen. Umgekehrt kann die Schnittstelle Aufträge im XML-Format abholen und in die Warenwirtschaft importieren.
Damit dies reibungslos funktioniert sind gewisse Vorgaben einzuhalten. Neben einer festen Verzeichnisstruktur und Dateibenennung gibt es auch einen festen Satzaufbau der XML-Dateien und der Art und Weise wie Bilder übertragen werden müssen.
Allgemeines #
Dem Kunden muss eine Möglichkeit zur Verfügung gestellt werden, einmal exportierte Aufträge erneut für eine Übergabe freizuschalten.
Konstanten müssen in irgendeiner einfachen Weise durch den Kunden änderbar sein, sind diese Werte nicht über die SHOP-Oberfläche zu verwalten, so müssen diese in einer Konfigurationsdatei über den FTP-Server verwaltet werden. Hierzu gehören zum Beispiel E-Mail-Adressen, die im Fehlerfalle für die Fehlermeldung angeschrieben werden sollen.
Adressen und Anschriften #
NopCommerce Adressen #
NopCommerce Adressschema
In NopCommerce ist der Login, der Datensatz an dem sich weitere anfügen. Diesem können beliebig viele Adressen zugeordnet sein. Dies können Rechnungs- und Lieferanschriften sein. Adressen können aber auch losgelöst vom Login nur Abholadressen sein.
Dieser Art Beziehung macht eine vollwertige Synchronisation schwierig bis unmöglich, so dass man nur eingeschränkt Daten bidirektional austauschen kann.
EULANDA Adressen #
EULANDA Adressschema
In EULANDA ist die Adresse in der Regel die Rechnungsadresse. Jeder Adresse können beliebige Kontakte zugeordnet werden (z.B. Einkäufer). Gibt es in EULANDA mehrere Lieferadressen, so sind dies eigene Adressen, die zwar mit der Rechnungsadresse lose verbunden werden können – zum vereinfachten Auffinden – aber es ist keine feste Relation.
Diese unterschiedlichen Ansätze, die auch den unterschiedlichen Aufgaben geschuldet sind, erlauben keine direkte bidirektionale Synchronisation von Adressdaten.
Datenabgleich #
Der Datenabgleich zwischen diesen Konzepten beschränkt sich hierdurch auf die Übergabe von Rechnungs- und Lieferadressen. Jeder übernommene Auftrag enthält in NopCommere neben dem Login auch eine Rechnungsadresse und falls vorhanden eine Lieferadresse. Diese kann unter Umständen auch eine Abholadresse in einer Filiale des Shop-Betreibers sein.
Bei der Übergabe des Auftrags wird die Auftragsadresse im EULANDA-Adressstamm angelegt. Hierzu wird ein Prefix „NOP:“ und die E-Mailadrese des Logins verwendet.
Die so angelegte Adresse wird mit dem übernommenen Auftrag verknüpft. Gibt es eine abweichende Lieferadresse, wird eine Dummy-Adresse im EULANDA-Adressstamm mit Matchcode „SHIPPING“ angelegt. Diese wird im Stammsatz ohne weitere Information angelegt, da diese von allen Lieferadressen die über das SHOP-System hereinkommen, verwendet wird. Die eigentlichen Informationen der Lieferadresse werden direkt in die Felder des Auftrags übernommen.
Es ist wichtig, dass für die Schnittstelle mindestens EULANDA Version 7.0.17 eingesetzt wird, da speziell das Matchcodefeld in der Länge stark erweitert wurde um auch lange E-Mailadressen abbilden zu können.
FTP-Struktur #
Die Kommunikation erfolgt über einen FTP-Server, der vom Kunden zu stellen ist. Ab einem frei definierbaren Basis-Verzeichnis werden die Daten in einer festen Struktur abgelegt.
FTP-Verzeichnisstruktur #
Im Beispiel gehen wir von folgender Annahme aus:
FTP-Basisordner: „/SHOP“
Name des Shops: „FutureWare“
Mandant: „Mustermann“
Artikel 1: 4711
Artikel 2: 4712
Die Struktur würde dann wie folgt aussehen:
/SHOP
/SHOP/Mustermann
/SHOP/Mustermann/Dms/Product
/SHOP/Mustermann/Dms/Product/Merkmal
/SHOP/Mustermann/Dms/Product/4711
/SHOP/Mustermann/Dms/Product/4712
/SHOP/Mustermann/FutureWare/Inbox
/SHOP/Mustermann/FutureWare/Inbox/Pending
/SHOP/Mustermann/FutureWare/Inbox/Running
/SHOP/Mustermann/FutureWare/Inbox/Finished
/SHOP/Mustermann/FutureWare/Outbox
/SHOP/Mustermann/FutureWare/Outbox/Pending
/SHOP/Mustermann/FutureWare/Outbox/Running
/SHOP/Mustermann/FutureWare/Outbox/Finished
Unterhalb des Mandanten-Namens „Mustermann“ gibt es zwei Ordner, einen „Dms“ für die Bilder und einen für die auszutauschenden Daten im XML-Format mit dem Namen „FutureWare“.
Die Artikel und Auftragsdaten werden über Inbox- und Outbox- Strukturen verwaltet. Hierbei werden aktiv laufende Prozesse immer im Ordner „Running“ abgelegt. Wenn diese hoch oder heruntergeladen sind, werden Sie entweder nach „Pending“ oder „Finished“ verschoben.
Im Ordner „Pending“ sind Dateien vorhanden, die stets für die sofortige Weiterverarbeitung vorgesehen sind. Der Ordner „Finished“ enthält abgeschlossene oder verworfene Dateien.
Die Bezeichnung Inbox und Outbox bezieht sich immer auf die EULANDA-Warenwirtschaft. Liegen im Ordner „/SHOP/Mustermann/FutureWare/Outbox/Pending“ XML-Daten, so sind dies Daten aus der EULANDA-Warenwirtschaft wie Artikel, Adressen oder Lagerdaten, welche zum SHOP übertragen werden sollen.
Möchte das SHOP-System hingegen Aufträge ablegen, liest die EULANDA-Schnittstelle diese aus dem Ordner „/SHOP/Mustermann/FutureWare/Inbox/Pending“ ein.
Bilder werden von EULANDA in Unterordner-Strukturen unterhalb des Ordners „Product“ kopiert. Die Unterordner enthalten als Namen immer die Artikelnummer (= SKU) des Artikels. Der Name der Bilddatei besteht aus der Artikelnummer, gefolgt von einem Bindestrich und einer fortlaufenden Zahl sowie einer Dateiendung entweder „.jpg“ oder „.png“. Die Fortlaufende Zahl beginnt mit „1“ bis maximal „15“ wobei die Nummerierung lückenlos ist.
Damit das weiterverarbeitende System erkennen kann, ob sich Bilder geändert haben, wird in den Ordner „Product“ eine Textdatei mit dem Namen „Md5.txt“ abgelegt. Diese enthält Textzeilen die mit CRLF getrennt sind und neben dem relativen Pfad zum Bild auch dessen MD5-Prüfsumme enthalten.
000007/000007-1.jpg BBE2A8476786EA648ED3A999EA316F7C
000021/000021-1.jpg F9FDBAB63AB1D20C16D26DCE7072D10A
000021/000021-2.jpg 1BE9387B1AF92CF60DEA6E233AD2DF78
000038/000038-1.jpg 67641002F07063B84D769DB50FDF72B1
000045/000045-1.jpg CE4FFD488610FC3079172729EC03E421
000069/000069-1.jpg 3E5D77DA1C110B6561DBA5020F327D05
000076/000076-1.jpg 184AC28AEBB18314CEB05FC47A35A64B
Die beiden Bestandteile des Dateinamens und der Prüfsumme sind mit einem Tabulatorzeichen (Binär 9) getrennt.
FTP-Dateinamen #
Die Dateien in den jeweiligen Inbox- und Outbox-Strukturen haben im Namen das Hauptobjekt und eine zufällige und eindeutige UID.
Lagerinformationen haben den Namen „stock“ gefolgt von einem Bindestrich und einer UID sowie die Dateierweiterung „.xml“. Die EULANDA-Schnittstelle legt diese im Outbox-Ordner unter „Pending“ ab.
stock-B31B508D-0D49-4803-B1EE-FB7CAFB1D182.xml
Artikelinformationen inkl. Kategorien haben im Namen „product“ gefolgt von einem Bindestrich und der Dateierweiterung „.xml“. Die EULANDA-Schnittstelle legt diese im Outbox-Ordner unter „Pending“ ab.
product-E85668CC-1488-491B-B0F5-1F2ABA5A735C.xml
Auftragsdaten werden im Inbox-Ordner unter „Pending“ erwartet und haben im Dateinamen „order“ gefolgt von einem Bindestrich und einer UDI sowie die Dateierweiterung „.xml“.
order-04378F00-7334-4ECD-A016-0D6125CEA2D6.xml
Von der SHOP-Schnittstelle können ggf. auch Lagerdaten und Artikel oder Adressen erwartet werden. Diese sind wie oben beschriebenen benannt und werden allesamt in der Inbox-Struktur erwartet.
Treten beim Import von Artikeln oder Lagerdaten Fehler bei der Import-Routine im SHOP auf, so wird die Fehlermeldung zum einen als E-Mail an eine einstellbare E-Mailliste erwartet und zum anderem als Textdatei mit der Dateierweiterung „.error“.
Die Betreffzeile der E-Mail hat den Aufbau „ERROR!(Leer)Mandant(leer)ShopName(leer).
ERROR! Mustermann-FutureWare product-E85668CC-1488-491B-B0F5-1F2ABA5A735C
Zusätzlich ist eine Textdatei in Unicode im Outbox-Pending-Ordner mit der Dateierweiterung „.error“ abzulegen. Der Dateiname muss dem der fehlerhaft verarbeiteten Datei entsprechen.
product-E85668CC-1488-491B-B0F5-1F2ABA5A735C.error
XML-Datei #
Die XML-Dateien verwenden native Feldnamen der EULANDA-Warenwirtschaft. Das Format ist für alle Dateigruppen identisch. In einer Datei (product*, order*, address*, stock* usw.) können beliebige Aufträge, Artikel, Kunden usw. übertragen werden.
Die XML-Datei muss in UTF-8 beschrieben sein, alle XML-Tags sind stets in Großbuchstaben anzugeben. Tags die unbekannt sind, müssen ignoriert werden. Sollen Felder gelöscht werden, sind bei Zahlen „0“ und bei Texten zwei doppelte Anführungszeichen zu setzen.
STRASSE>""</STRASSE>
Am Anfang der Übergabedatei steht ein Metablock, gefolgt von Listennamen. Die Listen enthalten die einzelnen Datensätze. Im folgenden Beispiel gibt es eine Artikelliste, welche dann verschiedene Artikel enthält. Der META-Block muss unbedingt ISO2 im Tag „COUNTRYFORMAT“ haben.
<EULANDA>
<METADATA>
<VERSION>1.1</VERSION>
<COUNTRYFORMAT>ISO2</COUNTRYFORMAT>
...
</METADATA>
<RABATTLISTE>
...
</RABATTLISTE>
<ARTIKELLISTE>
<ARTIKEL>
<ARTNUMMER>4711</ARTNUMMER>
<VKNETTO>12.59</VKNETTO>
…
</ARTIKEL>
<ARTIKEL>
<ARTNUMMER>4712</ARTNUMMER>
…
</ARTIKEL>
...
<ARTIKELLISTE>
</EULANDA>
Fließkommazahlen sind ohne Tausender-Trennung anzugeben, als Dezimal-Trennzeichen ist ein Punkt zu verwenden.
<COST>4845.00</COST>
Datumswerte sind in ISO anzugeben.
<DATUM>2014-05-31T20:30:14</DATUM>
Landeskennungen sind mit zweistelligen Alphacode anzugeben, also „DE“ für Deutsch.
<LAND>DE</LAND>
XML-Stuktur #
Beispiel einer Auftragsdatei #
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<EULANDA>
<METADATA>
<VERSION>1.1</VERSION>
<GENERATOR>NOPCOMMERCE</GENERATOR>
<DATEFORMAT>ISO8601</DATEFORMAT>
<FLOATFORMAT>US</FLOATFORMAT>
<COUNTRYFORMAT>ISO2</COUNTRYFORMAT>
<FIELDNAMES>NATIVE</FIELDNAMES>
<DATE>2017-05-05T16:08:24</DATE>
<PCNAME>EULANDA</PCNAME>
<USERNAME>ADMINISTRATOR</USERNAME>
<DATABASEVERSION>5.63</DATABASEVERSION>
</METADATA>
<MERKMALBAUM>
<ARTIKEL/>
</MERKMALBAUM>
<RABATTLISTE/>
<ARTIKELLISTE/>
<ADRESSELISTE>
<ADRESSE>
<ID.ALIAS>NOP:SHIPPING</ID.ALIAS>
<MATCH>NOP:SHIPPING</MATCH>
</ADRESSE>
<ADRESSE>
<ID.ALIAS>NOP:GUEST</ID.ALIAS>
<MATCH>NOP:GUEST</MATCH>
</ADRESSE>
<ADRESSE>
<ID.ALIAS>NOP:INFO@EULANDA.EU</ID.ALIAS>
<MATCH>NOP:INFO@EULANDA.EU</MATCH>
<NAME1>EULANDA Software GmbH</NAME1>
<NAME2>Gerd Schmitt</NAME2>
<STRASSE>Auf der Langwies 1a</STRASSE>
<PLZ>65510</PLZ>
<ORT>Hünstetten</ORT>
<LAND>DE</LAND>
<EMAIL>info@eulanda.eu</EMAIL>
<TEL>0612693730</TEL>
</ADRESSE>
</ADRESSELISTE>
<AUFTRAGLISTE>
<AUFTRAG>
<DATUM>2017-05-05T13:26:36</DATUM>
<BESTELLNUMMER>100208</BESTELLNUMMER>
<OBJEKT>Onlineshop</OBJEKT>
<BRUTTOFLG>0</BRUTTOFLG>
<SHOP>
<SHIPPINGINFO>
<COST>4.12</COST>
</SHIPPINGINFO>
</SHOP>
<ADRESSEID.ALIAS>NOP:INFO@EULANDA.EU</ADRESSEID.ALIAS>
<AUFTRAGPOSLISTE>
<AUFTRAGPOS>
<ARTIKELID.ALIAS>150012263</ARTIKELID.ALIAS>
<MENGE>1.00</MENGE>
</AUFTRAGPOS>
</AUFTRAGPOSLISTE>
</AUFTRAG>
</AUFTRAGLISTE>
</EULANDA>
Bei der Übermittlung von Aufträgen ist die Rechnungsadresse als Stammdatensatz (im Tag ADRESSLISTE) anzugeben. Handelt es sich um einen registrierten Kunden, muss die Adresse im TAG <ID.ALIAS> und im
Bei Gastbestellung darf im Stammsatz in der
Hat der Kunde eine abweichende Lieferanschrift angegeben, so ist diese mit „NOP:SHIPPING“ anzugeben. Diese werden im Stammsatz wie bei Gastbestellungen nur mit den Tags <ID.ALIAS> und
Im oberen Beispiel werden drei Adressen als Stammdatensatz ausgegeben. ID.ALIAS ist ein Pseudonym für die ID-Nummer. Diese wird jedoch erst später beim Import in die Warenwirtschaft erzeugt bzw. zugewiesen. Sie ist immer mit dem eindeutigen Key der Tabelle identisch, bei Adressen ist dies das Feld „MATCH“ bei Artikeln „ARTNUMMER“.
Wir empfehlen als eindeutigen Key ein kurzes Präfix, gefolgt von einem Doppelpunkt und der E-Mailadresse des Kunden, zu verwenden. Dieser bleibt in der Regel lange stabil, so dass Nachbestellungen dieser Adresse zugeordnet werden können. Bei der EULANDA NopCommerce-Schnittstelle wird das Präfix „NOP“ verwendet. Beachten Sie, dass KEY-Felder immer in Großbuchstaben anzugeben sind und Umlaute umgewandelt werden müssen – aus Ä wird AE.
Der Anwender hat später die Möglichkeit Rechnungsadressen, die durch die Schnittstelle angelegt wurden, mit einer Bestandsadresse zusammenzuführen und so als MATCH-Feld einen eigenen Begriff zu wählen. Spätere Bestellungen, die von der Schnittstelle kommen, werden trotzdem weiterhin synchronisiert.
Technisch ist es erforderlich eine Gast- und eine Lieferanschrift als Leerdatensatz über die Schnittstelle bei jeder Übergabe anzulegen. Die vorgeschlagene Benennung „NOP:GUEST“ und „NOP:SHIPPING“ kann über eine Konfigurations-Datei eingestellt werden, indem das Präfix „NOP“ und die beiden Begriffe „GUEST“ und „SHIPPING“ dort abgelegt werden können.
Das Feld „BRUTTOFLG“ gibt an, ob die Preise im Auftrag netto oder inklusive MwSt. sind. In der Version 3.0 der SHOP-Schnittstelle werden nur Nettowerte akzeptiert, BRUTTOFLG ist entsprechend mit „0“ zu übergeben. Eine Erweiterung der SHOP-Schnittstelle auf Bruttoübergabe ist derzeit nicht vorgesehen. Rechnungen werden also immer Netto ausgegeben und die MwSt. wird am Ende der Rechnung beaufschlagt.
Im Tag „SHIPPINGINFO“ können im Unter-Tag „COST“ die Versandkosten übertragen werden. Die Schnittstelle legt entsprechend eine neue Position im Auftrag von EULANDA mit den Versandkosten an.
Auftragsposition besteht zumindest aus der Artikelnummer (= SKU) und der Menge. Die „AUFTARGLISTE“ kann mehrere Abschnitte „AUFTRAG“ enthalten. In jedem „AUFTRAG“ gibt es eine „AUFTRAGPOSLISTE“ die wiederum mehrere „AUFTRAGPOS“ enthalten kann.
Ähnliches gilt für die Adressen. In diesem Beispiel sind drei Adressen angegeben, die dem Tag „ADRESSELISTE“ zugeordnet sind.
Die Bestellnummer im Auftragskopf muss eindeutig sein, diese wird dazu verwendet, Aufträge nicht mehrfach zu importieren. Die Schnittstelle lehnt entsprechend Aufträge ab, die bereits im Feld „BESTELLNUMMER“ der EULANDA-Auftragsdatenbank vorkommen.
Kategorien werden von EULANDA mit einer UID übergeben. Die Hierarchie wird über einen eigenen Abschnitt, der nach den Metadaten am Anfang der Datei steht, mit dem Namen „MERKMALBAUM“ übergeben.
Sind Änderungen an den Kategorien (= Merkmalbaum) in EULANDA gemacht worden, so wird stets der gesamte Baum neu übertragen. Zur Identifizierung im SHOP hat jeder Kategorie-Ordner und jedes Endmerkmal eine eindeutige UID. Wird eine Kategorie innerhalb der Hierarchie umgezogen, behält er die UID bei. Auf diese Wiese kann die Schnittstelle den Merkmalbaum im SHOP optimal anpassen.
Im ARTIKEL-TAG wird der Pfad des Artikels in einem Merkmalbaum jeweils mit übertragen. Ein Artikel kann in beliebig vielen Kategorien gleichzeitig enthalten sein. Die UID die ebenfalls dort angegeben wird, erlaubt eine schnelle Zuordnung im SHOP-System.
Ein Layout uploadfähig machen #
Ab Version 4.10 lassen sich nun auch Layouts (= Themes) wie Standard-Plug-Ins, in eine ZIP-Datei packen, sodass sicht diese über das Admincenter unter „Konfiguration\Plugins“ hochladen lassen.
Letztlich wird der einzelne Unterordner mit den Theme-Dateien in eine Zip-Datei gepackt in deren Root noch eine Beschreibungsdatei gepackt wird.
Diese Zusatzdatei „uploadeditems.json“ hat folgenden Aufbau:
[
{
"Type": "Theme",
"SupportedVersion": "4.10",
"DirectoryPath": "EULANDA-White/"
}
]
Diese Angaben werden in im Format UTF-8 als Text gespeichert. Dies lässt sich wunderbar mit den Windows-Notepad machen.
Achten Sie darauf, dass die Option „Dateiextension bei bekannten Dateitypen ausblenden“ im Dateiexplorer unter Optionen, nicht aktiviert ist, da dann zwar vermeintlich der richtige Dateiname angezeigt, aber unsichtbar doch noch die Endung „.txt“ angefügt wird.
Unterhalb der Zip-Root ist dann neben dieser Zusatzdatei nur der Hauptordner der Theme-Dateien, die unter „DirectoryPath“ in der Zusatzdatei angegeben wurde – also „EULANDA-White“.
Darunter sind die normalen Dateien wie bei jedem Theme enthalten. Also die Ordner „Content“ und „Views“ mit den jeweiligen Unterordnern.
Eine vollständige Struktur kann beispielsweise wie folgt aussehen:
\uploadeditems.json
\EULANDA-White
\EULANDA-White\preview.jpg (510px x 333px)
\EULANDA-White\theme.json
\EULANDA-White\Content
\EULANDA-White\Content\Css
\EULANDA-White\Content\Css\ie8.css
\EULANDA-White\Content\Css\print.css
\EULANDA-White\Content\Css\styles.css
\EULANDA-White\Content\Css\styles.rtl.css
\EULANDA-White\Content\Css\Images
\EULANDA-White\Content\Css\Images\*.gif *.png usw.
\EULANDA-White\Views
\EULANDA-White\Views\_ViewImports.cshtml
\EULANDA-White\Views\Shared
\EULANDA-White\Views\Shared\Head.cshtml
Der Name der Zip-Datei spielt keine Rolle. Über die json-Datei „theme.json“ werden die Theme-Eigenschaften angegeben.
Die in diesem Beispiel folgenden Inhalt hat:
{
"SystemName": "EULANDA-White",
"FriendlyName": "EULANDA-White",
"SupportRTL": false,
"PreviewImageUrl": "~/Themes/EULANDA-White/preview.jpg",
"PreviewText": "'EULANDA-White'"
}
Der Inhalt des Beispiels wurde im Wesentlichen dem NopCommerce-Standard-Theme „DefaultClean“ entnommen.
Nach der Plugin-Installation steht das Theme an gewohnter Stelle auf dem Webserver zur Verfügung.