VibeFox Servientrega for OpenCart — Hilfe
Anforderungen
OpenCart: 3.0.x (getestet mit 3.0.5.0) oder 4.0.2 und neuer (getestet mit 4.1.0.3).
PHP: 8.0 oder neuer.
Servientrega-Konto (nur für Live-Tarife): Live-Tarife nutzen den Servientrega Cotizador Corporativo (Schnittstelle für Firmenangebote). Sie benötigen ein Servientrega-Firmenkonto (Kreditkonto) mit Zugang dazu. Sie brauchen drei Angaben: den Benutzer, das Passwort und den Abrechnungscode (código de facturación, meist beginnend mit SER). Dies sind Ihre SISCLINET-Zugangsdaten, die Ihr Servientrega-Vertriebsberater ausstellt. Wenn Sie nur feste Preise verwenden, brauchen Sie kein Servientrega-Konto.
Serverzugriff (nur für Live-Tarife): Ihr Server muss web.servientrega.com per HTTP auf Port 8058 (Angebots-Schnittstelle) und Port 8081 (Webdienst zur Passwortverschlüsselung) erreichen können.
VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer Domain.
Installation
Der Download ist eine ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das OpenCart-3-Paket vfd_servientrega-oc3-(version).ocmod.zip und das OpenCart-4-Paket vfd_servientrega.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen derselbe.
OpenCart 3
1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_servientrega-oc3-(version).ocmod.zip. Die Erweiterung fügt keine OCMOD-Modifikationen hinzu, daher müssen Sie Extensions > Modifications nicht aktualisieren. Statt des Installers können Sie auch den Inhalt des Ordners upload aus dem Paket in das Stammverzeichnis Ihres Shops kopieren.
2. Gehen Sie zu Extensions > Extensions, wählen Sie den Erweiterungstyp Shipping, suchen Sie VibeFox Servientrega und klicken Sie auf Install (die grüne +-Schaltfläche).
3. Klicken Sie auf Edit (die Stift-Schaltfläche), um die Einstellungsseite zu öffnen.
4. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Edit ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
5. 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 die Währung Ihres Shops nicht COP ist, den Währungsumrechnungskurs.
6. Optional legen Sie feste Preise je Land und Gewicht sowie einen Ersatzpreis fest, schalten Enable Servientrega ein und klicken auf Save.
OpenCart 4
1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_servientrega.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 übernimmt den Erweiterungscode aus dem Dateinamen, und ein umbenanntes Paket funktioniert nicht.
2. Das Paket erscheint auf derselben Seite in der Liste der installierten Erweiterungen. Klicken Sie daneben auf Install (die grüne +-Schaltfläche).
3. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Servientrega, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-Schaltfläche).
4. Geben Sie den Lizenzschlüssel und die Einstellungen wie in den Schritten 4 bis 6 für OpenCart 3 ein. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich.
Nach der Installation ist die Versandart ausgeschaltet, bis Sie Enable Servientrega einschalten und speichern. Installieren Sie die Erweiterung nach einer Deinstallation erneut, werden die aufbewahrten Servientrega-Einstellungen wieder verwendet.
Konfiguration
Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Shipping > VibeFox Servientrega > Edit. Die Abschnitte stehen links. Sie gelten für alle Geozonen. Ein Button Save am unteren Rand speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht die zwischengespeicherten Servientrega-Angebote und das Anmeldetoken. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.
Können Live-Tarife mit den gespeicherten Einstellungen nicht funktionieren, zeigt eine Warnung über den Einstellungen den Grund an: ein fehlender Benutzer, Passwort oder Abrechnungscode, ein fehlender Umrechnungskurs oder ein fehlender DANE-Code des Versandorts. Eine Warnung erscheint auch, wenn der Shop keine Gewichtsklasse in kg oder Längenklasse in cm hat und seine Standardeinheit der Erweiterung nicht bekannt 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, ein leerer Versandartname, ein Name mit mehr als 64 Zeichen oder mit < > ; = # { }, oder eine Sortierreihenfolge, die keine ganze Zahl ist, mit einem Fehler abgelehnt, und nichts wird gespeichert.
Allgemein
Enable Servientrega: blendet Servientrega in der Kasse ein oder aus. Standard: aus.
Method title: der Name der Versandart, den der Kunde im Warenkorb und in der Kasse sieht. Standard: Servientrega. Pflichtfeld, höchstens 64 Zeichen.
Sort order: die Position von Servientrega unter den Versandarten in der Kasse. Eine ganze Zahl.
Servientrega-API (Live-Tarife für Kolumbien) (optional; ohne Zugangsdaten werden nur die festen Preise verwendet)
User (login): Ihr Servientrega-/SISCLINET-Benutzer. Wenn Sie ihn leeren, wird auch das gespeicherte Passwort entfernt.
Password: Ihr Servientrega-/SISCLINET-Passwort, so wie Sie es eingeben. Die Erweiterung lässt es vor der Anmeldung 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 código de facturación (Abrechnungscode) Ihres Servientrega-Kontos, wie er 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 Servientrega-Vereinbarung, für den ein Angebot eingeholt wird.
Das abrechenbare Gewicht ist das größere aus tatsächlichem und volumetrischem Gewicht.
Currency conversion rate: Servientrega rechnet in COP ab. 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 deklarierte Paketwert wird ebenso in COP umgerechnet. Ist die Währung Ihres Shops COP, zeigt das Feld an, dass keine Umrechnung nötig ist: Lassen Sie es leer. Verwendet Ihr Shop eine andere Währung und dieses Feld ist leer, werden keine Live-Tarife verwendet und die festen Preise gelten. Die Erweiterung ruft keine Wechselkurse ab. Punkt und Komma werden beide als Dezimaltrennzeichen akzeptiert.
Ship from (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. Ein 5-stelliger Gemeindecode wird ebenfalls akzeptiert. Die Shop-Adresse in OpenCart ist Freitext, daher wird der Versandort niemals daraus übernommen: Ohne dieses Feld gibt es keine Live-Tarife.
Fixed prices (verwendet, wenn kein Live-Tarif vorliegt: keine Zugangsdaten, ein Ziel außerhalb Kolumbiens, eine unbekannte Gemeinde, ein fehlender Umrechnungskurs oder ein API-Fehler bzw. keine Abdeckung für die Strecke)
Price per country: eine Tabelle mit Ländern und Preisen in der Standardwährung Ihres Shops, ohne Steuer. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die Entfernen-Schaltfläche, um eine zu löschen. Price gilt für jedes Gewicht. Die Gewichtsspalten XS (bis 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) und XL (über 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 neue Zeile beginnt als * Default. Eine Zeile ohne jeden 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 die Versandart in diesem Fall auszublenden.
Fixed price applies: wie feste Preise berechnet werden.
Live-Tarife von Servientrega werden immer je Sendung berechnet.
Conditions
Minimum weight (kg): blendet die Versandart unterhalb dieses Warenkorbgewichts aus. 0 bedeutet keine Grenze (Standard).
Maximum weight (kg): blendet die Versandart oberhalb dieses Warenkorbgewichts aus. Standard: 50. 0 bedeutet keine Grenze.
Minimum order amount: zeigt die Versandart nur, wenn die Zwischensumme der Produkte, die einen Versand benötigen (nach dem Gutschein, vor Steuer), diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.
Free shipping from: der Versand ist kostenlos, wenn diese Zwischensumme diesen Betrag erreicht, und es geht keine Anfrage an Servientrega. Dies gilt für jedes Ziel, für das die Versandart angeboten wird, auch für Länder ohne Zeile in der Preistabelle. Lassen Sie das Feld leer, um nie kostenlosen Versand anzubieten.
Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Die Angebote von Servientrega (ValorTotal) enthalten bereits die Gebühren des Frachtführers. Wählen Sie No tax, wenn Sie keine Steuer obendrauf aufschlagen möchten.
Geo zone: bietet Servientrega nur für Adressen in dieser Geozone an. All zones (Standard) bedeutet keine Grenze. Geozonen werden unter System > Localisation > Geo Zones verwaltet. Sie wird nicht geprüft, wenn Ignore shipping zones eingeschaltet ist.
Availability without geo zone
Normalerweise wird die Versandart in der unter Conditions gewählten Geozone angeboten oder überall.
Ignore shipping zones: bietet Servientrega für die unten genannten Länder an, unabhängig von der Geozone.
Countries: die Zielländer für diesen Modus. Leer lassen, um alle aktivierten Länder Ihres Shops zu verwenden. Dieses Feld wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.
Advanced
Debug log: schreibt Tarifberechnungen und API-Fehler in storage/logs/vfd_svtg_debug.log.php. Die Datei kann nicht über das Web gelesen werden. Zugangsdaten, Token und Kundenadressen werden nicht protokolliert. Ist das Protokoll ausgeschaltet, wird nichts geschrieben, auch keine API-Fehler. Erreicht die Datei 5 MB, wird sie nach vfd_svtg_debug.old.log.php verschoben und ein neues Protokoll begonnen. 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 es eingeschaltet, löscht die Deinstallation der Erweiterung alle Servientrega-Einstellungen und das Protokoll. Ist es ausgeschaltet (Standard), bleiben sie für eine Neuinstallation erhalten. Zwischengespeicherte Angebote werden immer gelöscht.
Import / Export
Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Das Passwort wird nicht exportiert.
Import: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen, zum Beispiel in einem anderen Shop. Die Werte werden wie beim normalen Speichern geprüft. Das gespeicherte Passwort bleibt erhalten, solange ein Benutzer festgelegt ist.
So funktioniert es in der Kasse
Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Servientrega-Preis. Ist eine Geo zone gesetzt und liegt die Adresse außerhalb, wird Servientrega nicht angeboten (außer Ignore shipping zones ist eingeschaltet). Nur Produkte mit Requires Shipping auf Yes zählen: Andere Produkte fügen kein Gewicht hinzu und sind nicht in der Bestellsumme enthalten. Die Bestellsumme ist der Preis dieser Produkte nach dem Gutscheinrabatt und vor Steuer. Geschenkgutscheine und Bonuspunkte werden nicht berücksichtigt. Die Erweiterung prüft zuerst die Bedingungen: das Lieferland (mit Ignore shipping zones), das Warenkorbgewicht und den Mindestbestellwert. Gilt kostenloser Versand, ist der Preis 0 und es geht keine Anfrage an Servientrega. Danach sucht sie einen Preis: den Live-Tarif von Servientrega, dann die Preistabelle und zuletzt den Ersatzpreis. Gibt es keinen Preis, wird die Versandart für diesen Warenkorb ausgeblendet.
Für ein Ziel in Kolumbien mit hinterlegten Zugangsdaten ermittelt die Erweiterung den DANE-Code der Gemeinde des Kunden. Sie verwendet einen DANE-Code, der im Postleitzahl- oder Stadtfeld eingegeben wurde, oder gleicht Departamento und Stadt mit der integrierten Tabelle von rund 1.130 Gemeinden ab. Das Departamento ist die Region / State der Adresse: OpenCart hat bereits alle 33 kolumbianischen Departamentos. Akzente und „D.C.“ werden ignoriert. Eine Stadt, die nur in einem Departamento existiert, wird auch ohne Departamento gefunden.
Anschließend sendet die Erweiterung an Servientrega ein Stück pro Bestellung: das Gesamtgewicht, umgerechnet von der Gewichtsklasse des Produkts in kg, und eine Box mit 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 deklarierte Wert ist der Bestellwert, umgerechnet in COP, mindestens 6.000 COP. Servientrega gibt die Summe in COP zurück. Die Erweiterung rechnet sie in die Standardwährung Ihres Shops um und rundet sie auf deren Dezimalstellen. Der Kunde sieht sie in seiner Währung mit der Steuer der gewählten Tax class.
Das Anmeldetoken bleibt bis zu seinem Ablauf gültig, höchstens 4 Tage. Ein abgelehntes Token wird einmal automatisch erneuert. Jedes Angebot wird 1 Stunde pro Strecke und Paket zwischengespeichert, sodass derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage (Verschlüsselung, Anmeldung oder Angebot) wird 10 Minuten zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf Servientrega warten muss. Das Zeitlimit beträgt 10 Sekunden pro Anfrage.
Der Kunde sieht nie einen API-Fehler. Der Grund wird bei aktiviertem Debug-Protokoll in das Protokoll geschrieben.
Die Erweiterung berechnet nur Tarife. Sie erstellt keine Versandbelege (guías), Etiketten oder Sticker, beauftragt keine Abholungen, verfolgt oder storniert keine Sendungen und lässt Kunden kein Servientrega-Büro (Centro de Soluciones) wählen. Erstellen Sie den Versandbeleg in SISCLINET oder in Ihrem Servientrega-Portal. Nachnahme (logística de recaudo) wird nicht angeboten. Live-Angebote gelten nur für Inlandssendungen innerhalb Kolumbiens. Sie fügt Bestellungen nichts hinzu: Die Bestellung zeigt den Namen der Versandart und die Versandkosten wie bei jeder anderen OpenCart-Versandart.
In OpenCart 4 klickt der Kunde auf der Kasseseite im Block der Versandarten auf Choose und wählt Servientrega im Fenster Shipping method options, in dem der Titel der Versandart mit dem Preis angezeigt wird. Die Versandart funktioniert genauso wie in OpenCart 3.
Lizenzschlüssel
Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Servientrega ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Servientrega > Edit, ü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: opencart-shipping-servientrega und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Admin-Sprache (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. 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 die Erweiterung mit dem zuletzt bekannten Status weiter.
Ein Schlüssel funktioniert auf einer Domain: der Shop-Adresse aus der OpenCart-Konfiguration. 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 die Servientrega-Versandart Kunden in der Kasse nicht angezeigt, und es werden keine Tarife angefragt oder berechnet. Ein Admin-Benutzer, der im Admin im selben Browser angemeldet ist, sieht die Versandart im Shop weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. In OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Versandart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint ein Hinweis auf dem Dashboard des Admins. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.
Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird beim Öffnen des Admin-Dashboard oder der Seite Edit automatisch erneut geprüft: 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 der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Servientrega erscheint nicht in der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable Servientrega eingeschaltet ist. Prüfen Sie Geo zone 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 * Default einen Preis hat oder ob Fallback cost gesetzt ist. Prüfen Sie, dass die Produkte Requires Shipping auf Yes haben.
Live-Tarife erscheinen nicht: schalten Sie das Debug log ein, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Seite der Erweiterung an. Häufige Gründe: ein fehlender Umrechnungskurs (die Shopwährung ist nicht COP), kein Versand-DANE-Code, das Departamento oder die Stadt des Kunden ist noch nicht eingegeben oder keine bekannte Gemeinde, falsche Zugangsdaten, keine Abdeckung für die Strecke oder der Server kann web.servientrega.com nicht auf den Ports 8058 und 8081 erreichen. Feste Preise decken diese Fälle ab, wenn Sie sie einrichten.
Anmeldung schlägt fehl: prüfen Sie Benutzer, Passwort und Abrechnungscode bei Ihrem Servientrega-Vertriebsberater. Nach einer fehlgeschlagenen Anmeldung wartet die Erweiterung 10 Minuten vor dem nächsten Versuch. Speichern Sie die Einstellungen, um sofort erneut zu versuchen.
Die Stadt des Kunden wird nicht erkannt: der Kunde sollte das Departamento im Feld Region / State wählen. Bei seltenen Schreibweisen kann der Kunde den 8-stelligen DANE-Code als Postleitzahl eingeben.
Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Seite der Erweiterung auf Save. Dies löscht die zwischengespeicherten Servientrega-Angebote und das Token.
Die Seite zeigt „Warning: You do not have permission to modify VibeFox Servientrega!“: Ihre Admin-Benutzergruppe darf die Einstellungen möglicherweise nur ansehen. Geben Sie der Gruppe die Berechtigung zum Ändern für extension/shipping/vfd_servientrega (OpenCart 3) oder extension/vfd_servientrega/shipping/vfd_servientrega (OpenCart 4) unter System > Users > User Groups.
Für Entwickler: die OpenCart-Ereignisse vfd_servientrega/dane_code und vfd_servientrega/quote_request erlauben es einer anderen Erweiterung, den DANE-Zielcode und die Angebotsanfrage zu ändern.
Deinstallation
Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Servientrega auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt Enable Servientrega, Sort order, Tax class und Geo zone immer zurück. Die zwischengespeicherten Angebote, Token und das verschlüsselte Passwort werden immer entfernt. Ist Remove data on uninstall eingeschaltet, werden auch die übrigen Einstellungen und das Protokoll gelöscht. Ist es ausgeschaltet, bleiben sie erhalten und werden bei einer erneuten Installation wieder verwendet. Bestehende Bestellungen behalten ihre Versandart und ihre Kosten.
Um in OpenCart 4 auch die Dateien der Erweiterung zu entfernen, gehen Sie nach der Deinstallation zu Extensions > Installer und klicken Sie in der Liste der installierten Erweiterungen neben VibeFox Servientrega auf Uninstall (die orangefarbene −-Schaltfläche) und danach auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.
Servientrega ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit Servientrega verbunden und wird nicht von Servientrega unterstützt.
