VibeFox SMSA Express for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

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

SMSA-passKey (nur für Live-Tarife): Live-Tarife 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 und bitten Sie um Zugang zum SMSA-Webservice unter Angabe Ihrer Kontonummer. Der passKey kann sich vom API-Schlüssel des SMSA-E-Commerce-Portals unterscheiden. SMSA hat für diesen Dienst keinen Testserver (Sandbox).

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

Installation

1. Gehen Sie im Back Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox SMSA Express in der Modulliste und klicken Sie dort auf Configure.

3. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Konfigurationsseite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Tragen Sie Ihre SMSA-Express-Preise in die Preistabelle ein und klicken Sie auf Save.

5. Optional: Aktivieren Sie unter Live rates (API) die Option 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.

Bei der Installation legt das Modul den Versanddienstleister SMSA Express mit dem Lieferzeittext SMSA Express courier an. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugewiesen. Zonen, Kundengruppen, Lieferzeit, Logo und Größenbeschränkungen können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis stammt immer vom Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox SMSA Express > Configure. Jeder Bereich hat eine eigene Schaltfläche Save, die die ganze Seite speichert. Jedes Speichern leert außerdem die zwischengespeicherten SMSA-Tarife. Ein Wert, der keine Zahl ist, eine negative Zahl, ein Wechselkurs von 0, ein Währungscode, der nicht aus 3 Buchstaben besteht, oder ein Minimum weight, das über dem Maximum weight liegt, wird mit einer Fehlermeldung abgelehnt. Nichts wird gespeichert, bis Sie den Wert korrigieren.

Bei aktivierten Live-Tarifen weisen Hinweise oberhalb der Einstellungen auf einen fehlenden passKey, eine fehlende Versandstadt, einen fehlenden Wechselkurs oder eine leere Preistabelle hin. Eine Warnung erscheint auch, wenn die Gewichtseinheit des Shops dem Modul nicht bekannt ist (Produktgewichte werden dann als kg gelesen). Stellen Sie kg, g, lb oder oz unter International > Localization (Local units) ein.

Allgemein

Enable SMSA Express: schaltet den Versanddienstleister in allen Zonen gleichzeitig ein oder aus. Das ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Method title: der Name des Versanddienstleisters, der im Warenkorb und an der Kasse angezeigt wird. Standard: SMSA Express. Pflichtfeld, bis zu 64 Zeichen.

Tax: die Steuerregel des Versanddienstleisters oder No tax. Wählen Sie No tax, wenn Ihre Preise (die Tabelle und die SMSA-Tarife) bereits Steuern enthalten, zum Beispiel die saudi-arabische Mehrwertsteuer (VAT).

Live-Tarife (API) (optional; wenn SMSA keinen Tarif liefert, wird die Preistabelle verwendet)

Live charges: Versandkosten von SMSA Express abrufen. Standard: aus.

SMSA passKey: der Schlüssel des SMSA-Webservices (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. Setzen Sie den Haken bei Remove the saved passKey, um ihn zu löschen. Wenn das Protokoll "Invalid Passkey" anzeigt, 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 versendet werden, so geschrieben, wie SMSA sie schreibt, zum Beispiel Riyadh, Jeddah oder Dammam. Lassen Sie das Feld leer, um die Shop-Stadt aus Shop Parameters > Contact > Stores zu verwenden.

Ship-from country: das Land, von dem Ihre Pakete versendet werden. Standardmäßig ist es das Land Ihres Shops.

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

Currency of SMSA charges: SMSA liefert jeden Tarif mit seinem Währungscode, meist SAR (der Standard). Ein Tarif 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 Tarife in einer anderen Währung nicht verwendet, und die Preistabelle gilt. Als Dezimaltrennzeichen werden Punkt und Komma akzeptiert.

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

Price table: eine Zeile pro Zielland. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorb-Symbol, um eine zu entfernen. Die Zeile * Default (all other countries) gilt für Länder ohne eigene Zeile. Jede Zeile hat einen Grundpreis und Gewichtsspalten: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg und XL über 5 kg. Eine leere oder mit 0 gefüllte Gewichtsspalte verwendet den Grundpreis. Ein Grundpreis von 0 bedeutet kostenlosen Versand. Zeilen ohne jeden 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 (auch keine * Zeile) oder die Zeile für dieses Gewicht keinen Preis hat. Lassen Sie das Feld leer, um den Versanddienstleister in diesem Fall auszublenden.

Price applies: wie der Preis berechnet wird.

Produktgewichte werden von der Gewichtseinheit Ihres Shops in Kilogramm umgerechnet.

Bedingungen

Minimum weight: blendet den Versanddienstleister aus, wenn der Warenkorb weniger wiegt, in kg. 0 bedeutet keine Grenze.

Maximum weight: blendet den Versanddienstleister aus, wenn der Warenkorb mehr wiegt, in kg. Standard: 30. 0 oder ein leeres Feld bedeutet keine Grenze.

Minimum order amount: zeigt den Versanddienstleister nur an, wenn die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern) diesen Betrag erreicht. Lassen Sie das Feld leer, um ihn immer anzuzeigen.

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

Verfügbarkeit ohne Versandzonen

Normalerweise wird der Versanddienstleister in den Zonen angeboten, denen er unter Shipping > Carriers zugewiesen ist.

Ignore shipping zones: bietet SMSA Express für die unten angegebenen Länder an, unabhängig davon, welche Zone passt. Solange dies aktiv ist, wird der Versanddienstleister allen Zonen hinzugefügt, auch später erstellten. Wenn Sie es ausschalten, werden diese hinzugefügten Zonen wieder entfernt.

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

Erweitert

Debug log: protokolliert die Tarifberechnungen in logs/vfd_smsa_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Kundenadressen und Schlüssel werden nicht protokolliert. Fehler bei Live-Tarifen werden immer protokolliert, auch wenn diese Option aus ist. Schalten Sie das Protokoll aus, wenn Sie fertig sind.

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 aktiv, löscht die Deinstallation des Moduls die SMSA-Express-Einstellungen, den Versanddienstleister und das Protokoll. Wenn aus, bleibt alles für eine erneute Installation erhalten. Zwischengespeicherte Tarife werden immer entfernt.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem SMSA-Express-Preis. Nur physische Produkte zählen: Virtuelle Produkte bringen kein Gewicht mit und sind nicht im Bestellwert enthalten. Das Modul prüft zuerst die Bedingungen: die Länder von Ignore shipping zones (falls aktiv), das Warenkorbgewicht und den Mindestbestellwert. Gilt kostenloser Versand, beträgt der Preis 0 und es wird keine Anfrage an SMSA gesendet.

Bei aktiven Live-Tarifen sendet das Modul an SMSA Ihre Versandstadt und Ihr Versandland, die Stadt und das Land des Kunden, die Sendungsart, das Paketgewicht in kg und einen Nachnahmebetrag von 0. SMSA antwortet mit dem Tarif und seiner Währung. Das Modul rechnet ihn in die Standardwährung Ihres Shops um, und der Preis wird danach in der Warenkorbwährung des Kunden angezeigt. Ein Live-Tarif wird erst angefragt, nachdem der Kunde eine Lieferadresse mit einer Stadt eingegeben hat.

Jeder Tarif 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 zwei Minuten lang nicht erneut gefragt. Nach einem abgelehnten Schlüssel wird fünf Minuten lang nicht erneut gefragt. So wartet die Kasse bei jeder Aktualisierung nie auf einen fehlerhaften Dienst. Das Zeitlimit der Anfrage beträgt 12 Sekunden.

Wenn SMSA keinen verwendbaren Tarif liefert (kein passKey, noch keine Stadt eingegeben, fehlende Produktgewichte, ein ungültiger Schlüssel, ein Timeout, ein Fehler, kein Service in die Stadt oder eine unbekannte Währung), wird die Preistabelle verwendet. Wenn Tabelle und Price for countries not in the table keinen Preis ergeben, wird der Versanddienstleister ausgeblendet. Der Kunde sieht nie einen Fehler. Der Grund wird im Protokoll festgehalten.

Wenn Sie den Versanddienstleister unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul übernimmt die neue Version automatisch.

Das Modul berechnet nur den Versandpreis. Es erstellt keine SMSA-Sendungen, druckt keine AWB-Etiketten, bearbeitet keine Rücksendungen und verfolgt keine Pakete. Nachnahme und ihre Gebühr sind nicht im Live-Tarif enthalten. Es gibt keine Auswahl einer SMSA-Verkaufsstelle: Der Versanddienstleister ist Haustürzustellung.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox SMSA Express ist der erste Block auf Modules > Module Manager > VibeFox SMSA Express > Configure, oberhalb der 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: presta-shipping-smsa-express und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Den Schlüssel können nur Mitarbeiter ändern, die die Berechtigung Configure für das Modul haben. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Ist der Schlüssel nicht gültig, 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. Nach einer Änderung der Shop-Adresse oder nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-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 der Versanddienstleister SMSA Express an der Kasse nicht angezeigt und kein Tarif berechnet. Die Kundenseite von PrestaShop weiß nicht, dass Sie im Back Office angemeldet sind, daher ist der Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, an der Kasse aber nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird während der Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls 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 unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe des Kunden abdeckt (oder ob Ignore shipping zones aktiv und das Land erlaubt ist). Prüfen Sie die Gewichtsgrenzen und Minimum order amount. Prüfen Sie, ob das Land oder * einen Preis hat oder ob Price for countries not in the table gesetzt ist. Außerdem können Produkte auf der Produktseite auf bestimmte Versanddienstleister beschränkt sein.

Kunden sehen den Tabellenpreis statt des SMSA-Tarifs: SMSA benötigt die Stadt des Kunden, deshalb wird bis zu deren Eingabe der Tabellenpreis angezeigt. Die Tabelle wird auch verwendet, wenn SMSA nicht antwortet, den Schlüssel oder die Stadt ablehnt oder den Tarif in einer Währung ohne Wechselkurs liefert. Den Grund finden Sie im Feld Log auf der Modulseite.

"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 Stadt. Prüfen Sie die Stadt in der Lieferadresse und die Ship-from city.

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

Die Steuer auf den Versand wird doppelt berechnet: Ihre Preisliste oder die SMSA-Tarife enthalten möglicherweise bereits die Mehrwertsteuer. Setzen Sie Tax auf No tax.

Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten SMSA-Tarife geleert.

Die Seite meldet, dass der Versanddienstleister SMSA Express nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn neu anzulegen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox SMSA Express und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Tarife werden immer entfernt. Ist Remove data on uninstall aktiv, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen und das Protokoll werden entfernt. Ist es aus, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Eine erneute Installation des Moduls oder ein Reset gibt dem Versanddienstleister den Status zurück, den er vorher hatte.

SMSA Express ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit SMSA Express verbunden und wird nicht von SMSA Express unterstützt.