VibeFox USPS 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, mit der cURL-Erweiterung.
USPS-Developer-Portal-App (nur für Live-Tarife): melden Sie sich mit einem kostenlosen USPS-Geschäftskonto im USPS Developer Portal (developers.usps.com) an, erstellen Sie eine App und kopieren Sie deren Consumer Key und Consumer Secret. Die Erweiterung nutzt die aktuellen USPS-APIs mit OAuth 2.0. Die alte Web Tools User ID funktioniert damit nicht. Ohne Schlüssel werden nur die Festpreise verwendet.
Absende-PLZ: Live-Tarife benötigen die 5-stellige US-PLZ, von der die Pakete versendet werden.
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_usps-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_usps.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen gleich.
OpenCart 3
1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_usps-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 den Inhalt des Ordners upload aus diesem Paket auch in das Stammverzeichnis Ihres Shops kopieren.
2. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox USPS und klicken Sie auf Install (der grüne +-Button).
3. Klicken Sie auf Edit (der Bleistift-Button), 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 License key).
5. Geben Sie den Consumer Key und das Consumer Secret, die 5-stellige Ship from ZIP code ein und wählen Sie die Services. Wenn die Standardwährung Ihres Shops nicht USD ist, geben Sie den USD exchange rate ein.
6. Optional können Sie Festpreise als Ausweichlösung eingeben, Enable USPS shipping einschalten und auf Save klicken.
OpenCart 4
1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_usps.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 (der grüne +-Button).
3. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox USPS, klicken Sie auf Install (der grüne +-Button) und dann auf Edit (der Bleistift-Button).
4. Geben Sie den Lizenzschlüssel und die Einstellungen ein wie in den Schritten 4 bis 6 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich.
Nach der Installation ist die Methode deaktiviert, bis Sie Enable USPS shipping einschalten und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die gespeicherten USPS-Einstellungen wieder verwendet.
Konfiguration
Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Shipping > VibeFox USPS > Edit. Die Abschnitte stehen links. Ein Save-Button unten speichert die ganze Seite ohne Neuladen. Jedes Speichern löscht den zwischengespeicherten USPS-Token und die Tarife. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern, den Cache leeren oder das Log löschen.
Ein ungültiger Wert wird nicht gespeichert: Die Seite nennt das Feld, setzt den vorherigen Wert zurück und zeigt The other settings were saved. an. Das betrifft einen leeren, zu langen oder unzulässige Zeichen enthaltenden Namen, eine negative oder nicht numerische Zahl, eine PLZ, die nicht 5-stellig ist, eine falsche Paketgröße, ein Min weight (kg) über Max weight (kg) (beide Grenzen behalten ihre Werte), eine Sortierreihenfolge, die keine ganze Zahl ist, sowie eine unbekannte Steuerklasse oder Geozone. Länderpreise, die keine Zahlen sind, werden gelöscht und aufgelistet. Warnungen über den Einstellungen zeigen an, wenn nur einer der beiden Schlüssel gesetzt ist, keine Schlüssel und keine Festpreise vorhanden sind (dann wird die Methode nie angezeigt), die PLZ fehlt, kein Service gewählt ist, der USD-Wechselkurs fehlt, die Testumgebung aktiv ist oder die Gewichts- oder Längeneinheit des Shops der Erweiterung unbekannt ist.
Allgemein
Die Einstellungen gelten für alle Geozonen. USPS wird beim Checkout als eine Versandoption angeboten.
Enable USPS shipping: bietet USPS-Versand beim Checkout an. Standard: aus.
Name: der Name der Versandart, den der Kunde beim Checkout sieht. Standard: USPS. Pflichtfeld, höchstens 64 Zeichen, ohne < > ; = # { }.
Tax class: die Steuerklasse der Versandkosten. USPS-Preise enthalten keine Steuern. No tax (Standard) bedeutet, dass die Versandkosten nicht besteuert werden.
Sort order: die Position von USPS unter den Versandarten beim Checkout. Eine ganze Zahl.
USPS-API (Live-Tarife)
Consumer Key: der Consumer Key (client_id) Ihrer USPS-Entwickler-App. Wenn Sie ihn leeren, wird auch das gespeicherte Consumer Secret entfernt.
Consumer Secret: das Consumer Secret (client_secret) derselben App. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. Clearing the Consumer Key removes it too. Geben Sie einen neuen Wert nur ein, wenn Sie ihn ändern möchten.
Test environment: nutzen Sie die USPS Testing Environment für Versender. Nur für Apps mit Zugang dazu. Lassen Sie es für echte Preise aus. Standard: aus.
Prices: welche USPS-Preisliste verwendet wird.
Services: die USPS-Services, die angeboten werden dürfen. Angezeigt wird der günstigste gewählte Service, den USPS für das Paket anbietet. Wählen Sie aus USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) und Library Mail (libraries and schools only). Standard: Ground Advantage, Priority Mail und First-Class Package International. Flat-Rate-, Cubic-, Hold-for-Pickup- und Sunday-Preise werden nie verwendet. Ist kein Service gewählt, werden keine Live-Tarife verwendet.
USD exchange rate: USPS-Preise sind in USD. Wenn die Standardwährung Ihres Shops nicht USD ist, geben Sie den Preis von 1 USD in Ihrer Währung ein, zum Beispiel 0.92. Er muss größer als 0 sein. Ohne ihn werden keine Live-Tarife verwendet, und die Festpreise gelten. Ist Ihre Shop-Währung USD, wird er nicht benötigt. Der Kurs wird nicht automatisch aktualisiert.
Cache: Angebote werden 1 Stunde und ein fehlgeschlagenes Angebot 10 Minuten zwischengespeichert. Nach Timeout, Serverfehler, Ratenlimit oder abgelehnten Schlüsseln wird USPS 5 Minuten lang nicht angefragt. Klicken Sie auf Clear cached USPS token and rates, um den Cache sofort zu leeren.
Versand und Paket (USPS-Preise hängen von der Absende-PLZ, dem Gewicht und der Paketgröße ab; der Warenkorb wird als ein Paket berechnet)
Ship from ZIP code: die 5-stellige US-PLZ, von der die Pakete versendet werden. ZIP+4 wird auf 5 Stellen gekürzt. OpenCart hat keine Shop-PLZ, daher geben Sie sie hier ein.
Box size (L x W x H): optionale Kartonmaße in der Längeneinheit Ihres Shops (im Feldnamen angezeigt), zum Beispiel 30x20x15. Leer lassen, um die Produktmaße zu verwenden: die längste Länge, die breiteste Breite und die gestapelten Höhen. Produkte ohne Maße werden als Karton mit 10 x 8 x 4 Zoll berechnet.
Default product weight (kg): das Gewicht für Produkte ohne Gewicht, in USPS-Tarifen, den Gewichtsgrenzen und Gewichtsstufen. Standard: 0.5. Leer bedeutet ebenfalls 0,5 kg.
Festpreise (Preise in der Standardwährung Ihres Shops, ohne Steuern; werden verwendet, wenn keine API-Schlüssel eingegeben sind, und als Ausweichlösung, wenn USPS keinen Tarif liefert; leer lassen Sie beide, um die Methode in diesem Fall zu verbergen)
Country prices: Preise nach Zielland und Warenkorbgewicht. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf den Entfernen-Button, um eine zu löschen. Die Gewichtsstufen sind XS bis 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg und XL über 5 kg. Eine leere oder 0-Stufe verwendet Price. * Default (any other country) gilt für alle anderen Länder.
Fallback cost: ein fester Preis, wenn kein Länderpreis passt. Leer lassen, um die Methode in diesem Fall zu verbergen.
Fixed price is: Per order (Standard) berechnet den Preis einmal für das Gewicht des gesamten Warenkorbs. Per item (each item priced by its own weight x quantity) berechnet jedes Produkt nach seinem eigenen Gewicht und multipliziert es mit der Menge. USPS-Live-Tarife werden immer für das gesamte Paket berechnet.
Bedingungen
Free shipping from: die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern), ab der diese Methode kostenlos ist. Dann wird keine Anfrage an USPS gesendet. Leer lassen, um nie kostenlosen Versand anzubieten.
Minimum subtotal: die Methode nur anzeigen, wenn die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern) mindestens diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.
Min weight (kg): das minimale Warenkorbgewicht, damit diese Methode erscheint. 0 bedeutet keine Grenze (Standard).
Max weight (kg): die Methode wird oberhalb dieses Warenkorbgewichts ausgeblendet. Standard: 30. Leer bedeutet 30 kg, 0 bedeutet keine Grenze. USPS akzeptiert bis 70 lb (31,7 kg): schwerere Pakete erhalten die Festpreise.
Geo zone: USPS nur für Adressen in dieser Geozone anbieten. All zones (Standard) bedeutet keine Begrenzung. Geozonen werden unter System > Localisation > Geo Zones verwaltet. Wird nicht zusammen mit Ignore shipping zones verwendet.
Verfügbarkeit ohne Versandzonen
Ignore shipping zones: die Geozone nicht prüfen. Die Methode wird für die unten genannten Länder angeboten.
Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zu erlauben. Dieses Feld wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.
Erweitert
Debug log: protokolliert API-Anfragen und die Tarifberechnung in storage/logs/vfd_usps_debug.log.php (bei OpenCart 4 system/storage/logs/vfd_usps_debug.log.php). Die Datei kann nicht über das Web gelesen werden. API-Fehler werden immer protokolliert, auch wenn diese Option aus ist. Schlüssel, Tokens, PLZ und Kundenadressen werden nie protokolliert. Erreicht die Datei 5 MB, wird sie nach vfd_usps_debug.old.log.php verschoben und ein neues Log begonnen.
Log: zeigt die Größe und die neuesten Einträge des Logs. Klicken Sie auf Clear log, um es zu leeren.
Remove data on uninstall: wenn eingeschaltet, löscht die Deinstallation der Erweiterung die USPS-Einstellungen und das Log. Zwischengespeicherte Tarife werden immer entfernt. Die USPS-Services aufgegebener Bestellungen bleiben immer erhalten. Wenn ausgeschaltet, bleiben die Einstellungen für eine Neuinstallation erhalten.
Import / Export
Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Das Consumer Secret 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. Das gespeicherte Consumer Secret bleibt erhalten.
So funktioniert es beim Checkout
Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem USPS-Preis. Ist eine Geo zone gesetzt und die Adresse liegt außerhalb, wird USPS nicht angeboten (mit Ignore shipping zones entscheidet stattdessen die Länderliste). Nur Produkte mit Requires Shipping auf Yes zählen: andere Produkte fügen kein Gewicht hinzu und sind nicht in der Zwischensumme enthalten. Geschenkgutscheine, Bonuspunkte und Shop-Guthaben werden nicht berücksichtigt. Die Erweiterung prüft dann die Bedingungen: Warenkorbgewicht und Mindestzwischensumme. Gilt kostenloser Versand, ist der Preis 0 und es wird keine Anfrage an USPS gesendet.
Die Erweiterung holt einen OAuth-Token von USPS und behält ihn bis kurz vor dessen Ablauf. Für Ziele in den USA und deren Territorien (Puerto Rico, die US-Jungferninseln, Guam, Amerikanisch-Samoa, die Nördlichen Marianen, Mikronesien, die Marshallinseln und Palau) fragt sie die Inlandspreise ab und benötigt die 5-stellige PLZ des Kunden: ohne sie erfolgt keine Anfrage. Für andere Länder fragt sie die internationalen Preise ab.
Die Anfrage enthält die Absende-PLZ, das Warenkorbgewicht, die Paketgröße und den Preistyp. Pakete über 70 lb erhalten die Festpreise. Der Kunde sieht eine Option mit dem günstigsten gewählten Service. Der USD-Preis wird in Ihre Standardwährung umgerechnet, auf deren Dezimalstellen gerundet und in der Kundenwährung mit der Steuer der gewählten Tax class angezeigt.
Jedes Angebot wird 1 Stunde zwischengespeichert. Ein fehlgeschlagenes Angebot wird 10 Minuten gemerkt. Nach Timeout, Serverfehler, Ratenlimit oder abgelehnten Schlüsseln wird USPS 5 Minuten lang nicht angefragt. Das HTTP-Timeout beträgt 10 Sekunden.
Wenn USPS keinen Tarif liefert, kommt der Preis aus Country prices, dann aus Fallback cost. Trifft keines zu, wird die Methode ausgeblendet. Der Kunde sieht nie USPS-Fehlertexte. Der Grund wird ins Debug-Log geschrieben.
Die Erweiterung berechnet nur Tarife. Sie kauft keine Frankierung oder Versandetiketten, bucht keine Abholungen, verfolgt keine Pakete und lässt Kunden keine Postfiliale oder Abholstelle wählen. Sie zeigt eine Option, nicht mehrere USPS-Services. Es gibt keine Kartonpackung: der Warenkorb wird als ein Paket berechnet. Versicherung und andere Zusatzleistungen sind nicht enthalten.
Bei OpenCart 4 klickt der Kunde im Versandart-Block der Checkout-Seite auf Choose und wählt im Fenster Shipping method options USPS aus. Die Methode funktioniert genauso wie bei OpenCart 3.
Bestellungen
Wenn eine Bestellung mit USPS aufgegeben wird, speichert die Erweiterung, wie der Versandpreis ermittelt wurde. Die Bestellseite unter Sales > Orders zeigt ein Panel USPS mit dem USPS service (bei einem Live-Tarif zum Beispiel USPS Ground Advantage), der Price source (USPS live rate, Fixed price oder Free shipping) und dem Calculated price (excl. tax). Diese Werte werden beim Aufgeben der Bestellung gespeichert.
OpenCart 4 behält für den Checkout eine Bestellung und aktualisiert sie jedes Mal, wenn der Kunde erneut bestätigt. Die gespeicherten Werte werden damit aktualisiert. Wechselt der Kunde auf eine andere Versandart, werden sie aus der Bestellung entfernt. Bei OpenCart 4 wird das Panel USPS oberhalb des Abschnitts History angezeigt.
Lizenzschlüssel
Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox USPS ist der erste Block auf Extensions > Extensions > Shipping > VibeFox USPS > 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-shipping-usps 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 weiter mit dem zuletzt bekannten Status.
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 USPS beim Checkout den Kunden 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), sodass Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. Bei OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher ist die Methode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint im Admin auf dem Dashboard eine Erinnerung. Schließen Sie sie mit ×, um sie 7 Tage lang zu verbergen. Bestehende Bestellungen sind nicht betroffen.
Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, Updates und Support benötigen aber eine Verlängerung. Der Status wird beim Öffnen des Dashboard im Admin oder der Seite Edit automatisch erneut geprüft: einmal am Tag in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Die Deinstallation der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
USPS erscheint nicht beim Checkout: prüfen Sie, ob die Lizenz aktiv ist und Enable USPS shipping eingeschaltet ist. Prüfen Sie die Geo zone oder schalten Sie Ignore shipping zones ein und prüfen Sie Countries. Prüfen Sie die Gewichtsgrenzen und die Minimum subtotal. Ohne funktionierende USPS-Schlüssel braucht die Methode einen Festpreis (Country prices oder Fallback cost). Prüfen Sie, dass die Produkte Requires Shipping auf Yes haben.
Live-Tarife erscheinen nicht: prüfen Sie die Warnungen oben auf der Seite Edit: beide Schlüssel, die PLZ, mindestens einen Service und bei Shops, die nicht in USD arbeiten, den Wechselkurs. US-Kunden müssen eine PLZ eingeben. Schalten Sie Debug log ein, laden Sie den Checkout neu und sehen Sie sich das Feld Log auf der Seite der Erweiterung an.
Tarife sind keine echten Preise: schalten Sie Test environment aus.
Die Seite warnt vor der Gewichts- oder Längeneinheit: ohne Gewichtsklasse mit der Einheit kg werden unbekannte Gewichtseinheiten als kg gelesen. Fügen Sie eine kg-Gewichtsklasse unter System > Localisation > Weight Classes hinzu. Eine unbekannte Längeneinheit des Shops wird als cm behandelt. Verwenden Sie cm, mm, m oder in als Längenklasse des Shops (System > Settings, Tab Option).
Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Seite der Erweiterung auf Save oder auf Clear cached USPS token and rates.
Die Seite zeigt "Warning: You do not have permission to modify VibeFox USPS!": Ihre Admin-Benutzergruppe darf die Einstellungen möglicherweise nur ansehen. Geben Sie der Gruppe die Änderungsberechtigung für extension/shipping/vfd_usps (OpenCart 3) oder extension/vfd_usps/shipping/vfd_usps (OpenCart 4) unter System > Users > User Groups.
Für Entwickler: die USPS-API-Adresse kann mit der Einstellung vfd_usps_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 USPS auf Uninstall (der rote −-Button). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt Enable USPS shipping, Sort order, Tax class und Geo zone immer zurück. Der zwischengespeicherte USPS-Token und die Tarife werden immer entfernt. Ist Remove data on uninstall eingeschaltet, werden auch die USPS-Einstellungen und das Debug-Log gelöscht. Ist es ausgeschaltet, bleiben die übrigen Einstellungen erhalten und werden bei einer erneuten Installation wieder verwendet. Die USPS-Daten aufgegebener Bestellungen werden nie entfernt; bestehende Bestellungen behalten ihre Versandart und Kosten.
Bei OpenCart 4 gehen Sie nach der Deinstallation zu Extensions > Installer, um auch die Dateien der Erweiterung zu entfernen, klicken Sie in der Liste der installierten Erweiterungen neben VibeFox USPS auf Uninstall (der orangefarbene −-Button) und dann auf Delete (der rote Papierkorb-Button), um das hochgeladene Paket zu entfernen.
USPS ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit USPS verbunden und wird nicht von USPS unterstützt.