VibeFox ShipStation 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.

ShipStation-Konto: verbinden Sie Ihre Versanddienstleister in ShipStation (Settings > Shipping > Carriers) und kopieren Sie dann API Key und API Secret unter ShipStation > Settings > Account > API Settings. Der API-Zugang hängt von Ihrem ShipStation-Tarif ab. Die Erweiterung verwendet die ShipStation API V1 (API Key und API Secret). Ohne Schlüssel werden nur die Ersatzpreise verwendet.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer Domain.

Installation

Der Download ist eine einzige 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_shipstation-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_shipstation.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_shipstation-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 ShipStation 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. Fügen 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. Fügen Sie API Key und API Secret ein, geben Sie die Versand-Postleitzahl ein und klicken Sie auf Save. Die Seite listet nun die Carrier-Codes Ihres Kontos auf. Tragen Sie den oder die gewünschten unter Carrier codes ein und speichern Sie erneut.

6. Wenn die Standardwährung Ihres Shops nicht die Währung Ihres ShipStation-Kontos ist, setzen Sie Exchange rate. Optional können Sie die Ersatzpreise ausfüllen.

7. Aktivieren Sie Enable ShipStation shipping 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_shipstation.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 ShipStation, klicken Sie auf Install (die grüne +-Schaltfläche) und danach 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 sie einschalten und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die von Ihnen behaltenen ShipStation-Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox ShipStation > Edit. Die Abschnitte sind links aufgelistet. Eine Schaltfläche Save speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht die zwischengespeicherten ShipStation-Tarife und prüft API Key und API Secret. Die Seite zeigt dann die mit Ihrem Konto verbundenen Versanddienstleister mit ihren Codes, zum Beispiel "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Warnungen oben auf der Seite zeigen an, wann Live-Tarife nicht funktionieren können: keine Schlüssel, kein Carrier-Code, keine Versand-Postleitzahl, kein Wechselkurs, eine fehlgeschlagene Verbindungsprüfung oder Carrier-Codes, die nicht mit Ihrem Konto verbunden sind. Eine Warnung erscheint auch, wenn die Gewichts- oder Längeneinheit des Shops nicht umgerechnet werden kann. Verwenden Sie kg, g, lb oder oz sowie cm, mm, m oder in (System > Settings > Option). Ein ungültiger Name, ein Zahlenfeld oder eine Preiszelle mit negativem Wert oder mit Text statt einer Zahl, ein Minimum weight über dem Maximum weight oder eine Sortierreihenfolge, die keine ganze Zahl ist, wird als Fehler gemeldet, und es wird nichts gespeichert.

Allgemein

Enable ShipStation shipping: blendet die Methode an der Kasse ein oder aus. Dies ist der Status der Erweiterung unter Extensions > Extensions > Shipping.

Name: der Name der Versandart, den der Kunde an der Kasse sieht. Standard: ShipStation Shipping. Pflichtfeld, höchstens 64 Zeichen, ohne die Zeichen < > ; = # { }.

Tax class: die Steuerklasse der Versandkosten oder No tax. ShipStation-Tarife enthalten keine Umsatzsteuer. No tax zeigt sie wie angeboten an; eine Steuerklasse fügt dem Versand gemäß Ihren Steuerregeln Steuern hinzu.

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

ShipStation-Konto

API Key: der API Key aus ShipStation > Settings > Account > API Settings. Er wird nur an ShipStation gesendet und nie protokolliert. 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.

API Secret: das API Secret von derselben Seite. Es wird genauso behandelt wie der Key.

Remove the saved API key and secret: erscheint, sobald Schlüssel gespeichert sind. Aktivieren und speichern Sie, um beide zu entfernen.

Carrier codes: ein oder mehrere ShipStation-Carrier-Codes, durch Kommas getrennt, zum Beispiel stamps_com, ups_walleted. Es werden bis zu 5 Codes verwendet, mit einer API-Anfrage pro Carrier. Wenn Sie mehr eingeben, werden nur die ersten 5 behalten, und die Seite weist Sie darauf hin. Angezeigt wird der günstigste Tarif dieser Carrier. Die Codes entnehmen Sie der Liste, die nach dem Speichern erscheint.

Allowed services: optional, durch Kommas getrennte ShipStation-Service-Codes, zum Beispiel usps_priority_mail, ups_ground. Lassen Sie das Feld leer, um den günstigsten Service der oben genannten Carrier anzuzeigen.

Package code: "package" (der Standard) berechnet Tarife für Ihren eigenen Karton und lässt Umschläge und Flatrate-Boxen der Carrier aus. Lassen Sie das Feld leer, um jeden vom Carrier angebotenen Pakettyp zu bewerten.

Versand von

Ship-from postal code: für Live-Tarife erforderlich, zum Beispiel 78703. ShipStation berechnet Tarife nur anhand der Postleitzahl, und diese muss im Land Ihres ShipStation-Kontos liegen. OpenCart hat keine Shop-Postleitzahl, daher wird sie nie aus der Shop-Adresse übernommen.

Tarife

Parcels: wie der Warenkorb an ShipStation gesendet wird.

One parcel per order (the cart is packed into one box): alle Artikel werden in einem Karton gestapelt und einmal bewertet. Dies ist der Standard.

One parcel per item (every unit ships in its own box): jedes Produkt wird als eigenes Paket bewertet, und der Tarif wird für jede Einheit berechnet. Ersatzpreise werden ebenfalls pro Einheit berechnet.

ShipStation account currency: die Währung, in der ShipStation Tarife zurückgibt: USD, CAD, GBP, AUD, NZD oder EUR. Standard: USD (US-Konten).

Exchange rate: der Preis von 1 Einheit der Kontowährung in der Standardwährung Ihres Shops, zum Beispiel 0.92. Nur nötig, wenn sich die Standardwährung von der Kontowährung unterscheidet. Ohne ihn werden Live-Tarife nicht verwendet, und es gelten die Ersatzpreise. Wechselkurse werden nicht automatisch aktualisiert.

Fallback prices (werden verwendet, wenn kein Live-Tarif vorliegt: keine API-Schlüssel, ShipStation nicht erreichbar oder keine Carrier-Tarife für die Adresse; Preise in der Standardwährung Ihres Shops; lassen Sie die Tabelle und Other countries leer, um die Methode in diesem Fall auszublenden)

Prices by country: eine Tabelle mit einem Base-Preis pro Land und Größenspalten nach Paketgewicht: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg und XL über 5 kg. Klicken Sie auf Add country, um eine Zeile hinzuzufügen. Eine leere Größe verwendet den Grundpreis. Ein Grundpreis von 0 bedeutet kostenlosen Versand. Die Zeile * Default (all other countries) gilt für Länder ohne eigene Zeile. Eine Zeile ohne Preis wird nicht gespeichert.

Other countries: der Preis, wenn die Tabelle für das Land keinen Preis hat. Lassen Sie das Feld leer, um die Methode in diesem Fall auszublenden.

Bedingungen

Free shipping from: die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern), ab der der Versand kostenlos ist. Dann wird keine ShipStation-Anfrage gestellt. Lassen Sie das Feld leer, um es zu deaktivieren.

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

Minimum weight: das minimale Warenkorbgewicht in der Gewichtseinheit Ihres Shops (im Feldnamen angezeigt), damit die Methode erscheint. 0 bedeutet keine Grenze (Standard).

Maximum weight: die Methode wird oberhalb dieses Warenkorbgewichts in der Gewichtseinheit Ihres Shops ausgeblendet. 0 bedeutet keine Grenze (Standard).

Verfügbarkeit

Geo zone: bietet die Methode 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.

Ignore shipping zones: bietet die Methode für die unten genannten Länder an, unabhängig von der Geozone.

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

Erweitert

Debug log: protokolliert ShipStation-Anfragen in storage/logs/vfd_shst_debug.log.php (auf OpenCart 4 system/storage/logs/vfd_shst_debug.log.php). Die Datei kann nicht über das Web gelesen werden. API-Fehler werden immer protokolliert, auch wenn diese Option aus ist. API Key, API Secret und Kundenadressen werden nie protokolliert. Die Postleitzahl wird maskiert. Erreicht die Datei 5 MB, wird sie nach vfd_shst_debug.old.log.php verschoben und ein neues Protokoll begonnen.

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

Remove data on uninstall: wenn aktiviert, löscht das Deinstallieren der Erweiterung die ShipStation-Einstellungen und das Protokoll. Wenn deaktiviert (Standard), bleiben sie für eine Neuinstallation erhalten. Zwischengespeicherte Tarife werden immer entfernt. Der ShipStation-Service bereits aufgegebener Bestellungen bleibt immer erhalten.

Import / Export

Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. API Key und API Secret werden 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. Gespeicherter API Key und API Secret bleiben erhalten.

So funktioniert es an der Kasse

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

Die Erweiterung sendet dann an ShipStation die Versand-Postleitzahl, das Zielland, den Bundesstaat, die Stadt und die Postleitzahl, das Paketgewicht und die Kartongröße. Vor der Eingabe einer Postleitzahl durch den Kunden erfolgt keine Anfrage. Länder ohne Postleitzahlen erhalten die Ersatzpreise. Artikel werden in einem Karton gestapelt. Hat ein Produkt keine Abmessungen, wird das Paket nur nach Gewicht bewertet.

ShipStation wird einmal pro Carrier-Code abgefragt. Die Erweiterung verwendet den günstigsten erlaubten Tarif, umgerechnet in die Standardwährung Ihres Shops und auf dessen Dezimalstellen gerundet. Der Preis wird dann in der Währung des Kunden mit der Steuer der gewählten Tax class angezeigt.

Jede Antwort wird 1 Stunde lang zwischengespeichert. Antwortet ShipStation ohne brauchbaren Tarif, wird diese Antwort 10 Minuten lang gemerkt. Lehnt ShipStation die Schlüssel ab oder ist es nicht erreichbar, werden Anfragen 5 Minuten lang pausiert. Nach einem Ratenlimit richtet sich die Pause nach der Rücksetzzeit von ShipStation. Das Anfrage-Timeout beträgt 12 Sekunden.

Gibt es keinen Live-Tarif, stammt der Preis aus der Ersatztabelle und danach aus Other countries. Trifft nichts davon zu, wird die Methode ausgeblendet. Der Kunde sieht nie ShipStation-Fehlermeldungen. Details gehen in das Debug-Protokoll.

Die Erweiterung berechnet nur Tarife. Sie kauft keine Etiketten, legt keine ShipStation-Bestellungen oder -Sendungen an, verfolgt keine Pakete und verwaltet keine Retouren. Es gibt keine Abholstellen, keine Auswahl zwischen mehreren Services an der Kasse, keine Adressprüfung, keine Versicherung, keine Unterschriftsbestätigung, kein Packen in mehrere Pakete und keinen Tarifaufschlag.

Auf OpenCart 4 klickt der Kunde im Block der Versandart auf der Kassenseite auf Choose und wählt im Fenster Shipping method options ShipStation aus. Die Methode funktioniert genauso wie unter OpenCart 3.

Bestellungen

Wird eine Bestellung mit einem Live-ShipStation-Tarif aufgegeben, wird der gewählte Service mit der Bestellung gespeichert. Öffnen Sie die Bestellung unter Sales > Orders: Der Bereich ShipStation oberhalb des Bestellverlaufs zeigt ihn als Service, zum Beispiel "USPS Ground Advantage - Package", damit Sie das passende Etikett in ShipStation erstellen können. Im Modus pro Artikel werden die Services durch Kommas getrennt aufgelistet. Spätere Änderungen am Warenkorb ändern sie nicht, und der Bereich wird auch angezeigt, nachdem Sie die Methode ausgeschaltet haben. Bestellungen mit Ersatzpreis oder kostenlosem Versand haben keinen ShipStation-Bereich.

OpenCart 4 behält eine Bestellung für die Kasse und aktualisiert sie jedes Mal, wenn der Kunde erneut bestätigt. Der gespeicherte ShipStation-Service wird damit aktualisiert. Wechselt der Kunde zu einer anderen Versandart oder gilt jetzt der Ersatzpreis, wird der gespeicherte Service aus der Bestellung entfernt.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox ShipStation ist der erste Block auf Extensions > Extensions > Shipping > VibeFox ShipStation > 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 aktiv 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-shipstation 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. 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 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 Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird ShipStation 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. Auf 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 auf dem Dashboard des Admins ein Hinweis. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard des Admins oder die Seite Edit öffnen: 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 der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

ShipStation erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable ShipStation shipping eingeschaltet ist. Prüfen Sie Geo zone (oder bei aktivem Ignore shipping zones Countries), die Gewichtsgrenzen und die Minimum subtotal. Ohne Live-Tarif prüfen Sie, ob das Land, * Default oder Other countries einen Preis hat. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Die Kasse zeigt den Ersatzpreis statt des ShipStation-Tarifs: prüfen Sie die Warnungen oben auf der Erweiterungsseite (Schlüssel, Carrier-Code, Versand-Postleitzahl, Wechselkurs). Aktivieren Sie das Debug log, laden Sie die Kasse neu und sehen Sie im Feld Log nach. Die Postleitzahl des Kunden ist erforderlich. Vor ihrer Eingabe erfolgt keine Anfrage.

Welchen Carrier-Code eingeben: speichern Sie die Einstellungen mit API Key und API Secret. Die Seite listet die Carrier-Codes Ihres Kontos auf. Verwenden Sie einen oder mehrere davon.

Die ShipStation-Verbindungsprüfung ist fehlgeschlagen: die Meldung nennt den Grund. Prüfen Sie API Key und API Secret und speichern Sie erneut, um die Prüfung zu wiederholen.

Der Tarif weicht von ShipStation ab: das Paket wird aus Produktgewichten und -abmessungen gebildet, wobei die Artikel in einem Karton gestapelt werden. Produkte ohne Abmessungen werden nur nach Gewicht bewertet. Tarife werden 1 Stunde lang zwischengespeichert. Klicken Sie auf der Erweiterungsseite auf Save, um den Cache zu leeren.

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

Für Entwickler: die Adresse der ShipStation-API kann über die Einstellung vfd_shst_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 ShipStation auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable ShipStation shipping, Sort order, Tax class und Geo zone zurück. Die zwischengespeicherten Tarife und das Ergebnis der Verbindungsprüfung werden immer entfernt. Ist Remove data on uninstall aktiviert, werden auch die ShipStation-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, ihre Kosten und ihren ShipStation-Service.

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

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