VibeFox Canada Post 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.

Canada Post Developer Program (nur für Live-Tarife): Live-Tarife nutzen die Canada Post Rating API. Melden Sie sich im Canada Post Developer Program auf der Website von Canada Post an und kopieren Sie Ihren API-Schlüssel und Ihre Kundennummer. Der API-Schlüssel hat die Form username:password, und Canada Post stellt getrennte Schlüssel für die Entwicklungsumgebung (Sandbox) und die Produktivumgebung bereit. Außerdem benötigen Sie die kanadische Postleitzahl, von der Sie versenden. Wenn Sie nur Festpreise verwenden, brauchen Sie keine API-Schlüssel.

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 Canada Post in der Modulliste und klicken Sie auf Configure.

3. Geben 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. Für Live-Tarife geben Sie Benutzername und Passwort der API, Ihre Kundennummer und die Postleitzahl des Versands ein. Wenn die Standardwährung Ihres Shops nicht CAD ist, geben Sie den CAD-Kurs ein. Füllen Sie Country prices aus, wenn Sie Festpreise oder einen Ersatzpreis wünschen (siehe Konfiguration). Klicken Sie auf Save.

Bei der Installation legt das Modul den Versanddienstleister Canada Post mit dem Laufzeittext Canada Post parcel delivery an. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugewiesen. Zonen, Kundengruppen, Laufzeit, Logo und Größenlimits können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis stammt immer aus dem Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Canada Post > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten Canada-Post-Tarife. Zum Speichern benötigen Sie die Berechtigung zum Konfigurieren des Moduls.

Ist ein Wert falsch, zeigt die Seite einen Fehler, und nichts wird gespeichert: ein Zahlenfeld oder ein Preis unter Country prices, der keine Zahl von 0 oder mehr ist (zum Beispiel -1 oder 12abc), ein CAD-Kurs von 0, Min cart weight (kg) größer als Max cart weight (kg) oder ein Method title mit mehr als 64 Zeichen. Wenn die Gewichts- oder Maßeinheit Ihres Shops dem Modul unbekannt ist, warnt die Seite, dass Gewichte als kg (Maße als cm) gelesen werden. Stellen Sie kg, g, lb oder oz (cm, mm, m oder in) unter International > Localization, Abschnitt Local units, ein.

Nach dem Speichern zeigt die Seite eine Warnung, wenn die Einstellungen nicht wie vorgesehen funktionieren können: Nur einer der Felder API-Benutzername und API-Passwort ist ausgefüllt, die Versand-Postleitzahl ist keine kanadische Postleitzahl (Format A1A 1A1), der CAD-Kurs fehlt bei einem Shop mit anderer Währung, oder es gibt weder API-Zugangsdaten noch Festpreise. Die Warnung nennt außerdem, was in der Zwischenzeit geschieht: Die Festpreise je Land werden verwendet, oder der Versanddienstleister wird an der Kasse ausgeblendet, wenn die Tabelle Country prices leer ist.

Allgemein

Enable Canada Post: schaltet den Versanddienstleister ein oder aus. Dies ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Method title: der Name des Versanddienstleisters, der dem Kunden an der Kasse angezeigt wird. Standard: Canada Post, auch wenn das Feld leer bleibt. Bis zu 64 Zeichen, ohne Zeichen, die PrestaShop in Namen von Versanddienstleistern nicht zulässt.

Tax: die Steuerregel, die PrestaShop zu den Versandkosten hinzufügt, oder No tax (nicht steuerpflichtig).

Canada Post API (Live-Tarife)

Mit ausgefülltem API-Benutzernamen und -Passwort stammt der Preis aus der Canada Post Rating API. Liefert die API keinen Tarif (API nicht erreichbar, falsche Postleitzahl, Service nicht verfügbar), wird der Festpreis aus Country prices verwendet oder der Versanddienstleister ausgeblendet, wenn es keinen gibt. Der Abschnitt verlinkt auf das Canada Post Developer Program, wo Sie die API-Schlüssel und Ihre Kundennummer finden. Fehlerdetails gehen ins Protokoll, nie an den Kunden.

API username: der Teil des API-Schlüssels vor dem Doppelpunkt. Verwenden Sie den Entwicklungsschlüssel mit Sandbox und den Produktionsschlüssel in einem Live-Shop.

API password: der Teil des API-Schlüssels nach dem Doppelpunkt. Nach dem Speichern bleibt das Feld leer und zeigt A password is saved. Leave empty to keep it; clear the username and save to remove both. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern wollen. Das Passwort wird genau so gespeichert, wie Sie es eingeben, und nie ins Protokoll geschrieben.

Customer number: Mit einer Kundennummer liefert Canada Post die kommerziellen (ermäßigten) Tarife Ihres Kontos. Lassen Sie das Feld leer für Schalter-Tarife (Retail). Leerzeichen werden entfernt.

Contract number: optional, für Vertragskunden. Sie wird nur zusammen mit der Kundennummer verwendet.

Sandbox: nutzt die Entwicklungsumgebung von Canada Post, zum Testen mit dem Entwicklungs-API-Schlüssel. Die Preise sind Testdaten. Schalten Sie sie in einem Live-Shop aus.

Ship-from postal code: die kanadische Postleitzahl, von der die Pakete versendet werden, zum Beispiel K1A 0B1. Live-Tarife benötigen sie.

Service in Canada: der Service für kanadische Adressen: Cheapest available, Regular Parcel (DOM.RP, Standard), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) oder Priority (DOM.PC).

Service to the USA: Cheapest available (Standard), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) oder Priority Worldwide parcel USA (USA.PW.PARCEL).

International service: Cheapest available (Standard), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) oder Priority Worldwide parcel International (INT.PW.PARCEL).

Wird der gewählte Service für die Adresse oder das Paket nicht angeboten, wird der günstigste verfügbare verwendet.

Use Canada Post prices without GST/HST/PST: Bei kanadischen Adressen enthält der Preis von Canada Post diese Steuern. Aktivieren Sie die Option, wenn PrestaShop die Steuer auf den Versand selbst berechnet (Tax oben), damit die Steuer nicht doppelt berechnet wird.

CAD to … rate: der Feldname zeigt die Standardwährung Ihres Shops, zum Beispiel CAD to USD rate. Die Preise von Canada Post sind in CAD. Ist Ihre Standardwährung nicht CAD, geben Sie ein, wie viele Einheiten Ihrer Währung einem CAD entsprechen, zum Beispiel 0.68. Ohne diesen Wert werden keine Live-Tarife verwendet. Ist Ihre Standardwährung CAD, lassen Sie das Feld leer. Der Kurs muss größer als 0 sein. Sowohl Punkt als auch Komma werden als Dezimaltrennzeichen akzeptiert.

Default product weight (kg): wird für jedes Produkt ohne Gewicht an Canada Post gesendet. Standard: 0.5. Produktgewichte (in der Gewichtseinheit Ihres Shops) und Abmessungen werden umgerechnet, und der Warenkorb wird als ein einziges Paket berechnet.

Festpreise (werden ohne API-Zugangsdaten und als Ersatz verwendet, wenn die API keinen Tarif liefert)

Country prices: eine Tabelle mit Ländern, einem Base-Preis und Preisen nach Warenkorbgewicht in der Standardwährung Ihres Shops, ohne Steuer: XS bis 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL über 5 kg. Ein leerer oder Null-Preis für eine Größe verwendet den Base-Preis. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Kreuz, um eine zu entfernen. Die Zeile * Default (all other countries) legt Preise für alle Länder fest, die keine eigene Zeile haben. Ein Land ohne Zeile (und ohne *) erhält keinen Festpreis. Ein Basispreis von 0 bedeutet kostenlosen Versand für dieses Land. Eine Zeile ohne jeden Preis wird nicht gespeichert.

Fixed price per: Order berechnet den Preis einmal. Item (price x quantity) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Dies gilt nur für Festpreise. Live-Tarife werden immer für das gesamte Paket berechnet.

Bedingungen

Min cart weight (kg): blendet den Versanddienstleister unterhalb dieses Warenkorbgewichts aus. 0 bedeutet kein Limit.

Max cart weight (kg): blendet den Versanddienstleister oberhalb dieses Warenkorbgewichts aus. Standard: 25, auch wenn das Feld leer ist. 0 bedeutet kein Limit. Canada-Post-Pakete können bis zu 30 kg wiegen. Der Wert kann nicht niedriger sein als Min cart weight (kg).

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

Free shipping: aktiviert kostenlosen Versand ab dem unten angegebenen Betrag.

Free shipping from: die Zwischensumme des Warenkorbs, ab der der Versand kostenlos ist. In diesem Fall wird keine API-Anfrage gestellt. Wird nur verwendet, wenn Free shipping aktiviert ist.

Verfügbarkeit ohne Versandzonen

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

Ignore shipping zones: bietet den Versanddienstleister für die unten genannten Länder an, unabhängig davon, welche Zone passt. Beim Speichern wird der Versanddienstleister allen Zonen hinzugefügt, ebenso später angelegte Zonen. Wenn Sie die Option ausschalten und speichern, werden die vom Modul hinzugefügten Zonen wieder entfernt, und der Versanddienstleister behält seine eigenen Zonen.

Countries: die Zielländer für diesen Modus. Halten Sie Strg (Cmd) gedrückt, um mehrere auszuwählen. Lassen Sie das Feld leer, um alle aktiven Länder zuzulassen. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.

Erweitert

Debug log: protokolliert die Tarifberechnungen in var/logs/vfd_canada_post.log.php. Die Datei kann nicht über das Web geöffnet werden und wird ab 5 MB rotiert. API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. API-Schlüssel, Kundennummern und Postleitzahlen der Kunden werden nicht protokolliert.

Remove data on uninstall: wenn aktiviert, löscht die Deinstallation des Moduls die Einstellungen, die gespeicherten Bestell-Services, die zwischengespeicherten Tarife und das Protokoll. Der Versanddienstleister wird bei der Deinstallation immer aus der Kasse entfernt. Bestellungen werden nie verändert.

Log: das Feld unter den Einstellungen zeigt den Dateinamen und die neuesten 50 Einträge. Klicken Sie auf Clear log, um es zu löschen.

So funktioniert es an der Kasse

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

Mit API-Zugangsdaten sendet das Modul an Canada Post die Versand-Postleitzahl, das Ziel, das Paketgewicht und, wenn alle Produkte Abmessungen haben, die geschätzte Paketgröße. Für Kanada ist das Ziel die Postleitzahl, für die USA der ZIP-Code, für alle anderen Länder nur das Land. Ein Live-Tarif wird nur angefragt, wenn eine kanadische oder US-Adresse eine gültige Postleitzahl oder ZIP-Code hat. Canada Post liefert alle Services für das Paket. Das Modul wählt den gewählten Service der Zielgruppe oder den günstigsten, entfernt kanadische Verkaufssteuern (GST/HST/PST), wenn Use Canada Post prices without GST/HST/PST aktiviert ist, und rechnet den CAD-Preis mit Ihrem Kurs um. Der Preis wird in der Standardwährung Ihres Shops berechnet und dann in der Warenkorbwährung des Kunden angezeigt.

Jede Antwort wird 1 Stunde zwischengespeichert, damit derselbe Warenkorb und dieselbe Adresse keine neue Anfrage auslösen. Eine fehlgeschlagene Anfrage wird 10 Minuten zwischengespeichert, damit ein Ausfall von Canada Post nicht jede Aktualisierung der Kasse verlangsamt. Das API-Timeout beträgt 10 Sekunden. Pakete über 30 kg werden nicht an die API gesendet.

Liefert die API keinen Tarif, wird der Festpreis verwendet, oder der Versanddienstleister wird ausgeblendet, wenn kein Festpreis vorhanden ist. Der Kunde sieht nie API-Fehlerdetails; sie gehen ins Protokoll.

Wenn Sie den Versanddienstleister unter Shipping > Carriers bearbeiten, speichert PrestaShop ihn als neue Version. Das Modul folgt der neuen Version automatisch.

Das Modul berechnet nur Tarife. Es erstellt keine Sendungen, druckt keine Etiketten, erstellt keine Manifeste oder Retouren und verfolgt keine Pakete. Kunden können keine Postfiliale oder Abholstelle wählen. Es zeigt einen einzigen Canada-Post-Tarif ohne Lieferdaten, Versicherungs- oder Unterschriftsoptionen. Der Warenkorb wird immer als ein Paket berechnet, und Währungskurse werden nicht automatisch aktualisiert.

Bestellungen

Wenn eine Bestellung mit dem Versanddienstleister Canada Post aufgegeben wird, speichert das Modul, wie sein Preis berechnet wurde. Auf der Bestellseite im Back-Office (Orders > Orders, eine Bestellung öffnen) zeigt ein Block Canada Post:

Canada Post service: der Name und Code des Services eines Live-Tarifs, zum Beispiel Regular Parcel (DOM.RP).

Price source: Live rate (Canada Post Rating API), Fixed price oder Free shipping.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Canada Post ist der erste Block unter Modules > Module Manager > VibeFox Canada Post > 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 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: presta-shipping-canada-post und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung zum Konfigurieren des Moduls 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 gilt für eine Domain: die Domain des Hauptshops, auch bei einem Multistore-Setup. 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 Canada Post Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Die Storefront von PrestaShop weiß nicht, dass Sie im Back-Office angemeldet sind, daher wird der Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber an der Kasse 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, aber Updates und Support erfordern 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. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Canada Post erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable Canada Post eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes des Kunden und dessen Kundengruppe abdeckt (oder Ignore shipping zones ist aktiv und das Land ist erlaubt). Prüfen Sie die Gewichtsgrenzen und Minimum order amount. Es muss einen Tarif geben: Mit API-Zugangsdaten braucht die Adresse eine gültige Postleitzahl (Kanada) oder ZIP-Code (USA); andernfalls muss ein Festpreis für das Land oder für * existieren. Produkte können auf der Produktseite außerdem auf bestimmte Versanddienstleister beschränkt sein.

Live-Tarife erscheinen nicht: Aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie im Panel Log auf der Modulseite nach. Dort steht der Grund: fehlender API-Benutzername oder fehlendes Passwort, eine ungültige Versand- oder Zielpostleitzahl, ein fehlender CAD-Kurs, ein Paket über 30 kg oder die Fehlermeldung von Canada Post. In der Zwischenzeit erhalten Kunden den Festpreis, sofern vorhanden.

Der Tarif weicht von der Website von Canada Post ab: Mit einer Kundennummer erhalten Sie die kommerziellen (ermäßigten) Tarife Ihres Kontos; ohne sie die Schalter-Tarife (Retail). Bei kanadischen Adressen enthält der Preis von Canada Post GST/HST/PST. Die Preise werden mit Ihrem CAD-Kurs umgerechnet.

Steuer wird auf den Versand doppelt berechnet: Aktivieren Sie Use Canada Post prices without GST/HST/PST oder setzen Sie Tax auf No tax.

Preise in einem Live-Shop testen: Schalten Sie Sandbox aus und verwenden Sie den Produktions-API-Schlüssel.

Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Das löscht die zwischengespeicherten Canada-Post-Tarife.

Die Seite meldet, dass der Versanddienstleister Canada Post fehlt: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn wieder anzulegen.

Sie haben keine Berechtigung, dieses Modul zu konfigurieren: Ihr Mitarbeiterprofil kann die Modulseite öffnen, aber nicht speichern. Bitten Sie einen Administrator, Ihrem Profil die Berechtigung zum Konfigurieren des Moduls zu geben.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Canada Post und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Der Versanddienstleister wird immer aus der Kasse entfernt (Bestellungen behalten ihren Versanddienstleister und ihren Verlauf). Ist Remove data on uninstall aktiviert, werden die Einstellungen, die gespeicherten Bestell-Services, die zwischengespeicherten Tarife und das Protokoll gelöscht. Ist sie ausgeschaltet, werden nur die zwischengespeicherten Tarife entfernt und alle Einstellungen bleiben erhalten. Wenn Sie das Modul erneut installieren (oder Reset ausführen), wird der bisherige Versanddienstleister mit seinem bisherigen Status wiederhergestellt: Ein Versanddienstleister, den Sie deaktiviert hatten, bleibt deaktiviert.

Canada Post ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Canada Post verbunden und wird nicht von Canada Post empfohlen.