API Magentoeinbindung

Magento Shopanbindung und Bestellabruf per API Schnittstelle

Wie erstelle ich bei Magento einen Zugang zur Schnittstelle?

Um eine Kommunikation zwischen Faktura-XP und Ihrem Magentoshop® herzustellen sind keinerlei Änderungen an Ihrem bestehenden Shop nötig. Es werden lediglich einige Schnittstellen Scripte - die sogenannte APICON - auf Ihren Webserver geladen und als zweites ein neuer Benutzer innerhalb Ihres Magentoshop® angelegt, der als legitimierter Benutzer für den Datenabruf von außen berechtigt ist. Der bereits bei der Installation des Magento-Shop angelegte Benutzer "Admin" ist für den Zugriff nicht geeignet.

Zusammenfassung

A) Hochladen der Schnittstellen Scripte APICON auf Ihren Webserver
B) Anlegen eines neuen Benutzers innerhalb Ihres Magentoshop
C) Hinterlegen der Zugangsdaten in Faktura-XP

A - Hochladen der APICON Dateien

Die Schnittstellen Scripte können Sie mit einem separaten FTP Programm Ihrer Wahl auf den Server laden. Dazu müssen Sie die "FTP Zugangsdaten" zu Ihrem Webserver kennen.

FTP Upload der APICON Schnittstelle

Stellen Sie eine Verbindung zum Webserver her auf dem die Magntoshop® Dateien abgelegt sind. Navigieren Sie nun auf die Ebene des Hauptverzeichnisses - dem "Root Verzeichnis" Ihrs Shopsystems. Das ist die Verzeichnisebene "app" auf der auch die Datei "../app/Mage.php" Ihres Magentoshop zu sehen ist.

Die APICON Dateien, die nun auf den Webserver geladen werden sollen befinden sich im Unterverzeichnis "System" Ihrer Faktura-XP Installation. Das ist im Regefall "C:\Anwendungen\FakturaXP\System\". Das dort befindliche Verzeichnis "apicon" enthält alle nötigen Scripte. Dies Verzeichnis wird mit dem gesamten Inhalt auf die gerade beschriebene Ebene Ihres Webservers hochgeladen.

Das Verzeichnis "apicon" muss sich nun auf der gleichen Ebene befinden wie das Verzeichnis "app" Ihres Magento®-Shop.

B - Benutzer für den Shopabruf einrichten

Schritt 1: In den Admin-Bereich des Magento-Shops einloggen

Den Admin-Bereich erreichen Sie in der Regel unter folgender Adresse: www.ihreDomain.de/admin oder www.ihreDomain.de/magento/admin, falls Ihr Shop im Unterverzeichnis "magento" installiert wurde.

Schritt 2: Zunächst muss eine Gruppenberechtigung erstellt werden

Klicken Sie dazu im Admin-Bereich auf den Menüpunkt System > Web Dienste > Gruppenberechtigungen (Pfeil).

Nachdem die Seite "Gruppenberechtigungen" geladen wurde, klicken Sie rechts auf den Knopf "Neue Rolle" (Pfeil).

Bitte geben Sie nun den Namen der Gruppen- Berechtigung ein (Pfeil rechts) und klicken Sie anschließend auf "Gruppenberechtigung Quellen" (Pfeil links).

Wählen Sie nun bei Quellenzugriff aus der Drop-Down Liste den Eintrag "Alle" aus, damit ein uneingeschränkter Zugriff zur Schnittstelle besteht.

Bitte speichern Sie anschließend die Gruppenberechtigung, indem Sie rechts oben auf den Button "Gruppenberechtigung speichern". Anschließend sollte die Meldung "Gruppenberechtigung erfolgreich gespeichert" erscheinen.

Schritt 3: Neuen Benutzer für Webdienst / Schnittstelle erstellen

Nachdem Sie nun erfolgreich eine Gruppenberechtigung erstellt haben, werden Sie jetzt den Benutzer für die Schnittstelle anlegen.

Öffnen Sie dazu wieder im Admin-Bereich den Menüpunkt System -> Web Dienste und klicken anschließend auf "Benutzer" (Pfeil).

Nachdem die Seite "Benutzer" geladen wurde, klicken Sie rechts auf den Knopf "Neuer Benutzer". Geben Sie in die darauf folgende Eingabemaske (Bild unten) Ihre gewünschten Daten für den Benutzer ein. Bitte merken Sie sich Benutzername und API Schlüssel (Passwort). Diese Angaben werden für die Eingabe in Faktura-XP benötigt um Zugriff auf Bestellungen und Artikel des Shop zu erhalten.

Verwenden Sie für Benutzernamen keinen Bindestrich, Umlaute oder Sonderzeichen.

Klicken Sie anschließend auf "Benutzer Gruppenberechtigung" (Pfeil).

Nun wählen Sie die zuvor erstellte Gruppenberechtigung aus der Liste aus (hier: gruppe1) und klicken dann auf den Button "Benutzer speichern" um Ihren Benutzer anzulegen. Jetzt ist der Schnittstellen-Zugang erfolgreich angelegt und kann mit denn angegeben Daten genutzt werden.

Im nächsten Schritt werden wir die Einstellungen innerhalb Faktura-XP beschreiben.

.

C - Zugangsdaten in Faktura-XP hinterlegen

Die "Zugangsdaten des neu angelegten Benutzers" werden nun in Faktura-XP hinterlegt. Damit ist die Kommunikation zwischen Faktura-XP und dem Magentoshop erst möglich. Verlassen Sie den Adminbereich des Onlineshop und starten nun die Anwendung Faktura-XP.

Klicken Sie im Menü auf "Webshop Synchronisieren".

Wählen Sie den Verbindungs-Typ "Magento" aus und klicken auf "weiter".

Lassen Sie vorerst das Häkchen "Auswahl beim nächsten mal übergehen" noch leer, bis alles nach Ihren wünschen funktioniert.

.

Magento Bestellverarbeitung: Registerkarte: „Bestellabruf”

Wenn Sie Ihre Auswahl getroffen haben, gelangen Sie in die Magento Bestellverarbeitung.

Zunächst müssen wir die Zugangsdaten in Faktura-XP hinterlegen. Dazu wechseln Sie auf die Registerkarte "Einstellungen". (Um mehr über den Bestellabruf zu erfahren besuchen Sie die Seite Abruf von Bestellungen aus Magento)

.

Magento Bestellverarbeitung: Registerkarte: „Einstellungen”

In der Registerkarte "Einstellungen" können Sie einige wichtige Kriterien für den Bestellabruf einstellen.

Eindeutige Kennung für Lagerbuchung

Falls Sie beim Bestellabruf aus Ihrem Onlineshop die bestellten Artikel aus dem Lagerbestand von Faktura-XP abziehen möchten, können Sie dies hier einstellen. Damit Faktura-XP die Artikel zuordnen kann, die gebucht werden sollen, müssen sie angeben, wie die Erkennung der Artikel erfolgen soll. Da die Artikelnummern in Ihrem Shop von denen der Artikelverwaltung innerhalb Faktura-XP abweichen kann, ist hier einstellbar, welches Feld mit Faktura-XP verglichen werden soll um den entsprechenden Artikel zu identifizieren.

Bestellabruf nach Nummer oder Status

Sie können wählen, ob die Neubestellungen über den Status der Bestellung (z.B. "offen") oder über die Bestellnummer erkannt werden sollen. Wählen Sie "Bestellnummer" als Erkennung von Neubestellungen, wird intern eine Liste der bereits bekannten und verarbeiteten Bestellungen geführt. Damit sind dann doppelte Abrufe ausgeschlossen, da dann vor dem Abruf die höchste, bekannte Bestellnummer ermittelt wird und nur die Bestellungen abgerufen werden, die größer als die bekannte Bestellnummer sind.

Textbausteine für Lieferscheine

Hier können Sie aus vorhandenen Textbausteinen auswählen, welche Texte Lieferscheinen verwendet werden, die beim Bestellabruf automatisiert erstellt werden. Lassen Sie die Felder leer, werden automatisch Bestelldaten, Datum als Text formuliert und eingefügt.

.

Zugriffsprofil für den Shop-Abruf konfigurieren

Klicken Sie hier auf die Schaltfläche "Zugriffsprofile und User-Zugang". Es öffnet sich der separate Dialog zur Verwaltung der Zugriffsprofile.

Profile und Einstellungen für den Datenzugriff: Registerkarte „Zugriffsprofile”

.

Zugangsdaten zum Datenabruf konfigurieren

Die Zugangsdaten werden in so genannten Profilen gespeichert. Dies ist der Zugriff des "Benutzers für Webdienste" Ihres Magento-Shop. Wie Sie diesen Benutzer in Ihrem Magentoshop anlegen haben wir bereits weiter oben beschrieben.

Sie können beliebig viele Profile anlegen und verwenden. Für die Neuanlage eines Profils klicken Sie auf die Schaltfläche "+" und geben dem Profil zunächst einen eindeutigen Namen.

Zugriff konfigurieren

Geben Sie im Feld "Domainname Shop" die WWW Adresse Ihres Shop ein. Befindet sich Ihr Shop in einem Unterverzeichnis des Servers wie z.B. "www.MeinShop.de/verzeichnis1/verzeichnis2/" geben Sie die Unterverzeichnisse - wie im Beispiel - mit ein (ohne Anführungszeichen).

Geben Sie dann den Benutzername und den API-Schlüssel ein, den Sie bei der Anlage des "Benutzers für Webdienste" in Ihrem Magentoshop bereits angelegt haben. Achten Sie dabei auf Groß- und Kleinschreibung.

SSL Server

Betreiben Sie Ihren gesamten Magentoshop über einen SSL Server können Sie die Option "Verbindung über SSL Verschlüsselung herstellen" anklicken. Sie erkennen SSL an dem vorangestellten "https://" in der Adresszeile Ihres Browsers, während Sie sich auf der Startseite Ihres Shops befinden.

.

Magento Zugriff konfigurieren

Für den Datenabruf müssen Sie noch die Zugangsdaten des zuvor angelegten Benutzers für Web Dienste (siehe [Anhang_13_(Magentocommerce)|oben]]) eingeben.

Geben Sie im Feld "Domainname Shop" die komplette Internetadresse, inkl. eventueller Unterverzeichnisse ein - z.B. "www.MeinShop.de/verzeichnis1/verzeichnis2/" (ohne Anführungszeichen).

Im Feld "Benutzernamen" und "API-Schlüssel" geben Sie die Zugangsdaten des zuvor angelegten Benutzer des Magento-Shop ein und setzen das Häkchen "Zugangsdaten lokal speichern" um die Daten auf Ihrem PC zu speichern.

"Benutzernamen" und "API-Schlüssel" sind NICHT die Zugangsdaten zum Adminbereich Ihres Shops!!!

Mit der Schaltfläche "OK" oder der Schaltfläche "Diskette" wird das Profil lokal abgespeichert. Ein Profil löschen können Sie mit der Schaltfläche "X" neben dem Profilnamen.

.

Parameter

In das Parameter gelangen Sie, indem Sie in dem Register „Einstellungen” auf den Button klicken. Nun öffnet sich ein neues Fenster mit weiteren Registerkarten.

.

Registerkarte: Shop

In dem Bereich unter Mehrwertsteuer können Sie entsprechende Einstellungen vornehmen, wie z.B ob Faktura-XP die Versandkosten in Brutto (inkl.MwSt) berechnet oder wie hoch die MwSt für den Versand ist. Links in den zwei Feldern sehen Sie oben Ihren Standort und darunter Ihre aktuelle Standardwährung.

.

Registerkarte: weitere Parameter

Unter weitere Parameter können Sie verschiedene Einstellungen über den Kundenstamm, Zahlungsbedingungen, Versandkosten-Bindung, Bank-Transfer, DTA Erzeugen und Bestellnummern vornehmen.

.

Registerkarte: Artikelübertragung

Hier konfigurieren Sie die Einstellungen zu der Artikelübertragung, den Artikelpreisen und der Erlöse und Einheit.

.

Registerkarte: Löschfunktionen

Unter Löschfunktionen können Sie Shopartikel oder Shop-Kategorieren löschen. Achten Sie hierbei auf die Hinweise.

.

Magento Bestellverarbeitung: Registerkarte: Protokoll

Je nach Abruf listet Faktura hier die entsprechenden Daten auf. Wenn Sie über ein anderes Register einen Abruf tätigen, wechselt Faktura in dieses Register um Ihnen die Daten aufzuzählen. Mehr dazu finden Sie auf der Seite Abruf von Bestellungen aus Magento

.

Magento Bestellverarbeitung: Registerkarte: „weitere Funktionen”

In dem Register „weitere Funktionen”, können Sie Abrufe tätigen oder Konfigurieren. Zudem erhalten Sie Informationen zu Ihren Storeviews und können Adressen und Lagerartikel aktualisieren.

Klicken Sie auf Kundenabrufe, zeigt Faktura Ihnen in einem kleinen Fenster die Gesamtanzahl von Kunden und die Anzahl der Neukunden an.

Wenn Sie Ihre Artikel abrufen, sichert Faktura erst die Daten und zeigt dann die Ergebnisse im Protokoll an, welches direkt aufgeschlagen wird.

Klicken Sie auf diese Schaltfläche, aktualisiert Faktura Ihre gespeicherten Adressen.

Bei Betätigung aktualisiert Faktura-XP die Lagerbestände in Ihrem Onlineshop, berücksichtigt dabei aber auch die Lagerentnahme im Onlineshop, die z.B durch Bestellungen von Kunden erfolgt.

Um Ihre Shop-Artikel zu aktualisieren, klicken Sie auf diese Schaltfläche. Es öffnet sich nun ein neues Fenster mit verschiedenen kriterien für den Artikelimport.

Hier können Sie z.B Auswählen ob Sie die Artikelbeschreibungen Ihrer Artikel in Faktura-XP mit denen in Ihrem Onlineshop abgleichen oder die Verkaufpreise aktualisieren wollen. Sie können auch mehrere Kriterien auf einmal auswählen.

Hinweis: Wenn Faktura den Artikel oder Kundenabruf nicht vollständig ausführen konnte, (z.B durch eine Unterbrechung der Verbindung oder ähnliches) kann durch ein gesetztes Häkchen im Feld für „Abruf mit lokalen Daten,” Faktura den unterbrochenen Abruf fortsetzen. Sie setzen also das Häkchen und führen den Abruf erneut aus. Somit wird dieser fortgesetzt und nicht erneut vollständig verarbeitet.

.

Storeviews

Was sind Storeviews?

Storeviews beschreiben jeden einzelnen Shop durch verschiedene Interfaces im Magento. Ist z.B. ein deutscher und ein englischer Shop vorhanden, so sind zwei Storeviews gegeben. Storeviews können beliebig oft verwendet und individuell gestaltet werden.

Klicken Sie auf die Schaltfläche , wird eine Liste der Storeviews online abgerufen und die lokalen Storeviews aktualisiert. Diese werden dann in der Liste sichtbar, aber auch wenn Sie andere Funktionen nutzen.

Haben Sie mehrere Stores, können Sie oben rechts im Register unter Abruf den jeweiligen Store aussuchen. Die Zahl 0 steht für alle Stores und somit werden alle Übertragungen, Aktualisierungen usw. bei allen Stores vorgenommen.

Im unteren Teil des Registers, haben Sie die Möglichkeit den Beginn des jeweiligen Abrufes selbst festzulegen oder nur zu kontrollieren. Der Abruf wird ab der eingestellten Bestellnummer fortgeführt. Den letzten zeigt Ihnen Faktura im oberen Feld an. In dem unteren Feld können Sie diese Nummer selbst festlegen, jedoch wird damit der Wert der automatischen Erkennung von Faktura überschrieben.

.

Error-Codes und Funktionsstörungen

Die Error-Codes (Fehler-Codes)

Wenn eine Überprüfung der Verbindung mit dem Magento-Shop nicht möglich ist (Betätigen der Taste „Testen”), zeigt Faktura Ihnen Fehlermeldungen an. Solche Error-Codes (Fehler-Codes) enthalten den Grund und die zugehörige Zahl der jeweiligen Fehlermeldung.

Bedeutungen der Error-Codes/ Fehlermeldungen:

Fehlermeldungen beim Login:

/* Login */

define 100; --> Diese Meldung wird angezeigt, wenn kein Fehler beim Login aufgetreten ist (Nummer 100)
define 101; --> Der Zugang zum Shop wird verwehrt (Nummer 101)
define 199; --> Ein noch unbekannter Fehler ist aufgetreten (Nummer 199)

Fehlermeldungen beim Skript:

/* Skript */

define 1000; --> Faktura konnte keinen Skript finden (Nummer 1000)
define 1099; --> Dieser Fehler tritt auf, wenn Sie versuchen Sich einzuloggen, aber bereits eingeloggt sind (Nummer 1099)
define 1110; --> Es entsteht ein Fehler beim Lesen des Produktes (Nummer 1110)
define 1210; --> Ein benötigter Ordner ist nicht vorhanden (Nummer 1210)
define 1310; --> Ein gesuchter Kunde fehlt (Nummer 1310)
define 1410; --> Die Addressen-Angabe existiert nicht (Nummer 1410)
define 1510; --> Die gesuchte Kategorie konnte nicht gefunden werden (Nummer 1510)

Funktionsstörungen oder Test klappt nicht

Sollte es zu Problemen mit dem Hochladen der Schnittstellen Scripte ("apicon" Ordner) geben, prüfen Sie mit einem FTP Programm ob das Verzeichnis "apicon" am angegebenen Ort des Webserver vorhanden ist. Danach prüfen Sie, ob alle Unterverzeichnisse und Dateien in diesem Ordner enthalten sind. Ist dies auch der Fall, prüfen Sie zuletzt noch ob diese Unterverzeichnisse die eigentlichen Scripte enthalten. Dies sind Dateien mit der Endung ".php".

Sollten alle Scripte vorhanden sein und Probleme auftreten können Sie sich auch gern an unsere Hotline wenden oder eine Email an unseren Support [1] senden.

Support Mailadresse: support@faktura-xp.de 

.