VibeFox bpost Cubee 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.

bpost-Shipping-Platform-Konto (nur für die Abholstellen-Auswahl): Das Modul sucht Abholstellen über die API der bpost Shipping Platform. Melden Sie sich unter plugins.bpost.be in Ihrem bpost-Shipping-Platform-Konto an und erstellen Sie die Schlüssel unter Settings > Key management. Sie benötigen drei Werte: Account ID (öffentlicher Schlüssel), Passphrase (privater Schlüssel) und eine App ID (X-APPID). Die App ID stellt bpost für Ihre Integration aus; fragen Sie den E-Commerce-Support von bpost (eol@bpost.be). Außerdem benötigen Sie die Carrier-ID Ihres Vertrags (68 = bpost). Ohne vollständige Schlüssel funktioniert das Transportunternehmen weiterhin mit Festpreisen, Kunden werden dann aber nicht aufgefordert, eine Abholstelle zu wählen.

VibeFox-Lizenzschlüssel: erhältlich 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 VibeFox bpost Cubee später in der Modulliste und klicken Sie dort 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. Geben Sie Ihre Preise und für die Abholstellen-Auswahl die bpost-API-Schlüssel ein (siehe Konfiguration). Klicken Sie auf Save.

Bei der Installation legt das Modul das Transportunternehmen bpost parcel locker mit dem Liefertext Pickup point or parcel locker an. Das Transportunternehmen ist mit der Zone Belgien und allen Kundengruppen verknüpft, ohne Steuerregel. Zonen, Kundengruppen, Lieferzeittext und Logo 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 bpost Cubee > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die ganze Seite speichert. Jedes Speichern löscht außerdem den gespeicherten API-Token und die zwischengespeicherten Listen der Abholstellen.

Die Seite zeigt Warnungen an, wenn etwas das Transportunternehmen oder die Auswahl stillschweigend ausblendet: Die Abholstellen-Auswahl ist aktiviert, aber die API-Schlüssel sind unvollständig; für Belgien (BE) gibt es keinen Preis und keinen Standardpreis; die letzte Verbindung zur bpost-API ist fehlgeschlagen; die Gewichtseinheit des Shops ist dem Modul unbekannt (festlegen unter International > Localization, Local units); oder das bpost-Transportunternehmen wurde nicht gefunden. Beim Speichern werden Zeilen von Country prices, die nicht gelesen werden konnten, in einer Warnung aufgelistet, ebenso ein Wert von Size prices, in dem keine Größe erkannt wurde. Ein Gewicht oder Betrag, der keine Zahl oder negativ ist, wird nicht gespeichert: Eine Warnung nennt das Feld, und der vorherige Wert bleibt erhalten. Ist Min weight (kg) größer als Max weight (kg), werden die Gewichte ebenfalls nicht gespeichert.

Allgemein

Enable/Disable: schaltet den Versand mit bpost parcel locker ein oder aus. Es ist derselbe Schalter wie der Status des Transportunternehmens unter Shipping > Carriers.

Name: der Name der Versandart, der dem Kunden an der Kasse angezeigt wird (der Name des Transportunternehmens). Standard: bpost parcel locker. Wenn Sie das Feld leer lassen, wird der Standard verwendet. Maximal 64 Zeichen; ein längerer Name wird abgelehnt und nichts gespeichert.

Tax status: None bedeutet, dass die Preise endgültig sind. Taxable mit einer Steuerregel fügt die Steuer dieser Regel zu Ihren Preisen hinzu. Die Auswahl wird am Transportunternehmen gespeichert.

bpost-API (Suche nach Abholstellen) (nur für die Abholstellen-Auswahl erforderlich)

Account ID (public key): der öffentliche Schlüssel Ihres bpost-Shipping-Platform-Kontos, zu finden unter Key management auf plugins.bpost.be. Wenn Sie dieses Feld leeren, wird auch die gespeicherte Passphrase entfernt.

Passphrase (private key): der private Schlüssel, mit dem jede Anfrage signiert wird (HMAC-SHA256). Er wird nie an bpost gesendet und nicht im Protokoll geschrieben. 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.

App ID (X-APPID): die Anwendungskennung, die bpost für Ihre Integration ausgestellt hat. Sie wird im Header X-APPID gesendet.

Carrier ID: das Transportunternehmen Ihres bpost-Shipping-Platform-Vertrags, dessen Abholstellen und Paketboxen aufgelistet werden. Standard: 68 (bpost). Andere Transportunternehmen in Ihrem Vertrag haben eigene IDs.

Abholstellen-Auswahl

Pickup points: zeigt die Auswahl für Abholstellen und Paketboxen an der Kasse. Standardmäßig aktiviert. Die Auswahl erscheint, und eine Abholstelle ist nur dann erforderlich, wenn alle drei API-Schlüssel ausgefüllt sind.

Search field width: die CSS-Breite des Feldes für Postleitzahl / Ort, z. B. 100% oder 300px. Standard: 100%.

Pickup point list width: die CSS-Breite der Liste der Abholstellen, z. B. 100% oder 400px. Standard: 100%.

Preise (in der Standardwährung Ihres Shops, ohne Steuern; bpost liefert über diese API keine Versandpreise)

Price by: wie der Preis bestimmt wird.

Country prices: eine Zeile pro Land in der Form CC=PREIS, z. B. BE=4.95. Die Zeile *=PREIS legt den Preis für alle anderen Länder fest, z. B. *=9.95. Sowohl Punkt als auch Komma werden als Dezimaltrennzeichen akzeptiert. Ungültige Zeilen werden ignoriert. Länder ohne Preis (wenn keine *-Zeile vorhanden ist) wird das Transportunternehmen nicht angeboten.

Size prices: wird verwendet, wenn Price by auf Paketgröße steht, in der Form S=3.50, M=4.50, L=6.00, XL=8.00. Die Größe ergibt sich aus dem Warenkorbgewicht: S bis 2 kg, M bis 5 kg, L bis 10 kg, XL darüber.

Calculation: Per order berechnet den Preis einmal. Per item (price x number of items) multipliziert ihn mit der Anzahl der Artikel im Warenkorb.

Preise werden auf die Dezimalstellen Ihrer Standardwährung gerundet und dann in der Warenkorbwährung des Kunden angezeigt.

Bedingungen

Min weight (kg): das minimale Warenkorbgewicht, damit das Transportunternehmen erscheint. Produktgewichte werden aus der Gewichtseinheit Ihres Shops umgerechnet. 0 bedeutet keine Grenze.

Max weight (kg): das Transportunternehmen wird ab diesem Warenkorbgewicht ausgeblendet. Standard: 30, weil bpost-Paketboxen Pakete bis 30 kg annehmen. 0 bedeutet keine Grenze.

Minimum order amount: zeigt das Transportunternehmen nur an, wenn die Zwischensumme des Warenkorbs diesen Betrag erreicht. Die Zwischensumme zählt versandpflichtige Produkte nach Rabatten ohne Steuern. Lassen Sie das Feld leer, um das Transportunternehmen immer anzuzeigen.

Kostenloser Versand

Free shipping: aktiviert die kostenlose Lieferung ab dem unten angegebenen Betrag.

Free shipping from: die Zwischensumme des Warenkorbs (versandpflichtige Produkte, nach Rabatten, ohne Steuern), ab der der Versand kostenlos ist. Wird nur verwendet, wenn Free shipping aktiviert ist. Das Land braucht trotzdem einen Preis, sonst wird das Transportunternehmen nicht angeboten.

Verfügbarkeit ohne Versandzonen

Normalerweise wird das Transportunternehmen in seinen Versandzonen unter Shipping > Carriers angeboten. Bei der Installation ist das die Zone Belgien.

Ignore shipping zones: bietet das Transportunternehmen in den unten genannten Ländern an, ohne es einer Zone hinzuzufügen. Das Transportunternehmen wird dann mit allen aktiven Zonen verknüpft, auch mit Zonen, die Sie später anlegen. Wenn Sie die Option wieder ausschalten, erhält das Transportunternehmen seine früheren Zonen zurück.

Countries: die Zielländer für diesen Modus. Standard: Belgien. Lassen Sie das Feld leer, um alle Länder zu verwenden, in die Sie liefern. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.

Erweitert

Debug log: protokolliert API-Anfragen und Preisberechnungen in logs/vfd_bpst_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Schlüssel und Tokens werden nie protokolliert.

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

Remove data on uninstall: ist die Option aktiviert, löscht die Deinstallation des Moduls seine Einstellungen und das Transportunternehmen. In Bestellungen gespeicherte Abholstellen bleiben immer erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem bpost-Preis. Nur versandpflichtige Produkte zählen: Virtuelle Produkte erhöhen das Gewicht nicht und sind nicht im Bestellbetrag enthalten. Das Modul prüft die Bedingungen: die Länder von Ignore shipping zones (falls aktiviert), das Warenkorbgewicht und den Mindestbestellwert. Dann nimmt es den Preis aus der Länderliste oder nach Paketgröße, multipliziert ihn im Modus je Artikel mit der Anzahl der Artikel und setzt ihn auf null, wenn der kostenlose Versand gilt. Für die Preisberechnung wird keine Anfrage an bpost gesendet.

Unter dem bpost-Transportunternehmen sieht der Kunde ein Feld Postal code or city, eine Schaltfläche Search und eine Liste der Abholstellen. Wählt der Kunde das Transportunternehmen und hat noch nicht gesucht, wird die Postleitzahl der Lieferadresse automatisch gesucht. Der Kunde kann eine andere Postleitzahl oder einen Ortsnamen eingeben. Jede Stelle wird mit Name und Adresse angezeigt. Es werden bis zu 50 Stellen aufgelistet. Die Liste wird auf Niederländisch abgerufen, wenn die Shopsprache Niederländisch ist, andernfalls auf Französisch.

Der Kunde muss eine Abholstelle wählen. Ohne Auswahl zeigt Continue im Lieferschritt Please select a bpost pickup point. an, und die Schaltfläche Place order wird auf der Seite mit derselben Meldung zurückgehalten. Nur eine Stelle aus der bpost-Liste für die Suche wird akzeptiert. Andernfalls sieht der Kunde The selected bpost pickup point is not in the list of your search. Please choose another one. Suche und Auswahl werden mit dem Warenkorb gespeichert, sodass ein Neuladen der Seite nichts verloren gehen lässt. Eine neue Suche löscht die vorherige Auswahl.

Um Abholstellen aufzulisten, sendet das Modul an bpost nur die gesuchte Postleitzahl oder den Ort, das Land und die Carrier-ID, signiert mit Ihren Schlüsseln. Der API-Token wird automatisch angefordert und erneuert. Lehnt bpost einen Token ab, wird einmal ein neuer angefordert und die Suche wiederholt. Suchergebnisse werden 6 Stunden lang zwischengespeichert. Antwortet bpost nicht, sieht der Kunde Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method., und das Modul versucht es nach 5 Minuten erneut. Das API-Timeout beträgt 15 Sekunden.

Wenn Sie das Transportunternehmen unter Shipping > Carriers bearbeiten, nachdem es Bestellungen hat, speichert PrestaShop es als neue Version des Transportunternehmens. Das Modul folgt der neuen Version automatisch.

Das Modul verwendet nur Festpreise. Es ruft keine Live-Tarife bei bpost ab, erstellt keine Sendungen, druckt keine Etiketten und verfolgt keine Pakete. Abholstellen werden als Liste angezeigt, nicht auf einer Karte. Erstellen Sie die Sendungen in Ihrem bpost-Shipping-Platform- oder Shipping-Manager-Konto; die ID der Abholstelle steht in der Bestellung.

Abholstellen

Beim Abschluss der Bestellung werden die gewählte Abholstelle (Name und Adresse) und ihre ID zusammen mit der Bestellung gespeichert. Auf der Bestellseite im Back Office zeigt der Block bpost pickup point die Stelle und ihre ID an, oder No pickup point was selected for this order. Klicken Sie auf Change, suchen Sie eine Postleitzahl oder einen Ort, wählen Sie eine andere Stelle aus der Liste und klicken Sie auf Save. Die Bestellung wird sofort aktualisiert, und die Seite zeigt Pickup point updated. Die Änderung wird im Debug-Log protokolliert, wenn Debug log aktiviert ist. Der Link Change ist nur verfügbar, wenn die API-Schlüssel ausgefüllt sind. Zum Speichern einer neuen Stelle benötigen Sie die Berechtigung zum Bearbeiten von Bestellungen; andernfalls zeigt die Seite Permission denied. an. Der Zugriff auf die Modulseiten ist nicht nötig.

Teilt PrestaShop einen Warenkorb in mehrere Bestellungen auf, bleibt die Abholstelle bei der ersten Bestellung. Die anderen Bestellungen haben keine Abholstelle, und das Debug-Log zeigt einen Fehler mit dem Namen der ersten Bestellung; legen Sie die Stelle für diese Pakete manuell bei bpost fest.

Kunden sehen die Abholstelle als bpost pickup point: auf der Bestellbestätigungsseite und in den Bestelldetails ihres Kontos. Sie wird auch dem Namen des Transportunternehmens in der Bestellbestätigungs-E-Mail hinzugefügt. Die neue Bestell-E-Mail an den Shop (wenn Sie das Modul für E-Mail-Benachrichtigungen verwenden) enthält ebenfalls die ID der Stelle.

Um Paketboxen und Heimlieferung gemeinsam anzubieten, verwenden Sie für die Heimlieferung in derselben Zone ein anderes Transportunternehmen. Die Auswahl der Abholstellen erscheint nur beim bpost-Transportunternehmen.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox bpost Cubee ist der erste Block unter Modules > Module Manager > VibeFox bpost Cubee > Configure, oberhalb der Einstellungen. Geben 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 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: presta-shipping-bpost-cubee 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).

Wird der Schlüssel nicht akzeptiert, zeigt der Block den Grund an, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nachdem sich die Shop-Adresse geändert hat 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 einer Multistore-Einrichtung. 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 das bpost-Transportunternehmen Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Das Frontend von PrestaShop weiß nicht, dass Sie im Back Office angemeldet sind, daher ist das Transportunternehmen auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte 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 automatisch erneut geprüft, während Sie im Back Office arbeiten: 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

bpost erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable/Disable eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob das Transportunternehmen die Zone des Landes und die Kundengruppe abdeckt, oder ob Ignore shipping zones aktiviert ist und das Land unter Countries steht. Prüfen Sie, ob das Land einen Preis hat oder eine Zeile *=PREIS existiert, und kontrollieren Sie die Gewichtsgrenzen und den Minimum order amount. Produkte können auf der Produktseite auch auf bestimmte Transportunternehmen beschränkt sein. Die Einstellungsseite zeigt eine Warnung, wenn Belgien keinen Preis hat.

Keine Auswahl für Abholstellen an der Kasse: Prüfen Sie, ob Pickup points aktiviert ist und Account ID (public key), Passphrase (private key) und App ID (X-APPID) ausgefüllt sind. Die Einstellungsseite zeigt eine Warnung, wenn die Schlüssel unvollständig sind.

Kunden sehen "Pickup points cannot be loaded right now": bpost hat nicht geantwortet oder die Schlüssel abgelehnt. Der Grund wird auf der Einstellungsseite und im Debug-Log angezeigt (Feld Log auf der Modulseite). Das Modul versucht es nach 5 Minuten automatisch erneut. Beim Speichern der Einstellungen wird sofort erneut versucht.

Für diese Postleitzahl oder diesen Ort wurden keine Abholstellen gefunden: bpost hat für diese Suche keine Stellen zurückgegeben. Bitten Sie den Kunden, eine benachbarte Postleitzahl oder einen Ortsnamen zu versuchen, und prüfen Sie die Carrier ID.

Preise mit Komma werden nicht verwendet: Sowohl 5,50 als auch 5.50 werden akzeptiert. Zeilen in Country prices, die nicht der Form CC=PREIS entsprechen, werden ignoriert; die Warnung nach dem Speichern listet sie auf.

Sind die Preise inklusive Steuern? Mit Tax status auf None sind die Preise endgültig. Mit einer Steuerregel Taxable fügt PrestaShop diese Steuer zu Ihren Preisen hinzu.

Die Seite meldet, dass das bpost-Transportunternehmen nicht gefunden wurde: Das Transportunternehmen wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, damit es neu angelegt wird.

Für Entwickler: Die Hooks actionVfdBpstApiUrl und actionVfdBpstApiLanguage ändern die API-Adresse von bpost und die Sprache der Abholstellen-Liste.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox bpost Cubee und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Der gespeicherte API-Token und die zwischengespeicherten Listen der Abholstellen werden immer entfernt. Ist Remove data on uninstall aktiviert, wird das Transportunternehmen gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, das Log und die Abholstellen nicht abgeschlossener Warenkörbe werden entfernt. Ist die Option ausgeschaltet, wird das Transportunternehmen nur deaktiviert und alle Einstellungen bleiben erhalten. Wenn Sie das Modul erneut installieren, erhält das Transportunternehmen den Status zurück, den es vor der Deinstallation hatte. Reset unter Modules > Module Manager funktioniert genauso, sodass ein deaktiviertes Transportunternehmen deaktiviert bleibt. In Bestellungen gespeicherte Abholstellen gehören zum Bestellverlauf und werden nie gelöscht.

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