VibeFox Aramex for OpenCart — Hilfe

Anforderungen

OpenCart: 3.0.x (getestet mit 3.0.5.0) oder 4.0.2 und neuer (getestet mit 4.1.0.3).

PHP: 8.0 oder neuer.

Aramex-Konto (nur für Live-Tarife): Live-Tarife nutzen die Aramex Rate Calculator API. Aramex gewährt seinen Kontoinhabern API-Zugang. Fragen Sie Ihren Aramex-Kundenbetreuer oder sehen Sie im Aramex Developers Solution Center auf der Aramex-Website nach. Sie benötigen sechs Werte: API-Benutzername (meist eine E-Mail-Adresse), Passwort, Kontonummer, Konto-PIN, Standortcode des Kontos (zum Beispiel DXB) und Ländercode des Kontos (zum Beispiel AE). Wenn Sie nur feste Preise je Land nutzen, brauchen Sie kein Aramex-Konto.

VibeFox-Lizenzschlüssel: Kauf auf vibefox.net. Ein Schlüssel gilt für eine Domain.

Installation

Der Download ist eine ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das OpenCart-3-Paket vfd_aramex-oc3-(version).ocmod.zip und das OpenCart-4-Paket vfd_aramex.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen derselbe.

OpenCart 3

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_aramex-oc3-(version).ocmod.zip. Die Erweiterung fügt keine OCMOD-Modifikationen hinzu, Sie müssen Extensions > Modifications also nicht aktualisieren. Statt des Installers können Sie auch den Inhalt des Ordners upload dieses Pakets in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Aramex und klicken Sie auf Install (die grüne +-Schaltfläche).

3. Klicken Sie auf Edit (die Bleistift-Schaltfläche), um die Einstellungsseite zu öffnen.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel in das Feld License key im Lizenzblock oben auf der Seite Edit ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

5. Wählen Sie, wie der Versandpreis berechnet wird, füllen Sie die passenden Abschnitte aus (siehe Konfiguration), aktivieren Sie Enable Aramex und klicken Sie auf Save.

OpenCart 4

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_aramex.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Code der Erweiterung dem Dateinamen, und ein umbenanntes Paket funktioniert nicht.

2. Das Paket erscheint auf derselben Seite in der Liste der installierten Erweiterungen. Klicken Sie daneben auf Install (die grüne +-Schaltfläche).

3. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Aramex, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Bleistift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel und die Einstellungen ein wie in den Schritten 4 und 5 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich.

Nach der Installation ist die Versandart deaktiviert, bis Sie Enable Aramex einschalten und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die von Ihnen behaltenen Aramex-Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Aramex > Edit. Die Abschnitte stehen links. Ein Button Save unten speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht außerdem die zwischengespeicherten Aramex-Tarife. Ist ein Wert falsch, wird nichts gespeichert und die Seite zeigt den Grund, zum Beispiel Enter a method title (1 to 64 characters)., eine Meldung, dass ein Feld eine Zahl sein muss, oder The account country code must have 2 letters, e.g. AE. Nur Administratoren mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Allgemein

Die Einstellungen gelten für alle Geozonen. Sie können die Methode unter Conditions auf eine Geozone und auf bestimmte Länder beschränken.

Enable Aramex: blendet Aramex an der Kasse ein oder aus. Standard: aus.

Method title: der Name der Versandart, den der Kunde im Warenkorb und an der Kasse sieht. Standard: Aramex. Pflichtfeld.

Shipping cost: wie der Preis berechnet wird.

Der Grund für einen fehlenden Live-Tarif wird im Debug-Protokoll notiert. Er wird dem Kunden nie angezeigt.

Sort order: die Position von Aramex unter den Versandarten an der Kasse. Eine ganze Zahl.

Aramex-API-Konto (nur für Live-Tarife nötig; alle sechs Felder sind Pflicht)

Username: Ihr Aramex-API-Benutzername, meist eine E-Mail-Adresse. Wenn Sie ihn leeren, wird auch das gespeicherte Passwort gelöscht.

Password: Ihr Aramex-API-Passwort. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Account number: Ihre Kundennummer bei Aramex. Wenn Sie sie leeren, wird auch die gespeicherte PIN gelöscht.

Account PIN: die PIN Ihres Aramex-Kontos. Wie das Passwort wird sie nach dem Speichern nicht mehr angezeigt.

Account entity: der Standortcode (Büro) Ihres Aramex-Kontos, zum Beispiel DXB, AMM oder RUH.

Account country code: der zweistellige Ländercode Ihres Aramex-Kontos, zum Beispiel AE.

Aramex-Dienst (für Live-Tarife)

Liegt die Lieferadresse im Herkunftsland, wird die Sendung als Domestic angeboten. Alle anderen Sendungen werden als International express angeboten.

International service: das Aramex-Produkt für Sendungen ins Ausland: PPX Priority Parcel Express (Standard), PDX Priority Document Express, PLX Priority Letter Express (Dokumente unter 0,5 kg), DPX Value Express Parcels, EPX Economy Parcel Express, EDX Economy Document Express, GPX Ground Parcel Express oder GDX Ground Document Express.

Domestic service: das Aramex-Produkt für Sendungen innerhalb des Herkunftslandes: ONP Overnight (Parcel) (Standard), OND Overnight (Document), SMP Same Day (Parcel), SMD Same Day (Document), SDD Same Day Delivery, EMD Early Morning Delivery, PEC Economy Delivery, PEX Road Express oder HVY Heavy (20 kg und mehr).

Payment type: wer Aramex den Versand bezahlt: Prepaid (shipper pays) (Standard), Collect (receiver pays) oder Third party. Normalerweise Prepaid.

API weight unit: die Einheit, die an Aramex gesendet wird: Kilograms (KG) (Standard) oder Pounds (LB). Produktgewichte werden aus ihrer Gewichtsklasse umgerechnet, Abmessungen aus ihrer Längenklasse. Das abrechenbare Gewicht ist das größere von tatsächlichem Gewicht und volumetrischem Gewicht (Länge × Breite × Höhe in cm / 5000). Das Minimum beträgt 0,5 kg; das gilt auch für Produkte ohne Gewicht.

Currency conversion rate: Aramex wird gebeten, in der Standardwährung Ihres Shops anzubieten. Antwortet Aramex trotzdem in einer anderen Währung, wird der Tarif mit dieser Zahl multipliziert (1 Einheit der Aramex-Währung = X Einheiten Ihrer Standardwährung). Lassen Sie das Feld leer, um solche Angebote abzulehnen, damit ein Kunde nie in der falschen Währung belastet wird.

Versandursprung (für Live-Tarife)

Origin country: das Land, aus dem Sie versenden. Die erste Option, Store country, verwendet das Land Ihres Shops.

Origin city: die Stadt, aus der Sie versenden. Aramex verlangt sie. Die Shop-Adresse in OpenCart ist Freitext, daher wird die Stadt daraus nie übernommen: Geben Sie sie hier ein.

Origin state / emirate: optional.

Origin postcode: optional.

Ist das Herkunftsland Ihr Shop-Land, wird ein leeres Bundesland aus der Region Ihres Shops unter System > Settings > Store > Local übernommen.

Feste Preise (verwendet, wenn Shipping cost auf Fixed prices steht, und als Ersatz für Live-Tarife)

Price per country: eine Liste von Ländern und Preisen in der Standardwährung Ihres Shops, ohne Steuern. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die Schaltfläche ×, um eine zu entfernen. Wählen Sie * All other countries für einen Preis, der für jedes Land ohne eigene Zeile gilt. Länder ohne Preis (wenn keine *-Zeile vorhanden ist) erhalten keinen festen Tarif, daher wird die Methode für sie ausgeblendet.

Fixed price applies: Per order (Standard) berechnet den Preis einmal. Per item (price × quantity) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Live-Tarife von Aramex werden immer je Sendung berechnet.

Bedingungen

Minimum weight (kg): blendet die Methode unterhalb dieses Warenkorbgewichts aus. 0 bedeutet keine Grenze (Standard).

Maximum weight (kg): blendet die Methode oberhalb dieses Warenkorbgewichts aus. Standard: 100. 0 bedeutet keine Grenze. Lassen Sie das Feld leer, werden 100 kg verwendet.

Minimum order amount: zeigt die Methode nur an, wenn die Summe der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern) diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.

Free shipping: aktiviert kostenlose Aramex-Lieferung ab dem unten angegebenen Betrag.

Free shipping from: die Summe der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern), ab der die Lieferung kostenlos ist. Wird nur verwendet, wenn Free shipping aktiviert ist.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Aramex-Live-Tarife können die Mehrwertsteuer bereits enthalten. Wählen Sie dann No tax, damit die Steuer nicht doppelt auf den Versand erhoben wird.

Geo zone: bietet Aramex nur für Adressen in dieser Geozone an. All zones (Standard) bedeutet keine Begrenzung. Geozonen verwalten Sie unter System > Localisation > Geo Zones.

Countries: bietet Aramex nur für diese Zielländer an. Lassen Sie das Feld leer, um alle Länder zu erlauben. Diese Begrenzung gilt zusammen mit Geo zone.

Erweitert

Debug log: schreibt Tarifberechnungen und API-Fehler in storage/logs/vfd_armx_debug.log.php. Die Datei ist aus dem Web nicht lesbar. Passwörter, PIN und Kundenadressen werden nie protokolliert. Schalten Sie das Protokoll aus, wenn Sie fertig sind. Erreicht die Datei 5 MB, wird sie nach vfd_armx_debug.old.log.php verschoben und ein neues Protokoll begonnen.

Log: zeigt Größe und neueste Einträge des Debug-Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Remove data on uninstall: ist die Option eingeschaltet, löscht das Deinstallieren der Erweiterung die Aramex-Einstellungen, die zwischengespeicherten Tarife und das Protokoll. Ist sie aus (Standard), bleiben sie für eine erneute Installation erhalten.

Importieren / Exportieren

Exportieren: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Passwort und PIN werden nicht exportiert.

Importieren: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen, zum Beispiel in einem anderen Shop. Die Werte werden wie bei einem normalen Speichern geprüft. Das gespeicherte Passwort und die PIN bleiben erhalten.

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Aramex-Preis. Ist eine Geo zone gesetzt und liegt die Adresse außerhalb, wird Aramex nicht angeboten. Nur Produkte mit Requires Shipping auf Yes zählen: andere Produkte fügen kein Gewicht hinzu und sind nicht im Bestellwert enthalten. Danach prüft die Erweiterung die Bedingungen: erlaubte Länder, Warenkorbgewicht und Mindestbestellwert. Der Bestellwert ist der Preis der versandpflichtigen Produkte nach Abzug des Gutscheinrabatts und vor Steuern. Geschenkgutscheine, Bonuspunkte und Store-Guthaben werden nicht berücksichtigt. Gilt kostenloser Versand, beträgt der Preis 0, und es wird keine Anfrage an Aramex gesendet.

Im Modus mit festen Preisen wird der Preis aus der Tabelle entnommen. In den Live-Modi sendet die Erweiterung an Aramex die Herkunfts- und Lieferadresse, das abrechenbare Gewicht, den Dienst und Ihre Standardwährung und verwendet die zurückgegebene Gesamtsumme. Ein Live-Tarif wird nur angefragt, wenn die Lieferadresse eine Stadt oder Postleitzahl hat. Der Preis wird in Ihrer Standardwährung berechnet, auf deren Dezimalstellen gerundet und dem Kunden in seiner Währung angezeigt, mit der Steuer der gewählten Tax class.

Jede Antwort wird 1 Stunde zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird 10 Minuten zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf Aramex warten muss. Das API-Zeitlimit beträgt 10 Sekunden.

Gibt Aramex einen Fehler, einen Betrag von null oder ein Angebot in einer anderen Währung ohne Umrechnungskurs zurück, sieht der Kunde keine Fehlermeldung. Die Methode wird ausgeblendet, oder im Ersatzmodus wird der feste Preis verwendet. Der Grund wird im Debug-Protokoll notiert.

Die Erweiterung berechnet nur Tarife. Sie erstellt keine Aramex-Sendungen, druckt keine Etiketten, bucht keine Abholungen, verfolgt keine Pakete und lässt Kunden keine Aramex-Filiale wählen. Sie fügt Bestellungen nichts hinzu: Die Bestellung zeigt den Namen der Methode und die Versandkosten wie bei jeder anderen OpenCart-Versandart. Das Paket wird an Aramex immer als ein Stück gesendet.

Auf OpenCart 4 klicken Sie an der Kasse im Block der Versandart auf Choose und wählen im Fenster Shipping method options Aramex. Die Methode funktioniert genauso wie unter OpenCart 3.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Aramex steht als erster Block auf Extensions > Extensions > Shipping > VibeFox Aramex > Edit, über den Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: opencart-shipping-aramex und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Den Schlüssel können nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung ändern. Die Texte des Blocks folgen der Admin-Sprache (Englisch und Russisch sind enthalten).

Wenn der Schlüssel nicht akzeptiert wird, zeigt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet die Erweiterung mit dem zuletzt bekannten Status weiter.

Ein Schlüssel gilt für eine Domain: die Shop-Adresse aus der OpenCart-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird die Aramex-Versandart Kunden an der Kasse nicht angezeigt und es wird kein Tarif berechnet. Ein Admin-Benutzer, der im Admin-Bereich im selben Browser angemeldet ist, sieht die Versandart im Shop weiterhin, markiert als (unlicensed — visible to admins only), damit Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. Unter OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Versandart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint ein Hinweis auf dem Dashboard des Admin-Bereichs. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.

Wenn eine Lizenz abläuft, arbeitet die Erweiterung weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard des Admin-Bereichs oder die Seite Edit öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Beim Deinstallieren der Erweiterung werden immer der Lizenzschlüssel und der Lizenzstatus entfernt.

Fehlerbehebung

Aramex erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable Aramex eingeschaltet ist. Prüfen Sie Geo zone, Countries, die Gewichtsgrenzen und Minimum order amount. Prüfen Sie im Modus mit festen Preisen, ob das Land oder * All other countries einen Preis hat. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Live-Tarife erscheinen nicht: schalten Sie das Debug log ein, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Erweiterungsseite an. Es zeigt den Grund: fehlende API-Zugangsdaten, den Aramex-Fehlercode, keine Herkunftsstadt, keine Lieferstadt oder Postleitzahl, eine Gewichts- oder Betragsgrenze oder ein Angebot in einer anderen Währung. Mit Aramex live rates, fixed prices if the API fails erhalten Kunden weiterhin den festen Preis, während Sie das Problem beheben.

Fehler ERR75 im Protokoll: Aramex hat die Anmeldung abgelehnt. Prüfen Sie Benutzername, Passwort, Kontonummer, PIN, Standortcode und Ländercode mit Ihrem Aramex-Kundenbetreuer.

Angebot in einer anderen Währung wird abgelehnt: Aramex hat in einer anderen Währung als Ihrer Standardwährung geantwortet. Geben Sie Currency conversion rate ein oder bitten Sie Aramex, in Ihrer Währung anzubieten.

Steuer wird beim Versand doppelt berechnet: Aramex-Summen können bereits die Mehrwertsteuer enthalten. Setzen Sie Tax class auf No tax.

Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Erweiterungsseite auf Save. Dadurch werden die zwischengespeicherten Aramex-Tarife gelöscht.

Die Seite meldet "Warning: You do not have permission to modify VibeFox Aramex!": Ihre Admin-Benutzergruppe darf die Einstellungen möglicherweise nur ansehen. Geben Sie der Gruppe die Bearbeitungsberechtigung für extension/shipping/vfd_aramex (OpenCart 3) oder extension/vfd_aramex/shipping/vfd_aramex (OpenCart 4) unter System > Users > User Groups.

Für Entwickler: die Aramex-API-Adresse kann mit der Einstellung vfd_armx_api_url (für Tests) ersetzt werden; sie hat kein Feld auf der Einstellungsseite.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Aramex auf Uninstall (die rote −-Schaltfläche). OpenCart setzt Enable Aramex, Sort order, Tax class und Geo zone immer zurück. Die zwischengespeicherten Tarife werden immer entfernt. Ist Remove data on uninstall eingeschaltet, werden außerdem die Aramex-Einstellungen und das Debug-Protokoll gelöscht. Ist es aus, bleiben die übrigen Einstellungen erhalten und werden bei einer erneuten Installation wieder verwendet. Bestehende Bestellungen behalten ihre Versandart und Kosten.

Auf OpenCart 4 entfernen Sie die Dateien der Erweiterung ebenfalls, indem Sie nach der Deinstallation zu Extensions > Installer gehen, neben VibeFox Aramex in der Liste der installierten Erweiterungen auf Uninstall (die orangefarbene −-Schaltfläche) klicken und danach auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Aramex ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist weder mit Aramex verbunden noch von Aramex unterstützt.