VibeFox Blue Express 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.

Blue-Express-Konto (nur für Live-Tarife): Live-Tarife benötigen ein Blue-Express-E-Commerce-Konto und dessen API-Schlüssel (x-api-key). Fordern Sie ihn bei Blue Express an: developers.bluex.cl oder gpo.integraciones@bx.cl. Der von Ihnen genutzte Service (EX, PY oder MD) muss in Ihrem Blue-Express-Vertrag freigeschaltet sein. Wenn Sie nur Festpreise verwenden, benötigen Sie keinen API-Schlüssel.

Regionen in Chile: Für einen Live-Tarif muss die Lieferadresse eine chilenische Region haben. Hat Ihr Shop keine Regionen für Chile, kann das Modul sie für Sie hinzufügen (siehe Konfiguration).

Abholpunkte: Die Blue-Express-Karte wird im Browser des Kunden von widget-pudo.blue.cl geladen.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. 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.

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

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

4. Geben Sie den API-Schlüssel, den Service, den Code des Herkunftsbezirks (zum Beispiel SCL), den CLP-Wechselkurs, falls die Währung Ihres Shops nicht CLP ist, und die Festpreise (zum Beispiel CL=4500) ein. Aktivieren Sie Pickup point carrier, wenn Sie die Abholung an Blue-Express-Punkten anbieten möchten. Klicken Sie auf Save. Siehe Konfiguration.

Bei der Installation legt das Modul zwei Versanddienstleister an: Blue Express (Lieferung nach Hause, Lieferzeittext Home delivery, aktiviert) und Blue Express pickup point (Lieferzeittext Pickup at a Blue Express point, deaktiviert, bis Sie ihn aktivieren). Beide sind der Zone Chile und allen Kundengruppen zugeordnet. Sie können Zonen, Kundengruppen, Lieferzeit, Logo und Größenbeschränkungen unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis kommt immer aus dem Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Blue Express > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten Blue-Express-Tarife und Gemeindedaten. Oben auf der Seite erscheinen Warnungen zu Einstellungen, die die Versanddienstleister oder den Live-Tarif ausblenden würden: kein API-Schlüssel, Shop-Währung ist nicht CLP ohne Wechselkurs, leere Festpreistabelle, keine Regionen für Chile, eine Gewichts- oder Maßeinheit des Shops, die das Modul nicht kennt (Gewichte werden dann als kg und Maße als cm gelesen), oder ein gelöschter Versanddienstleister. Ungültige Werte werden mit einer Fehlermeldung abgelehnt, und es wird nichts gespeichert: ein leerer oder ungültiger Name des Versanddienstleisters, ein Name mit mehr als 64 Zeichen, eine negative oder ungültige Zahl oder Min weight (kg) größer als Max weight (kg). Die folgenden Bedingungen und Preise gelten für beide Versanddienstleister.

Allgemein

Enable/Disable: schaltet den Versanddienstleister für die Lieferung nach Hause ein oder aus. Dies ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Name: der Name des Versanddienstleisters, der an der Kasse für die Lieferung nach Hause angezeigt wird. Standard: Blue Express. Pflichtfeld, höchstens 64 Zeichen.

Tax status: None (no tax on shipping) oder Taxable mit einer Ihrer Steuerregeln. Die Preise von Blue Express enthalten IVA. Wählen Sie None, wenn PrestaShop keine Steuer obendrauf aufschlagen soll. Gilt für beide Versanddienstleister.

Abholung an Blue-Express-Punkten (PUDO)

Pickup point carrier: bietet die Lieferung an einen vom Kunden gewählten Blue-Express-Punkt an, als zweiter Versanddienstleister neben der Lieferung nach Hause. Standardmäßig deaktiviert. Dies ist derselbe Schalter wie der Status des Versanddienstleisters Blue Express pickup point unter Shipping > Carriers.

Pickup point name: der Name des Versanddienstleisters, der an der Kasse für die Abholung an einem Blue-Express-Punkt angezeigt wird. Standard: Blue Express pickup point. Pflichtfeld, höchstens 64 Zeichen.

Blue Express API (für Live-Tarife erforderlich)

API key: Ihr Blue-Express-API-Schlüssel (Header x-api-key). Ohne ihn werden nur die Festpreise verwendet. Nach dem Speichern bleibt das Feld leer und zeigt A key is saved - leave empty to keep it. an. Geben Sie einen neuen Wert nur ein, wenn Sie ihn ändern möchten. Setzen Sie das Häkchen bei Remove the saved API key und speichern Sie, um ihn zu löschen.

Service: der Blue-Express-Service für den Tarif: Express (EX) (Standard), Prioritario (PY) oder SameDay (MD). Er muss in Ihrem Blue-Express-Vertrag freigeschaltet sein.

Origin district code: der Blue-Express-Bezirkscode des Ortes, von dem Sie versenden, zum Beispiel SCL für Santiago (Standard). Fragen Sie bei Blue Express nach, wenn Sie unsicher sind.

CLP per 1 unit of store currency: Wenn die Standardwährung Ihres Shops nicht CLP ist, zeigt das Feld sie an, zum Beispiel CLP per 1 EUR. Die Preise von Blue Express sind in chilenischen Pesos (CLP). Geben Sie ein, wie viele CLP eine Einheit Ihrer Standardwährung wert ist, zum Beispiel 1050. Ohne diesen Wert werden keine Live-Tarife verwendet. Der Wert wird ignoriert, wenn die Shop-Währung CLP ist.

Preis

Rate source: so wird der Preis berechnet. Der Live-Tarif benötigt eine chilenische Adresse mit Region und Gemeinde (Stadt). Fehler werden im Protokoll festgehalten und nie dem Kunden angezeigt.

Fixed prices: eine Zeile pro Land im Format COUNTRY_CODE=PRICE, in der Standardwährung Ihres Shops, ohne Steuer, zum Beispiel CL=4500 in einem CLP-Shop oder CL=4.50 in einem EUR-Shop. Komma und Punkt werden als Dezimaltrennzeichen akzeptiert. Ungültige Zeilen werden ignoriert und beim Speichern in einer Warnung aufgelistet. Für ein Land ohne Zeile gibt es keinen Festpreis, daher werden die Versanddienstleister dort ausgeblendet, wenn der Festpreis benötigt wird. Festpreise können für jedes Land verwendet werden.

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 den Festpreis. Der API-Tarif gilt immer für die gesamte Sendung.

Bedingungen

Min weight (kg): blendet die Versanddienstleister aus, wenn der Warenkorb weniger wiegt. 0 bedeutet keine Grenze.

Max weight (kg): blendet die Versanddienstleister aus, wenn der Warenkorb mehr wiegt. Standard: 100. 0 bedeutet keine Grenze, ein leeres Feld bedeutet 100 kg. Min weight (kg) darf nicht größer sein als Max weight (kg).

Minimum order subtotal: zeigt die Versanddienstleister erst ab dieser Zwischensumme des Warenkorbs an (Shop-Währung, nach Rabatten, ohne Steuer). Leer lassen, um sie immer anzuzeigen.

Kostenloser Versand

Free shipping: aktiviert den kostenlosen Versand ab einer Zwischensumme des Warenkorbs.

Free from subtotal: die Zwischensumme des Warenkorbs (Shop-Währung, nach Rabatten, ohne Steuer), ab der der Versand kostenlos ist. Wird nur verwendet, wenn Free shipping aktiviert ist.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet beide Versanddienstleister in jeder Zone an. Die Länder werden dann durch die folgende Liste begrenzt. Später erstellte Zonen werden ebenfalls hinzugefügt. Wenn Sie die Option wieder ausschalten, erhalten die Versanddienstleister die Zonen zurück, die sie vorher hatten.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zu verwenden, in die Sie versenden. Wird nur mit Ignore shipping zones verwendet.

Erweitert

Debug log: protokolliert Anfragen und Entscheidungen in logs/vfd_blex_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. API-Fehler werden immer protokolliert. Der API-Schlüssel und Kundenadressen werden nie protokolliert. Schalten Sie das Protokoll aus, wenn Sie fertig sind.

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

Remove data on uninstall: wenn aktiviert, löscht die Deinstallation des Moduls die Einstellungen und die Versanddienstleister. In Bestellungen gespeicherte Abholpunkte bleiben erhalten.

Regionen in Chile (nur angezeigt, wenn Ihr Shop keine brauchbaren Regionen für Chile hat)

Blue Express benötigt für den Live-Tarif die Region einer chilenischen Adresse (RM, VS usw.). PrestaShop enthält standardmäßig keine chilenischen Regionen. Klicken Sie auf Add Chilean regions, um die 16 chilenischen Regionen als Bundesländer von Chile mit den Codes hinzuzufügen, die Blue Express verwendet, und um das Regionsfeld im Formular für chilenische Adressen anzuzeigen. Regionen, die Sie bereits haben, werden anhand von Code oder Name nicht doppelt hinzugefügt. Bis Sie auf die Schaltfläche klicken, wird nichts verändert. Sie können sie auch selbst unter International > Locations > States mit den Codes RM, VS usw. anlegen.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem Preis jedes Blue-Express-Versanddienstleisters. Nur physische Produkte zählen: Virtuelle Produkte erhöhen das Gewicht nicht und sind nicht in der Zwischensumme enthalten. Das Modul prüft Countries (mit Ignore shipping zones), das Gewicht des Warenkorbs und die Minimum order subtotal. Greift der kostenlose Versand, beträgt der Preis 0, und es wird keine Anfrage an Blue Express gesendet.

Für einen Live-Tarif muss die Adresse in Chile liegen und eine Region und eine Stadt (Gemeinde) haben. Das Modul bittet Blue Express zuerst, die Gemeinde zu erkennen, und fragt dann den Preis für den Service, den Herkunftsbezirk, das Ziel und die Pakete ab. Jedes Produkt wird mit Gewicht und Maßen in kg und cm gesendet. Produkte ohne Gewicht oder Größe werden mit 0,01 kg, 10 x 10 x 10 cm gesendet. Der angegebene Wert wird in CLP übermittelt. Der CLP-Preis wird in die Standardwährung Ihres Shops umgerechnet und dann in der Warenkorbwährung des Kunden angezeigt.

Tarife werden 1 Stunde lang und Gemeindedaten 12 Stunden lang zwischengespeichert. Ein fehlgeschlagener API-Aufruf wird 5 Minuten lang gemerkt, und das Timeout beträgt 10 Sekunden, damit eine langsame oder nicht erreichbare API nicht jede Aktualisierung des Checkouts verzögert. API-Fehler werden dem Kunden nie angezeigt: Der Versanddienstleister wird ausgeblendet, oder im Ersatzmodus wird der Festpreis verwendet. Der Grund wird im Protokoll festgehalten.

Wenn Sie einen Versanddienstleister unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul folgt der neuen Version automatisch.

Das Modul erstellt keine Sendungen oder Etiketten bei Blue Express, vergibt keine Sendungsnummern und zeigt keine Tracking-Updates an. Legen Sie die Sendung in Ihrem Blue-Express-Konto an. Es gibt keine regionalen Tariftabellen je Gemeinde: Verwenden Sie den API-Tarif von Blue Express oder einen Festpreis je Land. Live-Tarife funktionieren nur für Chile.

Abholpunkte

Wenn der Kunde im Versandschritt Blue Express pickup point auswählt, erscheint darunter ein Feld mit der Schaltfläche Choose pickup point. Die Schaltfläche öffnet die offizielle Blue-Express-Karte, auf der der Kunde einen Punkt auswählt. Der gewählte Punkt wird mit Name und Adresse angezeigt, und die Schaltfläche wird zu Change pickup point. Der Punkt wird im Warenkorb gespeichert, und der Tarif wird mit dem Abholpreis (PUDO) von Blue Express neu berechnet. Ändert sich der Preis, wird die Seite neu geladen, um ihn anzuzeigen. Bis ein Punkt gewählt ist, zeigt der Versanddienstleister den Preis für die Lieferung nach Hause.

Der Kunde kann ohne Punkt nicht fortfahren: Please choose a Blue Express pickup point. Der Shop prüft dies, wenn der Kunde im Versandschritt auf Continue klickt. Ein fehlerhafter Punktcode wird mit The selected Blue Express pickup point is not valid. Please choose it again on the map. abgelehnt, und die vorherige Auswahl bleibt bestehen.

Beim Aufgeben der Bestellung wird der Punkt mit seinem Blue-Express-Agenturcode, Namen und seiner Adresse in der Bestellung gespeichert. Auf der Bestellseite im Admin-Bereich wird er im Block Blue Express pickup point angezeigt. Klicken Sie auf Edit, um mit Choose on the Blue Express map einen anderen Punkt zu wählen oder den Agency code, den Name und die Address von Hand einzugeben, und klicken Sie dann auf Save pickup point. Die Änderung wird als private Bestellnachricht erfasst. Für die Änderung des Punkts sind nur Bearbeitungsrechte für Bestellungen nötig, kein Zugriff auf die Modulseiten. Der Kunde sieht den Punkt auf der Bestellbestätigungsseite, auf der Bestelldetailseite und in der Bestellbestätigungs-E-Mail neben dem Namen des Versanddienstleisters. Die neue Bestell-E-Mail an den Shop (aus dem Modul Mail alerts) zeigt ebenfalls den Agenturcode. Bestehende Bestellungen behalten ihre Abholpunktdaten.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Blue Express ist der erste Block auf Modules > Module Manager > VibeFox Blue Express > Configure, über den 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 gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-shipping-blue-express 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. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie einen Domain-Platz in Ihrem Konto 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 Haupt-Shops, auch bei einer Multistore-Konfiguration. Wenn Sie den Schlüssel aus dem Shop entfernen, wird sein Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne einen aktiven Schlüssel werden die Blue-Express-Versanddienstleister Kunden an der Kasse nicht angezeigt und es wird kein Tarif berechnet. Die PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher wird der Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht an der Kasse 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, 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 wöchentlich. Ein Cron-Job ist nicht nötig. Deinstallation oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Blue Express erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable/Disable (bzw. Pickup point carrier) eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe abdeckt, oder aktivieren Sie Ignore shipping zones und prüfen Sie Countries. Lesen Sie die Warnungen oben auf der Modulseite. Prüfen Sie die Gewichtsgrenzen, die Minimum order subtotal und ob Fixed prices eine Zeile für das Land hat, wenn Sie Festpreise oder den Ersatz verwenden. Produkte können auf der Produktseite auch auf bestimmte Versanddienstleister beschränkt sein.

Live-Tarife erscheinen nicht: Bei Blue Express API only werden die Versanddienstleister ausgeblendet, wenn kein Tarif vorliegt. Aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Modulseite an. Typische Ursachen: kein API-Schlüssel, Shop-Währung nicht CLP ohne Wechselkurs, fehlende Region oder Gemeinde in der Adresse, eine von Blue Express nicht erkannte Gemeinde oder ein API-Fehler (zum Beispiel HTTP 401 oder 403, wenn der API-Schlüssel abgelehnt wird). Mit Blue Express API, fixed price if the API gives no rate erhalten Kunden weiterhin den Festpreis, während Sie das Problem beheben.

Chilenische Adressen haben keine Region: Die Seite zeigt eine Warnung über fehlende Regionen. Klicken Sie auf der Modulseite auf Add Chilean regions. Kunden, deren Adressen ohne Region gespeichert wurden, müssen die Adresse bearbeiten und die Region auswählen.

Steuer wird auf den Blue-Express-Preis aufgeschlagen: Die Preise von Blue Express enthalten IVA. Setzen Sie Tax status auf None (no tax on shipping).

Die Karte öffnet sich nicht: Die Karte wird im Browser des Kunden von widget-pudo.blue.cl geladen. Diese Adresse muss daher erreichbar und auf Ihrer Website nicht blockiert sein.

Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten Tarife und Gemeindedaten gelöscht.

Die Seite meldet, dass ein Blue-Express-Versanddienstleister fehlt: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn erneut anzulegen. Das Zurücksetzen behält Ihre Einstellungen und den Status der Versanddienstleister.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Blue Express und wählen Sie Uninstall. Der Lizenzschlüssel, der Lizenzstatus und die zwischengespeicherten Tarife werden immer entfernt. Ist Remove data on uninstall aktiviert, werden beide Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, das Protokoll und die Abholpunkte, die mit keiner Bestellung verknüpft sind, werden entfernt. Ist die Option ausgeschaltet, werden die Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Wird das Modul erneut installiert, werden die Versanddienstleister mit dem vorherigen Status wiederhergestellt. In Bestellungen gespeicherte Abholpunkte werden niemals entfernt.

Blue Express ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Blue Express verbunden noch wird es von Blue Express unterstützt.