VibeFox Chilexpress for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer, mit der cURL-Erweiterung für Live-Tarife. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Chilexpress-API-Schlüssel (nur für Live-Tarife): Erstellen Sie ein Konto im Entwicklerportal von Chilexpress (developers.wschilexpress.com) und abonnieren Sie zwei Produkte: Rating (Cotizador) und Coverage (Coberturas / Georreferencia). Jedes Produkt hat einen eigenen Abonnementschlüssel. Testschlüssel funktionieren nur mit der Testumgebung; Produktionsschlüssel werden Geschäftskunden von Chilexpress mit einem Kundenvertrag ausgestellt. Sie benötigen außerdem den Chilexpress-County-Code der Comuna, von der Sie versenden, zum Beispiel STGO. Wenn Sie nur Festpreise verwenden, brauchen Sie keine API-Schlüssel.

Chilenische Regionen (nur für Live-Tarife): Live-Tarife benötigen die Region der Lieferadresse. PrestaShop enthält standardmäßig keine chilenischen Regionen; das Modul kann sie für Sie hinzufügen (siehe unten Chilean regions). Das Land Chile muss im Shop vorhanden sein.

VibeFox-Lizenzschlüssel: Er wird auf vibefox.net erworben. 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 VibeFox Chilexpress in der Modulliste und klicken Sie dort 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. Füllen Sie die Tabelle Country prices aus. Für Live-Tarife geben Sie beide Abonnementschlüssel, Ihren Versand-County-Code und, falls die Shopwährung nicht CLP ist, den CLP-Wechselkurs ein. Klicken Sie auf Add Chilean regions, falls die Seite dazu auffordert. Wählen Sie dann die Tarifquelle (siehe Konfiguration) und klicken Sie auf Save.

Bei der Installation legt das Modul den Versanddienstleister Chilexpress mit dem Lieferzeittext Chilexpress courier an. Der Versanddienstleister ist der Zone Chile und allen Kundengruppen zugeordnet. Zonen, Kundengruppen, Lieferzeit, Logo und Größenbegrenzungen können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis kommt immer aus dem Modul. Um Chilexpress in anderen Zonen anzubieten, fügen Sie diese dort dem Versanddienstleister hinzu oder aktivieren Sie Ignore shipping zones.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Chilexpress > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten Chilexpress-Tarife und Comuna-Listen. Änderungen erfordern die Berechtigung "configure" für das Modul; ohne sie zeigt die Seite You do not have permission to configure this module.

Die Seite listet Probleme oben auf: API-Tarife sind ausgewählt, aber ein Schlüssel, der Versand-County-Code oder der CLP-Wechselkurs fehlt; die Preistabelle hat keine Zeile für Chile oder den Standard; der Shop hat keine chilenischen Regionen oder im chilenischen Adressformular kein Regionsfeld; die Gewichts- oder Maßeinheit des Shops ist dem Modul nicht bekannt (dann wird sie als kg bzw. cm gelesen; stellen Sie sie unter International > Localization, Local units ein); der Versanddienstleister wurde gelöscht. Zahlen können mit Punkt oder Komma eingegeben werden, wie in der Sprache Ihres Back Office. Eine ungültige oder negative Zahl, ein CLP exchange rate von 0, ein Min weight (kg) über dem Max weight (kg) oder ein Name mit mehr als 64 Zeichen ist ein Fehler, und es wird nichts gespeichert, bis Sie ihn korrigieren.

Allgemein

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

Name: der Name der Versandmethode, den der Kunde an der Kasse sieht. Es ist der Name des Versanddienstleisters. Standard: Chilexpress. Pflichtfeld, bis zu 64 Zeichen.

Tax: die Steuerregel des Versanddienstleisters oder No tax (der Standard für einen neuen Versanddienstleister). Chilexpress-API-Tarife werden genau so verwendet, wie sie angeboten werden. Wählen Sie No tax, wenn das Angebot bereits IVA enthält und Ihr Shop darauf noch Steuer aufschlagen würde.

Tarife

Rate source: woher der Preis kommt.

Live-Tarife sind nur für Ziele in Chile verfügbar. Andere Länder verwenden immer die Festpreise.

Country prices: eine Tabelle der Zielländer mit einer Spalte Price und optionalen Preisen nach Paketgröße in der Standardwährung Ihres Shops, ohne Steuern. Die Größe ergibt sich aus dem Warenkorbgewicht: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg, XL über 5 kg. Eine auf 0 belassene Größe verwendet Price. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorb-Symbol, um eine zu entfernen. Die Zeile * Default gilt für Länder ohne eigene Zeile. Ein Land ohne Zeile (und ohne * Default) erhält keinen Festpreis, daher wird der Versanddienstleister dort ausgeblendet. Eine Zeile, deren Preis und Größenpreise alle 0 sind, bedeutet kostenlosen Versand. Eine leere Tabelle wird mit einer Zeile für Chile zu 0 angezeigt; die letzte Zeile lässt sich nicht entfernen, sondern nur auf 0 zurücksetzen. Geben Sie deshalb echte Preise ein, bevor Sie die Seite speichern. Ein doppeltes Land oder ein ungültiger Preis wird korrigiert (das Duplikat wird ignoriert, der Preis auf 0 gesetzt), und eine Warnung listet die Korrekturen auf.

Calculation type: Per order berechnet den Festpreis einmal. Per item (fixed price x number of items) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Ein Chilexpress-API-Tarif wird immer für das gesamte Paket angeboten.

Chilexpress-API (Live-Tarife)

Der Abschnitt beginnt mit Links zum Entwicklerportal und zu den Abonnementseiten für Rating und Coverage.

Test environment: verwendet die Testumgebung von Chilexpress (qaservices.wschilexpress.com). Nutzen Sie sie mit Testschlüsseln und schalten Sie sie in einem Live-Shop aus.

Rating API key: der Abonnementschlüssel des Produkts Rating (Cotizador).

Coverage API key: der Abonnementschlüssel des Produkts Coverage (Coberturas / Georreferencia). Er dient dazu, den Chilexpress-County-Code der Comuna des Kunden zu finden (das Feld City der Adresse zusammen mit der Region).

Nach dem Speichern bleibt ein Schlüsselfeld leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Der Schlüssel wird so gespeichert, wie Sie ihn eingeben; nur Leerzeichen am Rand werden entfernt.

Remove the saved Rating API key und Remove the saved Coverage API key: werden nur angezeigt, wenn ein Schlüssel gespeichert ist. Aktivieren Sie die Option und klicken Sie auf Save, um den Schlüssel zu löschen.

Origin county code: der Chilexpress-County-Code (Comuna), von dem Sie versenden, 2 bis 5 Buchstaben, zum Beispiel STGO (Santiago Centro), PROV (Providencia) oder VALP (Valparaíso). Nach der Installation ist er leer. Ein Wert, der kein County-Code ist, wird mit einem Fehler abgelehnt.

Service: der Chilexpress-Service, der für den Tarif verwendet wird. Wird er für das Ziel nicht angeboten, wird der günstigste verfügbare Service verwendet.

CLP exchange rate: Chilexpress rechnet in chilenischen Pesos. Er wird nur benötigt, wenn die Standardwährung Ihres Shops nicht CLP ist: der Preis von 1 CLP in dieser Währung, zum Beispiel 0.001. Ohne ihn werden API-Tarife nicht verwendet. Ist die Shopwährung CLP, lassen Sie das Feld leer. Der Wert muss größer als 0 sein.

Chilean regions: Die Comunas Chiles werden je Region abgefragt, daher benötigen Live-Tarife die Region der Adresse. Hat der Shop keine chilenischen Regionen, zeigt das Feld die Schaltfläche Add Chilean regions. Sie fügt die 16 Regionen als Bundesländer von Chile hinzu (ISO-Codes RM, VS …), aktiviert "Contains states" für Chile und fügt das Regionsfeld zum chilenischen Adressformular hinzu. Regionen, die bereits vorhanden sind (anhand von Code oder Name), werden nicht doppelt angelegt. Wenn alles eingerichtet ist, zeigt das Feld Chilean addresses have a region mit der Anzahl der Regionen.

Verfügbarkeit

Min weight (kg): das minimale Warenkorbgewicht, damit der Versanddienstleister erscheint. 0 bedeutet keine Grenze.

Max weight (kg): der Versanddienstleister wird oberhalb dieses Warenkorbgewichts ausgeblendet. Standard: 25. 0 bedeutet keine Grenze; ein leeres Feld bedeutet 25 kg. Min weight (kg) darf nicht größer sein als dieser Wert.

Minimum subtotal: Der Versanddienstleister wird nur angezeigt, wenn die Zwischensumme des Warenkorbs (versandpflichtige Produkte, nach Rabatten, ohne Steuern) mindestens diesen Betrag erreicht. Lassen Sie das Feld leer, um ihn immer anzuzeigen.

Ignore shipping zones: bietet den Versanddienstleister für die unten genannten Länder an, auch wenn deren Zone ihm nicht zugeordnet ist: Der Versanddienstleister wird allen Zonen zugeordnet, und später angelegte Zonen werden ebenfalls zugeordnet. Wenn Sie es ausschalten, erhält der Versanddienstleister seine vorherigen Zonen zurück.

Countries: die Zielländer für diesen Modus, gewählt aus den aktiven Ländern des Shops. Lassen Sie das Feld leer, um alle Länder zu erlauben. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.

Kostenloser Versand

Free shipping: aktiviert die Schwelle für kostenlosen Versand.

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. In diesem Fall wird keine API-Anfrage gestellt.

Erweitert

Debug log: schreibt API-Anfragen und Tarifberechnungen in logs/vfd_chx_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. API-Schlüssel und Kundenadressen werden nie protokolliert.

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

Remove data on uninstall: ist die Option aktiviert, löscht die Deinstallation des Moduls alle Moduleinstellungen, den Versanddienstleister, die zwischengespeicherten Tarife, die Protokolle und die mit Bestellungen gespeicherten Services. Ist sie deaktiviert, bleibt alles für eine erneute Installation erhalten. Bestellungen selbst bleiben immer erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem Chilexpress-Preis. Gezählt werden nur versandpflichtige Produkte: Virtuelle Produkte haben kein Gewicht und fließen nicht in die Zwischensumme ein. Die Zwischensumme wird nach Warenkorbregeln (Gutscheinen) ohne Steuern in der Standardwährung Ihres Shops ermittelt. 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 Chilexpress gesendet.

Bei einer Adresse in Chile und einer API-Tarifquelle übernimmt das Modul die Region der Adresse und die Comuna aus dem Feld City und sucht den Chilexpress-County-Code in der Comuna-Liste dieser Region (Coverage API). Akzente, Leerzeichen und Schreibvarianten werden ignoriert, sodass Ñuñoa und Nunoa übereinstimmen und Santiago mit Santiago Centro. Ein County-Code, der direkt im Feld City eingetragen wird, wird ebenfalls akzeptiert. Danach sendet das Modul an die Rating API den Herkunfts- und den Ziel-County-Code, das Warenkorbgewicht (mindestens 0,1 kg), die Paketabmessungen (Länge und Breite des größten Produkts, Höhen gestapelt) und die Zwischensumme des Warenkorbs in CLP als Warenwert. Chilexpress liefert seine Services zurück; das Modul verwendet den gewählten oder den günstigsten Service und rechnet den Betrag in Pesos in die Standardwährung Ihres Shops um. Der Preis wird auf die Nachkommastellen dieser Währung gerundet und danach in der Warenkorbwährung des Kunden angezeigt.

Tarife werden 1 Stunde und Comuna-Listen 7 Tage zwischengespeichert. Eine fehlgeschlagene Anfrage wird 5 Minuten gemerkt, damit eine langsame oder nicht erreichbare API nicht jede Aktualisierung der Kasse verlangsamt. Das API-Timeout beträgt 10 Sekunden. Gibt Chilexpress einen Fehler zurück, keinen Service mit Preis oder ist die Comuna oder Region unbekannt, sieht der Kunde keine Fehlermeldung. Im reinen API-Modus wird der Versanddienstleister ausgeblendet, sonst wird der Festpreis verwendet. Der Grund wird im Debug-Protokoll festgehalten.

Wenn Sie den 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 berechnet nur Tarife. Es erstellt keine Sendungen oder Transportaufträge (OT), druckt keine Etiketten, bucht keine Abholungen und verfolgt keine Pakete; buchen Sie die Sendung in Ihrem Chilexpress-Konto. Kunden können keine Chilexpress-Filiale wählen, und es gibt keine Comuna-Auswahl: Der Kunde gibt die Comuna im Standardfeld City ein. Internationale Sendungen verwenden die Festpreise.

Bestellungen

Wenn eine Bestellung mit dem Versanddienstleister Chilexpress aufgegeben wird, speichert das Modul, wie sein Preis berechnet wurde. Die Bestellseite im Back Office zeigt einen Block Chilexpress mit Chilexpress service (bei einem Live-Tarif der von Chilexpress angebotene Service, zum Beispiel Express) und Price source: Live rate (Chilexpress Rating API), Fixed price oder Free shipping.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Chilexpress ist der erste Block auf Modules > Module Manager > VibeFox Chilexpress > 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-chilexpress und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Den Schlüssel können nur Mitarbeiter mit der Berechtigung Configure für das Modul ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Wenn der Schlüssel nicht akzeptiert wird, 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 Shopadresse 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 den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne einen aktiven Schlüssel wird der Versanddienstleister Chilexpress Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Das PrestaShop-Shop-Frontend 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, es aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen.

Wenn eine Lizenz abläuft, arbeitet das Modul weiter, aber Updates und Support erfordern 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 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

Chilexpress 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 der Versanddienstleister die Zone des Landes des Kunden und die Kundengruppe abdeckt (oder ob Ignore shipping zones aktiviert ist und das Land unter Countries steht). Prüfen Sie die Gewichtsgrenzen und die Minimum subtotal. Bei Festpreisen prüfen Sie, ob das Land oder * Default eine Zeile hat. Produkte können auch auf der Produktseite auf bestimmte Versanddienstleister beschränkt sein.

Der Versand in Chile ist kostenlos, obwohl er es nicht sein sollte: Die Zeile für Chile (oder * Default) in Country prices hat 0 bei Price und in den Größenspalten. Geben Sie die Preise ein und klicken Sie auf Save.

Der Live-Tarif wird nicht angezeigt, stattdessen wird der Festpreis verwendet: Prüfen Sie zuerst die Warnungen oben auf der Modulseite. Andernfalls aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Modulseite an. Typische Ursachen: Die Adresse hat keine Region oder das Regionsfeld fehlt (verwenden Sie Add Chilean regions), eine Comuna, die Chilexpress nicht kennt (prüfen Sie das Feld City und die Region), ein Schlüssel für das falsche Produkt oder die falsche Umgebung oder ein Ziel ohne Chilexpress-Abdeckung.

HTTP 401 oder 403 im Protokoll: Der Abonnementschlüssel ist falsch, inaktiv oder gehört zu einem anderen Produkt oder einer anderen Umgebung. Testschlüssel funktionieren nur, wenn Test environment eingeschaltet ist.

API-Tarife werden in einem Shop mit anderer Währung nicht verwendet: Geben Sie den CLP exchange rate ein.

Sind API-Tarife mit oder ohne IVA? Sie werden genau so verwendet, wie Chilexpress sie anbietet. Wenn Ihr Shop auf den Versand Steuer aufschlägt und das Angebot bereits IVA enthält, setzen Sie Tax auf No tax.

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

Die Seite meldet "The Chilexpress carrier was not found": Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn erneut anzulegen.

Die Seite meldet "The country Chile does not exist in this shop": Fügen Sie Chile unter International > Locations > Countries hinzu oder aktivieren Sie es und verwenden Sie danach Add Chilean regions.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Chilexpress und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Tarife und Comuna-Listen werden immer entfernt. Ist Remove data on uninstall aktiviert, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, das Protokoll und die mit Bestellungen gespeicherten Services werden entfernt. Ist sie deaktiviert, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Eine erneute Installation des Moduls stellt den gespeicherten Versanddienstleister mit seinem früheren Status wieder her. Chilenische Regionen, die mit Add Chilean regions hinzugefügt wurden, bleiben im Shop erhalten.

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