VibeFox Envioclick for PrestaShop — Hilfe

Voraussetzungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Envioclick-Konto (nur für Live-Tarife): ein Envioclick-Konto in Mexiko oder Kolumbien mit API-Zugang. Der API-Schlüssel befindet sich in Ihrem Envioclick-Konto unter Mi cuenta (oben rechts) > Información del API. Wenn Sie nur feste Preise verwenden, benötigen Sie kein Envioclick-Konto.

User-Agent (nur Mexiko): Envioclick Mexiko verlangt bei jeder API-Anfrage einen User-Agent-Wert. Fragen Sie den Envioclick-Support danach (soporte.tecnico@envioclick.com).

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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 Envioclick in der Modulliste und klicken Sie dort auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel unter License key im Lizenzbereich oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie den API-Schlüssel ein, wählen Sie das API-Land, tragen Sie den User-Agent (Mexiko), die Herkunfts-Postleitzahl bzw. den DANE-Code und die Herkunftsadresse ein. Wenn die Standardwährung Ihres Shops weder MXN noch COP ist, geben Sie den Währungsumrechnungskurs ein. Klicken Sie für Kolumbien auf Add Colombian departments, falls die Seite diese Option anbietet.

5. Optional können Sie feste Preise je Land und Ausweichkosten hinzufügen und danach auf Save klicken.

Bei der Installation legt das Modul den Versanddienstleister Envioclick Shipping mit dem Lieferzeittext Courier delivery by the best Envioclick carrier an. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugewiesen. Zonen, Kundengruppen, Lieferzeit, Logo und Größenlimits können Sie 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 Envioclick > Configure. Jeder Abschnitt hat seinen eigenen Button Save, der die gesamte Seite speichert. Jedes Speichern leert außerdem die zwischengespeicherten Envioclick-Tarife. Zahlenfelder akzeptieren sowohl den Punkt als auch das Komma als Dezimaltrennzeichen.

Wenn ein API-Schlüssel hinterlegt ist, zeigt die Seite oben Warnungen an, falls Live-Tarife nicht funktionieren können: kein Umrechnungskurs für eine Shopwährung außer MXN oder COP, kein User-Agent für Mexiko, keine Herkunfts-Postleitzahl oder kein DANE-Code oder keine Herkunftsadresse für Kolumbien. Die Seite warnt außerdem, wenn die Gewichts- oder Maßeinheit Ihres Shops nicht erkannt wird; stellen Sie kg, g, lb oder oz sowie cm, mm, m oder in unter International > Localization (Local units) ein. Beim Speichern prüft das Modul, ob Method title ein gültiger Versanddienstleistername ist, ob Zahlenfelder nicht negative Zahlen enthalten, ob der Currency conversion rate größer als 0 ist, ob Minimum weight nicht größer als Maximum weight ist und ob der Herkunftscode für Mexiko 5 Stellen und für Kolumbien 8 Stellen (oder der 5-stellige Gemeindecode) hat. Schlägt eine Prüfung fehl, wird ein Fehler angezeigt und nichts gespeichert.

Allgemein

Zonen, Kundengruppen und Größenlimits des Versanddienstleisters werden unter Shipping > Carriers festgelegt (oder Sie verwenden unten Ignore shipping zones). Die Einstellungen auf dieser Seite gelten für alle Zonen.

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

Method title: der Name des Versanddienstleisters, den der Kunde im Warenkorb und an der Kasse sieht. Standard: Envioclick Shipping. Pflichtfeld.

Carrier in the title: zeigt den Envioclick-Versanddienstleister und die voraussichtliche Lieferzeit eines Live-Tarifs unter dem Versanddienstleister an der Kasse an, zum Beispiel „Estafeta Express, 1 day“. Der Versanddienstleister wird in jedem Fall in der Bestellung gespeichert und auf den Bestellseiten angezeigt. Standard: ein.

Envioclick-API (Live-Tarife)

Optional. Ohne API-Schlüssel werden nur die festen Preise verwendet. Der Abschnitt verlinkt auf die Envioclick-API-Dokumentation für Mexiko und Kolumbien. Live-Tarife werden nur für Ziele im API-Land angefragt. Versand in andere Länder nutzt die festen Preise.

API key: Ihr Envioclick-API-Schlüssel aus Mi cuenta > Información del API. Er wird im Header „Authorization“ gesendet. 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.

Remove the saved API key: wird nur angezeigt, solange ein Schlüssel gespeichert ist. Wählen Sie Yes und speichern Sie, um den Schlüssel zu löschen; danach werden nur die festen Preise verwendet. Ein im Feld API key eingegebener Schlüssel ersetzt den gespeicherten.

API country: das Land Ihres Envioclick-Kontos.

Colombian departments: nur für Kolumbien. PrestaShop hat standardmäßig keine kolumbianischen Departamentos. Ohne sie werden nur Stadtnamen erkannt, die in Kolumbien eindeutig sind; das Departamento unterscheidet Gemeinden mit gleichem Namen. Der Button Add Colombian departments fügt die 33 Departamentos als Bundesstaaten von Kolumbien hinzu (ISO-Codes ANT, DC usw.), aktiviert „Contains states“ für Kolumbien und ergänzt das Departamento-Feld im kolumbianischen Adressformular. Bereits vorhandene Departamentos werden nicht doppelt angelegt. Sobald alles eingerichtet ist, zeigt das Feld an, wie viele Departamentos die kolumbianischen Adressen haben.

User-Agent (Mexiko): der Wert, den der Envioclick-Support ausstellt (soporte.tecnico@envioclick.com), zum Beispiel EcUserAgent-2/123456. Für Mexiko erforderlich; ohne ihn werden für Mexiko keine Live-Tarife angefragt. Für Kolumbien optional.

Carrier choice: Cheapest (Standard) oder Fastest (then cheapest). Envioclick liefert Tarife mehrerer Versanddienstleister, und der Kunde erhält einen einzigen Tarif.

Branch pickup rates: berücksichtigt außerdem die Tarife „Ocurre“, bei denen der Kunde das Paket in der Filiale des Versanddienstleisters abholt. Ist die Option aus, werden nur Tarife für die Lieferung an die Haustür verwendet. Nachnahme-Dienste (COD) werden nie verwendet. Standard: aus.

Currency conversion rate: Envioclick berechnet in MXN (Mexiko) oder COP (Kolumbien). Wenn die Standardwährung Ihres Shops eine andere ist, geben Sie den Wert von 1 MXN oder 1 COP in der Währung Ihres Shops ein, zum Beispiel 0.05. Der angegebene Warenwert des Pakets wird auf die gleiche Weise umgerechnet. Lassen Sie das Feld leer, wenn die Shopwährung MXN oder COP ist. Ohne den Kurs werden in einer anderen Währung keine Live-Tarife verwendet.

Versand von

Wird für Live-Tarife verwendet. Leere Felder werden aus der Shopadresse unter Shop Parameters > Contact > Stores übernommen, wenn sich der Shop im API-Land befindet.

Origin postcode / DANE code: Mexiko: die 5-stellige Postleitzahl. Kolumbien: der 8-stellige DANE-Code der Gemeinde, zum Beispiel 11001000 für Bogotá; der 5-stellige Gemeindecode (11001) funktioniert ebenfalls.

Origin address: Straße und Hausnummer der Abholadresse. Für Kolumbien erforderlich, für Mexiko optional.

Feste Preise

Werden verwendet, wenn kein Live-Tarif vorliegt: kein API-Schlüssel, ein Ziel außerhalb des API-Landes oder ein API-Fehler bzw. kein Versanddienstleister für die Strecke.

Price per country: eine Tabelle mit zweistelligen Ländercodes und Preisen in der Standardwährung Ihres Shops, ohne Steuern. Klicken Sie auf Add row, um ein Land hinzuzufügen, und auf das Papierkorb-Symbol, um eines zu entfernen. Verwenden Sie * als Ländercode für alle Länder ohne eigene Zeile.

Fallback cost: wird verwendet, wenn kein Live-Tarif vorliegt und keine Zeile der Tabelle passt. Lassen Sie das Feld leer, um den Versanddienstleister in diesem Fall auszublenden.

Fixed price applies: Per order berechnet den Preis einmal. Per item (price × quantity) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Envioclick-Live-Tarife gelten immer pro Sendung.

Bedingungen

Minimum weight: blendet den Versanddienstleister unterhalb dieses Warenkorbgewichts aus, in kg. 0 bedeutet keine Grenze.

Maximum weight: blendet den Versanddienstleister oberhalb dieses Warenkorbgewichts aus, in kg. Standard: 25. 0 bedeutet keine Grenze.

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

Free shipping from: kostenloser Versand, wenn die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern) diesen Betrag erreicht. Dann wird keine Anfrage an Envioclick gesendet. Lassen Sie das Feld leer, um nie kostenlosen Versand anzubieten.

Tax: die Steuerregel des Versanddienstleisters oder No tax. Envioclick-Tarife enthalten die Steuern der Versanddienstleister bereits. Wählen Sie daher No tax, um die Versandkosten nicht doppelt zu versteuern.

Verfügbarkeit ohne Versandzonen

Normalerweise wird der Versanddienstleister in den Zonen angeboten, die ihm unter Shipping > Carriers zugewiesen sind.

Ignore shipping zones: bietet Envioclick für die unten genannten Länder an, auch wenn der Versanddienstleister ihrer Zone nicht zugewiesen ist. Ist die Option eingeschaltet, wird der Versanddienstleister allen Zonen zugewiesen, auch später angelegten. Ist sie ausgeschaltet, erhält der Versanddienstleister seine vorherigen Zonen zurück.

Countries: die Zielländer für diesen Modus. Lassen Sie das Feld leer, um alle Länder zu verwenden, in die Sie versenden (aktive Länder). Wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.

Erweitert

Debug log: protokolliert Tarifberechnungen und API-Fehler in logs/vfd_evc_debug.log.php im Modulordner. Die Datei kann nicht über den Webbrowser geöffnet werden. Der API-Schlüssel und die Kundenadressen werden nicht protokolliert. Solange das Protokoll ausgeschaltet ist, wird nichts geschrieben. Schalten Sie es nach Abschluss der Arbeiten wieder aus.

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

Remove data on uninstall: ist die Option eingeschaltet, löscht die Deinstallation des Moduls die Envioclick-Einstellungen, den Versanddienstleister, die zwischengespeicherten Tarife und die Protokolle. Der Versanddienstleister, der bei früheren Bestellungen gespeichert wurde, bleibt erhalten. Ist die Option ausgeschaltet, bleibt alles für eine erneute Installation erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem Envioclick-Preis. Nur physische Produkte zählen: Virtuelle Produkte erhöhen das Gewicht nicht und sind nicht im Bestellbetrag enthalten. Das Modul prüft zuerst die Bedingungen: die Länder von Ignore shipping zones, das Warenkorbgewicht und den Mindestbestellwert. Gilt kostenloser Versand, beträgt der Preis 0, und es wird keine Anfrage an Envioclick gesendet.

Ist ein API-Schlüssel hinterlegt und liegt das Ziel im API-Land, fordert das Modul bei Envioclick Tarife an. In Mexiko erfolgt die Anfrage, sobald der Kunde eine 5-stellige Postleitzahl eingegeben hat. In Kolumbien erfolgt sie, sobald Departamento und Gemeinde erkannt wurden (Akzente und Groß-/Kleinschreibung spielen keine Rolle). Das Modul wählt den günstigsten oder den schnellsten Tarif, der keine Nachnahme ist, und rechnet ihn in die Standardwährung Ihres Shops um. Danach wird der Preis in der Warenkorbwährung des Kunden angezeigt.

Das Paket ist immer eine einzige Box: das Gesamtgewicht in kg sowie Länge und Breite des größten Artikels, mit einer Höhe, die das Gesamtvolumen aller Artikel abdeckt. Produkte ohne Abmessungen zählen als 10 × 10 × 10 cm. Ein Warenkorb ohne Gewicht wird als 0,5 kg gesendet. Der angegebene Wert ist die Zwischensumme des Warenkorbs.

Jeder Tarif wird für dieselbe Strecke und dasselbe Paket 1 Stunde lang zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten lang zwischengespeichert, damit eine nicht erreichbare API nicht jede Aktualisierung der Kasse verlangsamt. Das API-Zeitlimit beträgt 10 Sekunden. Gibt Envioclick einen Fehler oder keinen Versanddienstleister für die Strecke zurück, sieht der Kunde keine Fehlermeldung: Es wird der feste Preis verwendet, oder der Versanddienstleister wird ausgeblendet. 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 Sendungsbelege oder Versandetiketten, beauftragt keine Abholungen und verfolgt oder storniert keine Sendungen. Es bietet einen einzigen Tarif statt einer Auswahl zwischen Versanddienstleistern und verwendet weder Nachnahme-Dienste noch Angebote für mehrere Pakete. Live-Tarife gelten nur innerhalb eines Landes.

Bestellungen

Wenn eine Bestellung mit dem Envioclick-Versanddienstleister aufgegeben wird, wird der für ihren Warenkorb berechnete Tarif zusammen mit der Bestellung gespeichert und ändert sich danach nicht mehr. Die Bestellseite im Admin-Bereich zeigt den Block Envioclick shipping mit Envioclick carrier, Estimated delivery und Envioclick rate ID (bei einem Live-Tarif), Price source (Envioclick live rate, Fixed price per country, Fallback cost oder Free shipping threshold) und Calculated price (excl. tax). Bei einem Live-Tarif zeigt die Bestellseite des Kunden Shipping carrier. Erstellen Sie den Sendungsbeleg in Ihrem Envioclick-Konto.

Bestellungen mit festem Preis haben keinen Envioclick-Versanddienstleister.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich License — VibeFox Envioclick ist der erste Bereich unter Modules > Module Manager > VibeFox Envioclick > Configure, über den Einstellungen. Tragen Sie den Schlüssel unter License key ein und klicken Sie auf Activate. Danach zeigt der Bereich 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-envioclick 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 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 auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Installation. 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 Envioclick-Versanddienstleister Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Das 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 an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen bleiben unberührt.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während der Arbeit im Back-Office automatisch erneut geprüft: 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

Envioclick erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable Envioclick eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe des Kunden abdeckt, oder schalten Sie Ignore shipping zones ein und prüfen Sie Countries. Prüfen Sie die Gewichtsgrenzen und den Minimum order amount. Ohne Live-Tarif benötigt der Versanddienstleister einen festen Preis für das Land, eine Zeile * oder eine Fallback cost. Produkte können auch auf der Produktseite auf bestimmte Versanddienstleister beschränkt sein.

Live-Tarife erscheinen nicht: Lesen Sie die Warnungen oben auf der Modulseite, schalten Sie danach das Debug log ein, laden Sie die Kasse neu und sehen Sie im Feld Log auf der Modulseite nach. Häufige Gründe: kein Umrechnungskurs (die Shopwährung ist nicht MXN oder COP), kein User-Agent (Mexiko), keine Herkunfts-Postleitzahl oder kein DANE-Code, die Postleitzahl (Mexiko) oder Stadt (Kolumbien) des Kunden ist noch nicht eingegeben, das Ziel liegt außerhalb des API-Landes oder es gibt keinen Versanddienstleister für die Strecke.

Warum ein Umrechnungskurs? Envioclick liefert Preise ausschließlich in mexikanischen oder kolumbianischen Pesos. Das Modul zeigt niemals einen Peso-Betrag als eine andere Währung an.

Kolumbien: Die Stadt wird nicht erkannt: Klicken Sie auf der Modulseite auf Add Colombian departments, damit Kunden das Departamento auswählen können, und prüfen Sie, ob der Gemeindename richtig geschrieben ist. Ein als Postleitzahl eingegebener 8-stelliger DANE-Code funktioniert ebenfalls.

Steuern werden auf den Versand doppelt berechnet: Envioclick-Tarife enthalten die Steuern der Versanddienstleister bereits. Stellen Sie Tax auf No tax.

Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten Tarife geleert.

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

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Envioclick und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Tarife und die gespeicherten Tarife von Warenkörben ohne Bestellung werden immer entfernt. Ist Remove data on uninstall eingeschaltet, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen und das Protokoll werden entfernt. Ist die Option ausgeschaltet, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Wenn Sie das Modul erneut installieren, erhält der gespeicherte Versanddienstleister seinen früheren Status zurück. Die Envioclick-Daten aufgegebener Bestellungen bleiben in beiden Fällen erhalten.

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