VibeFox Servientrega 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.
Servientrega-Konto (nur für Live-Tarife): Live-Tarife nutzen den Servientrega Cotizador Corporativo (API für Firmenangebote). Sie benötigen ein Servientrega-Firmenkonto (Kreditkonto) mit Zugriff darauf. Sie brauchen drei Angaben: den Benutzer, das Passwort und den Abrechnungscode (código de facturación, beginnt meist mit SER). Es sind Ihre SISCLINET-Zugangsdaten, die Ihr Vertriebsberater bei Servientrega ausstellt. Wenn Sie nur feste Preise verwenden, benötigen Sie kein Servientrega-Konto.
Serverzugriff (nur für Live-Tarife): Ihr Server muss web.servientrega.com per HTTP auf Port 8058 (Angebots-API) und Port 8081 (Webdienst zur Passwortverschlüsselung) erreichen können.
VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. 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 Servientrega 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 Benutzer, Passwort und Abrechnungscode ein, wählen das Servientrega-Produkt, geben den DANE-Code des Versandorts ein und, falls Ihre Shopwährung nicht COP ist, den Währungsumrechnungskurs. Klicken Sie auf Add Colombian departments, wenn Ihr Shop noch keine hat (siehe Konfiguration).
5. Optional fügen Sie feste Preise je Land und Gewicht sowie Ausweichkosten hinzu und klicken dann auf Save.
Bei der Installation erstellt das Modul den Versanddienstleister Servientrega mit dem Liefertext Servientrega courier delivery. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugewiesen. Zonen, Kundengruppen, Lieferzeit, Logo und Größenbeschränkungen können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis stammt immer vom Modul.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Servientrega > Configure. Sie gelten für alle Zonen. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die ganze Seite speichert. Jedes Speichern leert die zwischengespeicherten Servientrega-Angebote und das Login-Token.
Wenn Live-Tarife mit den gespeicherten Einstellungen nicht funktionieren können, zeigt eine Warnung über dem Formular den Grund: einen fehlenden Benutzer, ein fehlendes Passwort oder einen fehlenden Abrechnungscode, einen fehlenden Umrechnungskurs oder einen fehlenden DANE-Code des Versandorts. Eine Warnung erscheint auch, wenn die Gewichts- oder Maßeinheit Ihres Shops (International > Localization, Local units) dem Modul unbekannt ist; Gewichte werden dann als kg und Abmessungen als cm gelesen. Beim Speichern wird ein Wert, der keine Zahl ist, eine negative Zahl, ein Umrechnungskurs von 0, ein Mindestgewicht über dem Höchstgewicht, ein falscher Preis in der Tabelle oder ein Methodentitel mit mehr als 64 Zeichen mit einer Fehlermeldung abgelehnt, und nichts wird gespeichert.
Allgemein
Enable Servientrega: schaltet den Versanddienstleister in allen Zonen gleichzeitig ein oder aus. Es ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.
Method title: der Name des Versanddienstleisters, der dem Kunden im Warenkorb und an der Kasse angezeigt wird. Standard: Servientrega. Pflichtfeld, höchstens 64 Zeichen.
Servientrega-API (Live-Tarife für Kolumbien) (optional; ohne Zugangsdaten werden nur die festen Preise verwendet)
User (login): Ihr Servientrega- / SISCLINET-Benutzer. Wird er geleert, wird auch das gespeicherte Passwort entfernt.
Password: Ihr Servientrega- / SISCLINET-Passwort, so wie Sie es eingeben. Das Modul lässt es vor dem Login vom Servientrega-Webdienst verschlüsseln. 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.
Billing code: der Abrechnungscode (código de facturación) Ihres Servientrega-Kontos, der in SISCLINET angezeigt wird. Er beginnt meist mit SER.
Alle drei Felder werden für Live-Tarife benötigt. Live-Tarife werden nur für Ziele in Kolumbien abgefragt. Andere Länder verwenden die festen Preise.
Servientrega product: der Dienst aus Ihrer Vereinbarung mit Servientrega, für den ein Tarif angefragt wird.
Das abgerechnete Gewicht ist das größere aus tatsächlichem und volumetrischem Gewicht.
Currency conversion rate: Servientrega berechnet Tarife in COP. Wenn die Standardwährung Ihres Shops nicht COP ist, geben Sie den Wert von 1 COP in Ihrer Shopwährung ein, zum Beispiel 0.00023. Der angegebene Paketwert wird auf dieselbe Weise in COP umgerechnet. Lassen Sie das Feld leer, wenn Ihre Shopwährung COP ist. Wenn Ihr Shop eine andere Währung verwendet und dieses Feld leer ist, werden keine Live-Tarife verwendet und die festen Preise gelten. Das Modul ruft keine Wechselkurse ab. Punkt und Komma werden beide als Dezimaltrennzeichen akzeptiert.
Colombian departments: das Departamento hilft, Gemeinden mit gleichem Namen zu unterscheiden. PrestaShop hat standardmäßig keine kolumbianischen Departamentos; ohne sie werden nur Stadtnamen erkannt, die in Kolumbien eindeutig sind. Klicken Sie auf Add Colombian departments, um die 33 Departamentos als Bundesländer von Kolumbien hinzuzufügen (ISO-Codes ANT, DC …), aktivieren Sie Contains states für Kolumbien und fügen Sie das Feld Departamento dem Adressformular für Kolumbien hinzu. Bereits vorhandene Departamentos werden nicht doppelt angelegt. Wenn alles eingerichtet ist, zeigt das Feld an, wie viele Departamentos die Adressen in Kolumbien haben.
Versand ab (für Live-Tarife verwendet)
Origin city (DANE code): der 8-stellige DANE-Code der Gemeinde, von der Sie versenden, zum Beispiel 11001000 Bogotá, 05001000 Medellín, 76001000 Cali oder 08001000 Barranquilla. Auch ein 5-stelliger Gemeindecode wird akzeptiert. Ist er leer und liegt die Shopadresse unter Shop Parameters > Contact > Stores in Kolumbien, wird die Gemeinde der Shopadresse verwendet.
Feste Preise (werden verwendet, wenn kein Live-Tarif vorliegt: keine Zugangsdaten, ein Ziel außerhalb Kolumbiens, eine unbekannte Gemeinde, ein fehlender Umrechnungskurs, ein API-Fehler oder keine Abdeckung für die Strecke)
Price per country: eine Tabelle mit Ländern und Preisen in der Standardwährung Ihres Shops, ohne Steuern. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorbsymbol, um eine zu entfernen. Price gilt für jedes Gewicht. Die Gewichtsspalten XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg und XL >5 kg ersetzen ihn für dieses Gewicht, wenn sie über 0 liegen. Die Zeile * Default gilt für alle Länder ohne eigene Zeile. Eine Zeile ohne Preis wird nicht gespeichert.
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: wie die festen Preise berechnet werden.
Live-Tarife von Servientrega gelten immer je Sendung.
Bedingungen
Minimum weight: blendet den Versanddienstleister aus, wenn der Warenkorb weniger wiegt, in kg. 0 bedeutet keine Grenze.
Maximum weight: blendet den Versanddienstleister aus, wenn der Warenkorb mehr wiegt, in kg. Standard: 50. 0 bedeutet keine Grenze.
Minimum order amount: zeigt den Versanddienstleister nur, wenn die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern) diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.
Free shipping from: der Versand ist kostenlos, wenn die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern) diesen Betrag erreicht; dann wird keine Anfrage an Servientrega gesendet. Das gilt für alle Ziele, in denen der Versanddienstleister angeboten wird, auch für Länder ohne Zeile in der Preistabelle. Leer lassen, um nie kostenlosen Versand anzubieten.
Tax: die Steuerregel des Versanddienstleisters oder No tax. Servientrega-Angebote (ValorTotal) enthalten die Gebühren des Versanddienstleisters bereits. Wählen Sie No tax, wenn Sie keine Steuer obendrauf aufschlagen möchten.
Verfügbarkeit ohne Versandzonen
Normalerweise wird der Versanddienstleister in den Zonen angeboten, die ihm unter Shipping > Carriers zugewiesen sind.
Ignore shipping zones: bietet Servientrega für die unten genannten Länder an, auch wenn der Versanddienstleister ihrer Zone nicht zugewiesen ist. Der Versanddienstleister wird dann allen Zonen zugewiesen, auch später angelegten Zonen. Wenn Sie die Option ausschalten, erhält der Versanddienstleister seine früheren Zonen zurück.
Countries: die Zielländer für diesen Modus. Leer lassen, um alle aktiven Länder Ihres Shops zu verwenden. Dieses Feld wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.
Erweitert
Debug log: schreibt Tarifberechnungen und API-Fehler in logs/vfd_svtg_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Zugangsdaten, Token und Kundenadressen werden nicht protokolliert. Ist das Protokoll ausgeschaltet, wird nichts geschrieben, auch keine API-Fehler. Schalten Sie das Protokoll aus, wenn Sie fertig sind.
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 eingeschaltet, löscht die Deinstallation des Moduls alle Servientrega-Einstellungen, den Versanddienstleister, die zwischengespeicherten Angebote und die Protokolle. Frühere Bestellungen behalten ihren Versanddienstleister. Ist sie ausgeschaltet, bleibt alles für eine erneute Installation erhalten.
Ablauf an der Kasse
Im Versandschritt fragt PrestaShop das Modul nach dem Servientrega-Preis. Nur physische Produkte zählen: Virtuelle Produkte fügen kein Gewicht hinzu und sind nicht im Bestellwert enthalten. Das Modul prüft zuerst die Bedingungen: das Lieferland (mit Ignore shipping zones), das Warenkorbgewicht und den Mindestbestellwert. Gilt kostenloser Versand, beträgt der Preis 0 und es wird keine Anfrage an Servientrega gesendet. Dann sucht es nach einem Preis: zuerst dem Live-Tarif von Servientrega, dann der Preistabelle und schließlich den Ausweichkosten. Gibt es keinen Preis, wird der Versanddienstleister für diesen Warenkorb ausgeblendet.
Bei einem Ziel in Kolumbien mit hinterlegten Zugangsdaten ermittelt das Modul den DANE-Code der Gemeinde des Kunden. Es verwendet einen DANE-Code, der als Postleitzahl oder im Ortsfeld eingetragen wurde, oder gleicht Departamento und Stadt mit der integrierten Tabelle von rund 1.130 Gemeinden ab. Akzente und „D.C.“ werden ignoriert. Ein Stadtname, der nur in einem Departamento vorkommt, wird auch ohne Departamento gefunden.
Danach sendet das Modul an Servientrega ein Stück pro Bestellung: das Gesamtgewicht, umgerechnet von der Gewichtseinheit Ihres Shops in kg, und eine Schachtel mit der Länge und Breite des größten Artikels sowie dem Gesamtvolumen aller Artikel, umgerechnet in cm. Produkte ohne Abmessungen zählen als 10 × 10 × 10 cm. Der angegebene Wert ist die Zwischensumme des Warenkorbs, umgerechnet in COP, mindestens 6.000 COP. Servientrega gibt die Summe in COP zurück. Das Modul rechnet sie in die Standardwährung Ihres Shops um, und der Kunde sieht sie in der Warenkorbwährung.
Das Login-Token wird bis zu seinem Ablauf gespeichert, höchstens 4 Tage. Ein abgelehntes Token wird einmal automatisch erneuert. Jedes Angebot wird 1 Stunde je Strecke und Paket zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage (Verschlüsselung, Login oder Angebot) wird 10 Minuten zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf Servientrega wartet. Das Timeout beträgt 10 Sekunden je Anfrage.
Der Kunde sieht nie einen API-Fehler. Der Grund wird bei eingeschaltetem Debug-Protokoll in das Protokoll geschrieben.
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 Versandscheine (guías), Etiketten oder Aufkleber, beantragt keine Abholungen, verfolgt oder storniert keine Sendungen und lässt Kunden kein Servientrega-Büro (Centro de Soluciones) wählen. Erstellen Sie den Versandschein in SISCLINET oder in Ihrem Servientrega-Portal. Nachnahme (logística de recaudo) wird nicht angeboten. Live-Angebote gelten nur für Inlandssendungen innerhalb Kolumbiens. Andere Länder verwenden die festen Preise.
Lizenzschlüssel
Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Servientrega ist der erste Block unter Modules > Module Manager > VibeFox Servientrega > 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 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-servientrega 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 in Ihrem Konto einen Domainplatz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul weiter mit dem zuletzt bekannten Status.
Ein Schlüssel funktioniert für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Installation. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.
Ohne aktiven Schlüssel wird der Versanddienstleister Servientrega Kunden an der Kasse nicht angezeigt, und es wird kein Tarif abgefragt oder berechnet. Der 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 einrichten, bevor Sie einen Schlüssel kaufen, 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 benötigen 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 Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Die Deinstallation oder das Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Servientrega erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable Servientrega 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 prüfen Sie, ob das Land oder die Zeile * Default einen Preis hat oder ob Fallback cost gesetzt ist. Produkte können auf der Produktseite zudem auf bestimmte Versanddienstleister beschränkt sein.
Live-Tarife erscheinen nicht: Schalten Sie das Debug log ein, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Modulseite an. Häufige Gründe: ein fehlender Umrechnungskurs (Shopwährung ist nicht COP), kein DANE-Code des Versandorts, das Departamento oder die Stadt des Kunden ist noch nicht eingetragen oder keine bekannte Gemeinde, falsche Zugangsdaten oder keine Abdeckung für die Strecke. Feste Preise decken diese Fälle ab, wenn Sie sie festlegen.
Login schlägt fehl: Prüfen Sie Benutzer, Passwort und Abrechnungscode bei Ihrem Vertriebsberater bei Servientrega. Nach einem fehlgeschlagenen Login wartet das Modul 10 Minuten, bevor der nächste Versuch erfolgt. Speichern Sie die Einstellungen, um sofort erneut zu versuchen.
Die Stadt des Kunden wird nicht erkannt: Klicken Sie auf Add Colombian departments, damit Kunden ihr Departamento auswählen können. Bei seltenen Schreibweisen kann der Kunde den 8-stelligen DANE-Code als Postleitzahl eingeben.
Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten Servientrega-Angebote und das Token geleert.
Die Seite meldet, dass der Versanddienstleister Servientrega nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, damit er neu angelegt wird.
Für Entwickler: Die Hooks actionVfdSvtgDaneCode und actionVfdSvtgQuoteRequest erlauben es, den DANE-Code des Ziels und die Angebotsanfrage zu ändern.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Servientrega und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Angebote, Token und das verschlüsselte Passwort 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 sie ausgeschaltet, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Bei einer erneuten Installation des Moduls oder mit Reset erhält der Versanddienstleister wieder den Status, den er vorher hatte.
Servientrega ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Servientrega verbunden noch von Servientrega unterstützt.