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

App im USPS Developer Portal (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. Das Modul verwendet die aktuellen USPS-APIs mit OAuth 2.0. USPS hat die alte Web-Tools-API (User ID und XML) am 25. Januar 2026 abgeschaltet, daher funktioniert eine Web-Tools-User-ID nicht mehr. Ohne Schlüssel werden nur die Festpreise verwendet.

Ship-from ZIP code: Live-Tarife benötigen die 5-stellige US-Postleitzahl, von der aus die Pakete versendet werden.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert 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 aus.

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

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

4. Geben Sie Consumer Key und Consumer Secret, die 5-stellige Ship from ZIP code ein und wählen Sie die Dienste. Wenn die Standardwährung Ihres Shops nicht USD ist, geben Sie den USD exchange rate ein. Optional können Sie Festpreise als Ersatz eingeben. Klicken Sie auf Save.

Bei der Installation legt das Modul den Versanddienstleister USPS mit dem Lieferzeittext Delivery by USPS 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 kommt immer vom Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox USPS > Configure. Sie gelten für alle Zonen des Versanddienstleisters. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern leert außerdem das zwischengespeicherte USPS-Token und die Tarife.

Ein ungültiger Wert wird nicht gespeichert: Der vorherige Wert bleibt erhalten, und eine Fehlermeldung nennt das Feld, während die anderen Felder gespeichert werden. Hinweise am oberen Seitenrand zeigen an, wenn nur einer der Schlüssel gesetzt ist, keine Schlüssel und keine Festpreise vorhanden sind (dann wird der Versanddienstleister nie angezeigt), die Versand-Postleitzahl fehlt, kein Dienst ausgewählt ist, der USD-Wechselkurs fehlt, die Testumgebung eingeschaltet ist, die Gewichts- oder Maßeinheit des Shops unbekannt ist (einstellbar unter International > Localization, Local units) oder der USPS-Versanddienstleister gelöscht wurde.

Allgemein

Enable USPS shipping: schaltet den Versanddienstleister ein oder aus. Das ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Name: der Name des Versanddienstleisters, den der Kunde im Bestellvorgang sieht. Standard: USPS. Pflichtfeld, bis zu 64 Zeichen.

Tax status: die Steuerregel des Versanddienstleisters. USPS-Preise enthalten keine Steuern. Wählen Sie eine Steuerregel, um die Versandsteuer hinzuzufügen, oder None, wenn der Versand nicht besteuert wird.

USPS-API (Live-Tarife)

Consumer Key: der Consumer Key (client_id) Ihrer USPS-Entwickler-App.

Consumer Secret: das Consumer Secret (client_secret) derselben App. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. an. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Wenn Sie den Consumer Key leeren, wird auch das gespeicherte Secret entfernt.

Test environment: nutzt die USPS Testing Environment for Mailers (apis-tem.usps.com). Nur für Apps, die Zugang dazu haben. Für echte Preise ausgeschaltet lassen (apis.usps.com). Standard: aus.

Prices: welche USPS-Preise verwendet werden.

Services: die USPS-Dienste, die angeboten werden dürfen. Angezeigt wird der günstigste ausgewählte Dienst, den USPS für das Paket anbietet. Flat-Rate-, Cubic-, Hold-for-Pickup- und Sunday-Preise werden nie verwendet. Standard: USPS Ground Advantage, Priority Mail und First-Class Package International Service. Ist kein Dienst ausgewä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 für 1 USD in dieser Währung ein, zum Beispiel 0.92. Ohne diesen Wert werden keine Live-Tarife verwendet, und es gelten die Festpreise. Nicht nötig, wenn die Standardwährung USD ist. Muss größer als 0 sein.

Cache: die Schaltfläche Clear cached USPS token and rates leert den Cache sofort. Tarife werden 1 Stunde zwischengespeichert, ein fehlgeschlagener Tarif 10 Minuten. Nach einem Timeout, Serverfehler, Ratenlimit oder abgelehnten Schlüsseln wird USPS 5 Minuten lang nicht angefragt.

Versand und Paket (die USPS-Preise hängen von der Versand-Postleitzahl, dem Gewicht und der Paketgröße ab; der Warenkorb wird als ein Paket kalkuliert, und Pakete über 70 lb verwenden die Festpreise)

Ship from ZIP code: die 5-stellige US-Postleitzahl, von der aus die Pakete versendet werden. Eine ZIP+4-Postleitzahl wird auf 5 Stellen gekürzt. Andere Werte werden mit einer Meldung abgelehnt.

Box size: optionale Kartonmaße in der Maßeinheit Ihres Shops, zum Beispiel 30x20x15. Leer lassen, um die Größe aus den Produktmaßen zu bilden: die längste Länge, die breiteste Breite und die gestapelten Höhen. Hat ein Produkt keine Maße, wird ein Karton von 10 x 8 x 4 Zoll verwendet.

Default product weight: das Gewicht in kg für Produkte ohne Gewicht, bei USPS-Tarifen, Gewichtsgrenzen und Gewichtsstufen. Standard: 0.5.

Festpreise (Preise in der Standardwährung Ihres Shops, ohne Steuern; werden verwendet, wenn keine API-Schlüssel eingegeben sind, und als Ersatz, wenn USPS keinen Tarif liefert: API nicht erreichbar, falsche Schlüssel, kein Dienst oder ein Ziel ohne US-Postleitzahl; lassen Sie beide Felder leer, um den Versanddienstleister in diesem Fall auszublenden)

Country prices: Preise nach Zielland und Warenkorbgewicht. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorbsymbol, um sie zu entfernen. Die Spalten sind Price sowie die Gewichtsstufen XS (bis 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) und XL (über 5 kg). Eine leere Stufe oder 0 verwendet Price. Die Zeile * Default (any other country) gilt für jedes andere Land. Eine Länderzeile ohne Preis leitet dieses Land an Fallback cost weiter. Werte, die keine Zahlen sind, werden mit einer Meldung gelöscht.

Fallback cost: ein fester Preis, wenn kein Länderpreis passt. Leer lassen, um den Versanddienstleister in diesem Fall auszublenden.

Fixed price is: Per order berechnet den Preis einmal nach dem Gewicht des gesamten Warenkorbs. Per item (each item priced by its own weight x quantity) bewertet jedes Produkt nach dem Gewicht einer Einheit (das Standardgewicht, wenn keines vorhanden ist) und multipliziert es mit der Menge. USPS-Live-Tarife werden immer für das gesamte Paket angeboten.

Bedingungen

Free shipping from: die Warenkorb-Zwischensumme (nach Rabatten, vor Steuern), ab der dieser Versanddienstleister kostenlos ist. Dann wird keine Anfrage an USPS gesendet. Leer lassen, um nie kostenlosen Versand anzubieten.

Minimum subtotal: den Versanddienstleister nur anzeigen, wenn die Warenkorb-Zwischensumme mindestens diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.

Min weight: das minimale Warenkorbgewicht in kg, damit dieser Versanddienstleister erscheint. 0 bedeutet keine Grenze.

Max weight: der Versanddienstleister wird oberhalb dieses Warenkorbgewichts in kg ausgeblendet. Standard: 30. USPS nimmt bis zu 70 lb (31,7 kg) an. 0 bedeutet keine Grenze. Ist Min weight größer als Max weight, wird ein Fehler angezeigt und die bisherigen Grenzen bleiben erhalten.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet den Versanddienstleister in jeder Zone für die unten genannten Länder an. Beim Speichern wird der Versanddienstleister allen Zonen des Shops zugeordnet, auch später angelegten. Wenn Sie die Option ausschalten, erhält der Versanddienstleister seine früheren Zonen zurück.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zu erlauben, in die der Shop versendet. Dieses Feld wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.

Erweitert

Debug log: protokolliert API-Anfragen und die Tarifberechnung in logs/vfd_usps_debug.log.php im Modulordner. Die Datei kann nicht über das Web aufgerufen werden. API-Fehler werden immer protokolliert, auch wenn diese Option aus ist. Schlüssel, Tokens und Kundenadressen werden nie protokolliert.

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 eingeschaltet, löscht die Deinstallation des Moduls die USPS-Einstellungen, den Versanddienstleister, die gespeicherten Bestellservices, die zwischengespeicherten Tarife und die Protokolle. Wenn ausgeschaltet, bleibt alles für eine erneute Installation erhalten.

Ablauf im Bestellvorgang

Im Versandschritt fragt PrestaShop das Modul nach dem USPS-Preis. Nur physische Produkte zählen: Virtuelle Produkte fügen kein Gewicht hinzu und werden nicht in die Zwischensumme einbezogen. Das Modul prüft zuerst die Bedingungen: erlaubte Länder (mit Ignore shipping zones), Warenkorbgewicht und Mindestzwischensumme. Gilt kostenloser Versand, beträgt der Preis 0, und es wird keine Anfrage an USPS gesendet.

Das Modul holt ein OAuth-Token von USPS und behält es bis kurz vor Ablauf. Ein Token, das USPS ablehnt, wird erneuert und die Anfrage wiederholt. Für Ziele in den USA und ihren Territorien (Puerto Rico, die US-Jungferninseln, Guam, Amerikanisch-Samoa, die Nördlichen Marianen, Mikronesien, die Marshallinseln und Palau) fragt es die Domestic-Prices-API ab und benötigt die 5-stellige Postleitzahl des Kunden. Für andere Länder fragt es die International-Prices-API mit Land und Postleitzahl ab.

Die Anfrage enthält die Versand-Postleitzahl, das Warenkorbgewicht in Pfund, die Paketgröße in Zoll und den Preistyp. Pakete über 70 lb erhalten die Festpreise. Der Kunde sieht eine einzige Option mit dem günstigsten ausgewählten Dienst, umgerechnet von USD in die Standardwährung Ihres Shops und dann in der Warenkorbwährung des Kunden angezeigt.

Jede Anfrage wird 1 Stunde zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten gemerkt. Nach einem 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, stammt der Preis aus Country prices, dann aus Fallback cost. Trifft keines zu, wird der Versanddienstleister ausgeblendet. Der Kunde sieht nie USPS-Fehlermeldungen. 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 Tarife. Es kauft keine Frankierung oder Versandetiketten, bucht keine Abholungen, verfolgt keine Sendungen und erlaubt dem Kunden nicht, eine Postfiliale oder Abholstelle zu wählen. Es zeigt eine Option, nicht mehrere USPS-Dienste. Es gibt keine Kartonpackung: Der Warenkorb wird als ein Paket kalkuliert. Versicherung und andere Zusatzleistungen sind nicht enthalten.

Bestellungen

Wenn eine Bestellung mit dem USPS-Versanddienstleister aufgegeben wird, speichert das Modul, wie der Versandpreis ermittelt wurde. Die Bestellseite im Back-Office zeigt einen Block USPS mit dem USPS service (bei einem Live-Tarif zum Beispiel USPS Ground Advantage) und der Price source: USPS live rate, Fixed price oder Free shipping.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox USPS ist der erste Block auf Modules > Module Manager > VibeFox USPS > 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-usps und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back-Office (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 das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert für eine Domain: die 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 USPS-Versanddienstleister Kunden im Bestellvorgang nicht angezeigt, und es wird kein Tarif berechnet. Der PrestaShop-Storefront 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, aber im Bestellvorgang nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen aber eine Verlängerung. Der Status wird während Ihrer 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. Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

USPS erscheint nicht im Bestellvorgang: Prüfen Sie, ob die Lizenz aktiv ist und Enable USPS shipping eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe abdeckt, 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 benötigt der Versanddienstleister einen Festpreis (Country prices oder Fallback cost). Produkte können auf der Produktseite auch auf bestimmte Versanddienstleister beschränkt sein.

Live-Tarife erscheinen nicht: Prüfen Sie die Hinweise oben auf der Modulseite. Schalten Sie Debug log ein, laden Sie den Bestellvorgang neu und sehen Sie sich das Feld Log an. Falsche Schlüssel, die falsche Umgebung und USPS-Fehlermeldungen werden dort protokolliert. Inlandstarife benötigen die 5-stellige Postleitzahl des Kunden.

Mein Shop ist nicht in USD: USPS rechnet nur in USD ab. Geben Sie den USD exchange rate ein. Ohne ihn wird der Live-Tarif nicht verwendet, und stattdessen wird der Festpreis angezeigt.

Eine Web-Tools-User-ID funktioniert nicht: Die alte Web-Tools-API ist abgeschaltet. Erstellen Sie eine App im USPS Developer Portal und verwenden Sie deren Consumer Key und Consumer Secret.

Tarife wirken nach einer Änderung veraltet: Der Cache wird beim Speichern der Einstellungen geleert. Sie können auch auf Clear cached USPS token and rates klicken.

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

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox USPS und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Das zwischengespeicherte Token und die Tarife werden ebenfalls immer entfernt. Ist Remove data on uninstall eingeschaltet, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, die gespeicherten Bestellservices und das Protokoll werden entfernt. Ist die Option aus, wird der Versanddienstleister nur deaktiviert, und alle Einstellungen bleiben erhalten. Bei einer erneuten Installation des Moduls oder bei Reset erhält der gespeicherte Versanddienstleister seinen früheren Status zurück: Ein eingeschalteter Versanddienstleister ist wieder eingeschaltet, ein deaktivierter bleibt deaktiviert.

USPS ist eine Marke ihres jeweiligen Inhabers. Dieses Modul steht in keiner Verbindung zu USPS und wird von USPS nicht unterstützt.