VibeFox SMSA Express 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.

SMSA-Express-Preisliste: die Preise für die Preistabelle stammen aus Ihrem SMSA-Konto oder vom SMSA-Vertrieb. Geben Sie sie in der Standardwährung Ihres Shops ein. Ist Ihre Preisliste in SAR, AED oder einer anderen Währung, rechnen Sie sie zuerst um.

SMSA-passKey (nur für Live-Beträge): Live-Beträge nutzen den SMSA-Webservice (SECOM, Operation getShipCharges). SMSA stellt den passKey auf Anfrage aus: Fragen Sie Ihren SMSA-Kundenbetreuer oder schreiben Sie an info@smsaexpress.com. Der passKey kann vom API-Schlüssel des SMSA-E-Commerce-Portals abweichen. SMSA hat für diesen Dienst keinen Testserver (Sandbox).

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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 Paket für OpenCart 3 vfd_smsa_express-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_smsa_express.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 zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_smsa_express-oc3-(version).ocmod.zip. Die Erweiterung fügt keine OCMOD-Modifikationen hinzu, Sie müssen also Extensions > Modifications nicht aktualisieren. Statt des Installers können Sie auch den Inhalt des Ordners upload aus diesem Paket in das Stammverzeichnis Ihres Shops kopieren.

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

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

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

5. Tragen Sie Ihre SMSA-Express-Preise in die Preistabelle ein.

6. Optional: Aktivieren Sie unter Live rates (API) Live charges, geben Sie Ihren SMSA-passKey, die Versandstadt und das Versandland ein und, falls die Standardwährung Ihres Shops nicht SAR ist, den Wechselkurs.

7. Aktivieren Sie Enable SMSA Express und klicken Sie auf Save.

OpenCart 4

1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_smsa_express.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Erweiterungscode 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 SMSA Express, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-Schaltfläche).

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

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

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit. Die Abschnitte sind links aufgelistet. Eine Schaltfläche Save speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht außerdem die zwischengespeicherten SMSA-Beträge. Ein ungültiger Methodentitel, ein Wert, der keine Zahl ist, eine negative Zahl, ein Wechselkurs von 0, ein Währungscode, der nicht aus 3 Buchstaben besteht, ein falscher Preis in der Tabelle, ein Minimum weight (kg) über dem Maximum weight (kg) oder eine Sortierreihenfolge, die keine ganze Zahl ist, wird mit einem Fehler abgelehnt, und nichts wird gespeichert, bis Sie es korrigieren. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Sind Live-Beträge aktiv, weisen Warnungen oberhalb der Einstellungen auf einen fehlenden passKey, eine fehlende Versandstadt oder einen fehlenden Wechselkurs oder auf eine leere Preistabelle hin. Eine Warnung erscheint auch, wenn der Shop keine kg-Gewichtsklasse hat und seine Standardgewichtseinheit der Erweiterung unbekannt ist (Produktgewichte werden dann als kg gelesen). Fügen Sie unter System > Localisation > Weight Classes eine kg-Gewichtsklasse hinzu.

Allgemein

Die Einstellungen gelten für jede Geozone. Sie können die Methode unter Conditions auf eine Geozone oder mit Ignore shipping zones auf eine Ländliste beschränken.

Enable SMSA Express: blendet SMSA Express 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: SMSA Express. Pflichtfeld, höchstens 64 Zeichen, ohne die Zeichen < > ; = # { }.

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

Live-Tarife (API) (optional; gibt SMSA keinen Betrag zurück, wird die Preistabelle verwendet)

Live charges: holt den Versandbetrag von SMSA Express. Ist es aus, wird an der Kasse nichts an SMSA gesendet. Standard: aus.

SMSA passKey: der Schlüssel des SMSA-Webservice (SECOM). 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. Aktivieren Sie Remove the saved passKey, um ihn zu löschen. Zeigt das Protokoll "Invalid Passkey", akzeptiert dieser Dienst den Schlüssel nicht. Fragen Sie SMSA nach einem passKey für den Webservice.

Ship-from city: die Stadt, von der Ihre Pakete versandt werden, so geschrieben, wie SMSA sie schreibt, zum Beispiel Riyadh, Jeddah oder Dammam. Für Live-Beträge erforderlich: OpenCart hat keine Shop-Stadt, daher wird sie nie aus der Shop-Adresse übernommen.

Ship-from country: das Land, aus dem Ihre Pakete versandt werden. Die erste Option, Store country, verwendet das Land Ihres Shops aus System > Settings > Store > Local. Dies ist der Standard.

Shipment type: wird als Sendungsart an SMSA übermittelt. DLV (der Standard) ist Standardzustellung. Ändern Sie es nur, wenn SMSA Ihnen einen anderen Code gegeben hat.

Currency of SMSA charges: der 3-Buchstaben-Code der Währung, in der SMSA Beträge zurückgibt, meist SAR (der Standard). Ein Betrag in einer anderen Währung als dieser oder der Standardwährung Ihres Shops wird nicht verwendet.

Exchange rate: der Preis von 1 Einheit der SMSA-Währung in der Standardwährung Ihres Shops, zum Beispiel 0.27. Nicht nötig, wenn beide Währungen gleich sind. Ohne ihn werden Beträge in einer anderen Währung nicht verwendet, und die Preistabelle gilt.

Preise (Ihre SMSA-Express-Preisliste in der Standardwährung Ihres Shops; wird verwendet, wenn Live-Beträge aus sind, und als Ersatz, wenn SMSA keinen Betrag liefert)

Price table: eine Zeile pro Zielland. Klicken Sie auf Add country, um eine Zeile hinzuzufügen. Die Zeile * All other countries gilt für Länder ohne eigene Zeile. Jede Zeile hat einen Base-Preis und Gewichtsspalten: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg und XL >5 kg. Eine leere oder mit 0 gefüllte Gewichtsspalte verwendet den Grundpreis. Ein Grundpreis von 0 bedeutet kostenlosen Versand. Zeilen ohne Preis werden nicht gespeichert. Hat ein Land zwei Zeilen, wird die erste verwendet. Sowohl "9.99" als auch "9,99" werden akzeptiert.

Price for countries not in the table: wird verwendet, wenn die Tabelle für das Zielland keine Zeile hat (und keine *-Zeile) oder die Zeile für dieses Gewicht keinen Preis hat. Lassen Sie das Feld leer, um die Methode in diesem Fall auszublenden.

Price applies: wie der Preis berechnet wird.

Produktgewichte werden von ihrer OpenCart-Gewichtsklasse in Kilogramm umgerechnet.

Bedingungen

Minimum weight (kg): blendet die Methode aus, wenn der Warenkorb weniger wiegt. 0 bedeutet keine Grenze (Standard).

Maximum weight (kg): blendet die Methode aus, wenn der Warenkorb mehr wiegt. Standard: 30. 0 oder ein leeres Feld bedeutet keine Grenze.

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

Free shipping from: die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern), ab der der Versand mit SMSA Express kostenlos ist. Erreicht der Warenkorb sie, beträgt der Preis 0, und es geht keine Anfrage an SMSA. Lassen Sie das Feld leer, um nie kostenlosen Versand anzubieten.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Wählen Sie No tax, wenn Ihre Preise (die Tabelle und die SMSA-Beträge) bereits Steuern enthalten, zum Beispiel saudische MwSt.

Geo zone: bietet SMSA Express nur für Adressen in dieser Geozone an. All zones (Standard) bedeutet keine Einschränkung. Wird nicht geprüft, während Ignore shipping zones aktiv ist. Geozonen verwalten Sie unter System > Localisation > Geo Zones.

Verfügbarkeit ohne Versandzonen

Normalerweise wird die Methode für Adressen der Geozone angeboten, die unter Conditions gewählt ist.

Ignore shipping zones: bietet SMSA Express für die unten genannten Länder an, unabhängig von der Geozone. Ist es aus, entscheidet die Geozone, und die Ländliste wird nicht verwendet.

Countries: die Zielländer für diesen Modus. Lassen Sie das Feld leer, um alle im Shop aktivierten Länder zu verwenden. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiv ist.

Erweitert

Debug log: protokolliert Tarifberechnungen in storage/logs/vfd_smsa_debug.log.php. Die Datei kann nicht über das Web gelesen werden. Kundenadressen und Schlüssel werden nicht protokolliert. Fehler bei Live-Beträgen werden immer protokolliert, auch wenn diese Option aus ist. Schalten Sie das Protokoll aus, wenn Sie fertig sind. Erreicht die Datei 5 MB, wird sie nach vfd_smsa_debug.old.log.php verschoben und ein neues Protokoll begonnen.

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

Remove data on uninstall: wenn aktiviert, löscht das Deinstallieren der Erweiterung die SMSA-Express-Einstellungen und das Debug-Protokoll. Wenn deaktiviert (Standard), bleiben die Einstellungen für eine Neuinstallation erhalten. Zwischengespeicherte Beträge werden immer entfernt.

Import / Export

Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Der passKey wird nicht exportiert.

Import: 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. Der gespeicherte passKey bleibt erhalten.

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem SMSA-Express-Preis. Ist eine Geo zone gesetzt (und Ignore shipping zones deaktiviert) und liegt die Adresse außerhalb, wird SMSA Express nicht angeboten. Nur Produkte mit Requires Shipping auf Yes zählen: andere Produkte fügen kein Gewicht hinzu und sind nicht im Bestellwert enthalten. Die Erweiterung prüft dann die Bedingungen: die Länder von Ignore shipping zones (falls aktiv), das Warenkorbgewicht und den Mindestbestellwert. Geschenkgutscheine, Bonuspunkte und Store-Guthaben werden nicht berücksichtigt. Gilt kostenloser Versand, beträgt der Preis 0, und es geht keine Anfrage an SMSA.

Mit aktiven Live-Beträgen sendet die Erweiterung an SMSA die Versandstadt und das Versandland, Stadt und Land des Kunden, die Sendungsart, das Paketgewicht in kg und einen Nachnahmebetrag von 0. SMSA antwortet mit dem Betrag und seiner Währung. Die Erweiterung rechnet ihn in die Standardwährung Ihres Shops um und rundet auf dessen Dezimalstellen. Der Preis wird dann in der Währung des Kunden mit der Steuer der gewählten Tax class angezeigt. Ein Live-Betrag wird erst angefordert, nachdem der Kunde eine Lieferadresse mit Stadt eingegeben hat.

Jeder Betrag wird eine Stunde lang zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird 5 Minuten lang zwischengespeichert. Nach einem Timeout oder Serverfehler wird SMSA 2 Minuten lang nicht erneut gefragt. Nach einem abgelehnten Schlüssel wird SMSA 5 Minuten lang nicht erneut gefragt. So wartet die Kasse bei jeder Aktualisierung nie auf einen ausfallenden Dienst. Das Anfrage-Timeout beträgt 12 Sekunden.

Wenn SMSA keinen brauchbaren Betrag zurückgibt (kein passKey, noch keine Stadt eingegeben, ein ungültiger Schlüssel, ein Timeout, ein Fehler, kein Dienst in die Stadt oder eine unbekannte Währung), wird die Preistabelle verwendet. Liefern die Tabelle und Price for countries not in the table keinen Preis, wird die Methode ausgeblendet. Der Kunde sieht nie einen Fehler. Der Grund wird im Protokoll festgehalten.

Die Erweiterung berechnet nur den Versandpreis. Sie erstellt keine SMSA-Sendungen, druckt keine AWB-Etiketten, verwaltet keine Retouren und verfolgt keine Pakete. Nachnahme und ihre Gebühr sind im Live-Betrag nicht enthalten. Es gibt keine Auswahl von SMSA-Filialen: Die Methode ist Zustellung an die Haustür. Sie fügt den Bestellungen nichts hinzu: Die Bestellung zeigt den Methodentitel und die Versandkosten wie jede andere OpenCart-Versandart.

In OpenCart 4 klickt der Kunde im Block der Versandarten auf der Kassenseite auf Choose und wählt im Fenster Shipping method options SMSA Express aus. Die Methode funktioniert genauso wie in OpenCart 3.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox SMSA Express ist der erste Block auf Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gilt, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-shipping-smsa-express und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Berechtigung Modify für die Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Admin-Sprache (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, nennt 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 Domainplatz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet die Erweiterung mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert auf einer Domain: der Shop-Adresse aus der OpenCart-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird SMSA Express Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Ein Admin-Benutzer, der im Admin im selben Browser angemeldet ist, sieht die Methode im Shop weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. In OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Methode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint eine Erinnerung auf dem Dashboard im Admin. Schließen Sie sie mit ×, um sie 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.

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

Fehlerbehebung

SMSA Express erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable SMSA Express eingeschaltet ist. Prüfen Sie Geo zone (oder bei aktivem Ignore shipping zones Countries), die Gewichtsgrenzen und den Minimum order amount. Prüfen Sie, ob das Land oder * einen Preis hat oder Price for countries not in the table gesetzt ist. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Kunden sehen den Tabellenpreis statt des SMSA-Betrags: SMSA braucht die Stadt des Kunden, daher wird bis zu ihrer Eingabe der Tabellenpreis angezeigt. Die Tabelle wird auch verwendet, wenn SMSA nicht antwortet, den Schlüssel oder die Stadt ablehnt oder den Betrag in einer Währung ohne Wechselkurs liefert. Sehen Sie im Feld Log auf der Erweiterungsseite nach dem Grund.

"Invalid Passkey" im Protokoll: der Schlüssel wird vom SMSA-Webservice nicht akzeptiert. Fragen Sie SMSA nach einem passKey für den Webservice.

Die Stadt des Kunden wird nicht akzeptiert: SMSA erwartet die eigene Schreibweise der Städte. Prüfen Sie die Stadt in der Lieferadresse und die Ship-from city.

Die Einstellungen werden nicht gespeichert, und ein Fehler wird angezeigt: ein Zahlenfeld enthält Text oder einen negativen Wert, der Wechselkurs ist 0, der Währungscode hat nicht 3 Buchstaben oder Minimum weight (kg) liegt über Maximum weight (kg). Korrigieren Sie den in der Meldung genannten Wert und klicken Sie erneut auf Save.

Steuer wird auf den Versand doppelt berechnet: Ihre Preisliste oder die SMSA-Beträge enthalten möglicherweise bereits MwSt. Setzen Sie Tax class auf No tax.

Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Erweiterungsseite auf Save. Das löscht die zwischengespeicherten SMSA-Beträge.

Die Seite zeigt "Warning: You do not have permission to modify VibeFox SMSA Express!": Ihre Admin-Benutzergruppe darf die Einstellungen womöglich nur ansehen. Geben Sie der Gruppe die Berechtigung zum Ändern für extension/shipping/vfd_smsa_express (OpenCart 3) oder extension/vfd_smsa_express/shipping/vfd_smsa_express (OpenCart 4) unter System > Users > User Groups.

Für Entwickler: die Adresse des SMSA-Webservice kann über die Einstellung vfd_smsa_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 SMSA Express auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable SMSA Express, Sort order, Tax class und Geo zone zurück. Die zwischengespeicherten Beträge werden immer entfernt. Ist Remove data on uninstall aktiviert, werden auch die SMSA-Express-Einstellungen und das Debug-Protokoll gelöscht. Ist es deaktiviert, bleiben die übrigen Einstellungen erhalten und werden bei einer Neuinstallation wieder verwendet. Bestehende Bestellungen behalten ihre Versandart und ihre Kosten.

Um bei OpenCart 4 auch die Dateien der Erweiterung zu entfernen, gehen Sie nach der Deinstallation zu Extensions > Installer, klicken Sie in der Liste der installierten Erweiterungen neben VibeFox SMSA Express auf Uninstall (die orangefarbene −-Schaltfläche) und dann auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

SMSA Express ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist weder mit SMSA Express verbunden noch von SMSA Express empfohlen.