VibeFox Instabee 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.

Budbee-API-Zugangsdaten (nur für die Auswahl der Paketbox): ein API-Schlüssel und ein API-Geheimnis. Instabee stellt sie Händlern mit einer Liefervereinbarung aus. Fragen Sie Ihren Ansprechpartner bei Instabee oder nutzen Sie das Händlerportal von Instabee. Die API-Dokumentation finden Sie auf developer.budbee.com. Ohne Zugangsdaten funktioniert die Methode mit festen Preisen weiter, aber Kunden können keine Paketbox wählen.

VibeFox-Lizenzschlüssel: gekauft auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.

Installation

Der Download ist eine einzige ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das Paket für OpenCart 3 vfd_instabee-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_instabee.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen gleich.

OpenCart 3

1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_instabee-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 den Inhalt des Ordners upload dieses Pakets in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Instabee 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 ein, im Lizenzblock oben auf der Seite Edit, und klicken Sie auf Activate (siehe Lizenzschlüssel).

5. Füllen Sie den Abschnitt Prices aus und tragen Sie für den Paketbox-Selektor Ihren Budbee-API key und Ihr API secret ein (siehe Konfiguration). Aktivieren Sie Enable/Disable und klicken Sie auf Save.

OpenCart 4

1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_instabee.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Erweiterungscode 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 Instabee, 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 und 5 für OpenCart 3 ein. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich.

Nach der Installation ist die Methode deaktiviert, bis Sie Enable/Disable einschalten und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die gespeicherten Instabee-Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Instabee > Edit. Die Abschnitte sind links aufgelistet. Eine Schaltfläche Save speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht außerdem die zwischengespeicherten Boxlisten und den letzten API-Fehler. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Warnungen oberhalb der Einstellungen zeigen an, wenn nur eine der beiden API-Zugangsdaten eingetragen ist, wenn keine API-Zugangsdaten vorhanden sind, wenn keine Länderpreise und kein Ersatzpreis vorhanden sind, wenn die letzte Budbee-API-Anfrage fehlgeschlagen ist (mit Datum, Uhrzeit und Grund) und wenn der Shop keine Gewichtsklasse mit der Einheit kg hat und die Einheit der Standard-Gewichtsklasse nicht erkannt wird (Gewichte werden dann als kg behandelt; legen Sie eine kg-Gewichtsklasse unter System > Localisation > Weight Classes an).

Ist Method name leer oder zu lang, ist Min weight (kg) größer als Max weight (kg), ist Sort order keine ganze Zahl oder existiert die Steuerklasse oder Geozone nicht, wird nichts gespeichert und ein Fehler angezeigt.

Allgemein

Enable/Disable: blendet Instabee an der Kasse ein oder aus. Standard: off.

Method name: der Name der Versandart, der dem Kunden an der Kasse angezeigt wird. Standard: Instabee parcel box. Pflichtfeld, höchstens 64 Zeichen.

Tax class: None (the prices are final) (Standard) bedeutet, dass die folgenden Preise endgültig sind. Eine Steuerklasse fügt die Versandsteuer dieser Klasse zu den folgenden Preisen hinzu.

Sort order: die Position von Instabee unter den Versandarten an der Kasse. Eine ganze Zahl.

Paketbox-Selektor (Budbee-API)

Mit API-Zugangsdaten wählt der Kunde an der Kasse eine Paketbox in der Nähe seiner Postleitzahl, und die Box wird in der Bestellung gespeichert. Beide Felder sind erforderlich. Der Selektor bleibt aus, bis beide ausgefüllt sind.

API key: Ihr Budbee-API-Schlüssel (der HTTP-Basic-Benutzername).

API secret: Ihr Budbee-API-Geheimnis (das HTTP-Basic-Passwort). Es wird nie ins Protokoll geschrieben.

Nach dem Speichern bleiben beide Felder leer und zeigen Saved - leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Um die gespeicherten Zugangsdaten zu löschen, setzen Sie den Haken bei Remove the saved API key and secret und speichern Sie. Ist nichts gespeichert, zeigt die Seite No credentials saved.

Test environment: nutzt die Staging-API von Budbee (api.staging.budbee.com). Aktivieren Sie sie nur mit Staging-Zugangsdaten von Instabee. Live-Shops lassen sie aus (api.budbee.com). Standard: off.

Preise (der Abschnittstitel zeigt die Standardwährung Ihres Shops)

Alle Preise gelten in der Standardwährung des Shops, ohne Steuer. Ein Dezimalkomma und ein Dezimalpunkt werden beide akzeptiert (49,90 = 49.90). Der Preis wird dem Kunden in seiner Währung angezeigt.

Calculation type: wie der Preis angewendet wird.

Country prices: eine Tabelle mit den Spalten Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg und XL >5 kg. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die ×-Schaltfläche, um eine zu entfernen. Wählen Sie * Any other country für eine Zeile, die für alle Länder ohne eigene Zeile gilt. Eine leere oder 0-Stufe verwendet die Spalte Price. Ein Price von 0 bedeutet kostenlose Lieferung. Hat die Zeile des Landes für das Warenkorbgewicht keinen Preis, wird die Zeile * verwendet, danach der Fallback cost. Beim Speichern wird ein Preis, der keine Zahl von 0 oder mehr ist, gelöscht, und eine Zeile mit unbekanntem Land wird entfernt; eine Warnung listet sie auf. Produktgewichte werden von ihrer OpenCart-Gewichtsklasse in kg umgerechnet.

Fallback cost: wird verwendet, wenn weder die Zeile des Ziellandes noch die Zeile * einen Preis liefert. Lassen Sie das Feld leer, um die Methode für solche Länder auszublenden.

Bedingungen

Min weight (kg): blendet die Methode unterhalb dieses Warenkorbgewichts aus. Standard: 0 (keine Grenze).

Max weight (kg): blendet die Methode oberhalb dieses Warenkorbgewichts aus. Paketboxen nehmen bis etwa 20 kg auf. Standard: 20. 0 bedeutet keine Grenze. Er darf nicht kleiner sein als Min weight (kg).

Minimum order amount: zeigt die Methode nur, wenn die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuer) diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.

Free shipping from: die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuer), ab der die Methode kostenlos ist. Leer lassen, damit sie nie kostenlos ist.

Ist ein Wert in diesen Feldern oder in Fallback cost keine Zahl von 0 oder mehr, wird er nicht gespeichert, der vorherige Wert bleibt erhalten, und eine Warnung nennt das Feld.

Verfügbarkeit

Geo zone: Instabee nur für Adressen in dieser Geozone anbieten. All zones (Standard) bedeutet überall. Die Geozone wird nicht geprüft, wenn Ignore shipping zones aktiviert ist. Geozonen werden unter System > Localisation > Geo Zones verwaltet.

Ignore shipping zones: ist die Option aktiv, wird die Geo zone nicht geprüft und die Methode wird für die unten genannten Länder angeboten. Ist sie aus (Standard), gilt nur die Geo zone.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zuzulassen. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiv ist.

Erweitert

Debug log: schreibt Debug-Meldungen in storage/logs/vfd_ibee_debug.log.php (bei OpenCart 4 system/storage/logs/vfd_ibee_debug.log.php). Die Datei kann nicht aus dem Web gelesen werden. API-Fehler und Bestellungen ohne Box, die aufgegeben wurden, während die API funktionierte, werden immer protokolliert, auch wenn die Option aus ist. API-Schlüssel und Kundendaten werden nie protokolliert. Erreicht die Datei 5 MB, wird sie nach vfd_ibee_debug.old.log.php verschoben und ein neues Protokoll begonnen.

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

Remove data on uninstall: ist die Option aktiv, löscht die Deinstallation der Erweiterung die Einstellungen, die zwischengespeicherten Boxlisten, das Protokoll und die Boxen nicht abgeschlossener Kassenvorgänge. Ist sie aus (Standard), bleiben die Einstellungen für eine erneute Installation erhalten. In Bestellungen gespeicherte Paketboxen bleiben immer erhalten.

Import / Export

Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. API-Schlüssel und -Geheimnis werden 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 bei einem normalen Speichern geprüft. Der gespeicherte API-Schlüssel und das Geheimnis bleiben erhalten.

Ablauf an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Instabee-Preis. Ist Ignore shipping zones aktiv, wird Instabee nur angeboten, wenn das Land erlaubt ist (die Geozone wird nicht geprüft). Andernfalls wird Instabee nicht angeboten, wenn eine Geo zone gesetzt ist und die Adresse außerhalb liegt. Nur Produkte mit Requires Shipping auf Yes zählen: andere Produkte erhöhen das Gewicht nicht und sind nicht im Bestellwert enthalten. Der Bestellwert ist der Preis der versandpflichtigen Produkte nach Abzug des Gutscheins und vor Steuer. Die Erweiterung prüft das Warenkorbgewicht und den Mindestbestellwert. Erreicht die Zwischensumme Free shipping from, beträgt der Preis 0. Andernfalls wird der Preis aus der Zeile Country prices des Ziellandes, der Zeile * oder dem Fallback cost genommen. Gibt es keinen Preis, wird die Methode ausgeblendet. Der Preis wird in Ihrer Standardwährung berechnet, auf deren Dezimalstellen gerundet und in der Währung des Kunden mit der Steuer der gewählten Tax class angezeigt.

Wählt der Kunde im Schritt Versandart Instabee und sind die API-Zugangsdaten gesetzt, erscheint unter der Methode für Schweden, Finnland, Dänemark, die Niederlande und Belgien ein Block Parcel box. Er listet die Boxen in der Nähe der Postleitzahl der Lieferadresse auf, sortiert nach Entfernung, mit Name, Adresse und Entfernung. Der Kunde kann eine andere Postleitzahl eingeben und auf Search klicken (oder Enter drücken). Solange keine Postleitzahl eingegeben ist, fordert der Block dazu auf. Werden keine Boxen gefunden, wird der Kunde gebeten, eine andere Postleitzahl zu versuchen oder eine andere Versandart zu wählen. Für andere Länder wird die Methode ohne Box angeboten.

Eine Paketbox ist Pflicht. Die gewählte Box wird für die Kasse nur gespeichert, wenn sie in der Budbee-Liste für diese Postleitzahl steht. Eine ohne Klick auf Search eingegebene Postleitzahl wird nicht verwendet. Klickt der Kunde im Schritt Versandart auf Continue, prüft die Erweiterung die Box auf dem Server erneut. Andernfalls sieht der Kunde Please choose an Instabee parcel box. Der Boxname stammt aus der Budbee-Liste, nicht aus dem Browser. Ändert der Kunde das Lieferland oder die Postleitzahl der Adresse, wird die frühere Auswahl verworfen.

Bei OpenCart 4 klickt der Kunde im Versandart-Block der Kassenseite auf Choose und wählt Instabee im Fenster Shipping method options. Der Block Parcel box erscheint in diesem Fenster unter der Instabee-Option und funktioniert genauso. Die Schaltfläche Continue des Fensters geht ohne eine Box aus der Liste nicht weiter, mit denselben Meldungen.

Die Erweiterung sendet an Budbee nur das Zielland und die Postleitzahl, niemals Namen, Adressen, E-Mails oder Bestelldaten. Boxlisten werden 12 Stunden pro Postleitzahl zwischengespeichert, eine Postleitzahl ohne Boxen 1 Stunde und eine fehlgeschlagene Anfrage 5 Minuten, damit eine langsame oder defekte API nicht jede Aktualisierung der Kasse verlangsamt. Die Kassenseite selbst wartet nie auf Budbee: Die Liste wird im Hintergrund geladen, sobald die Methode gewählt ist. Das API-Zeitlimit beträgt 10 Sekunden.

Ist die Budbee-API nicht erreichbar, sieht der Kunde Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. Die Bestellung wird dann markiert, und Sie wählen die Box, wenn Sie die Sendung buchen. Eine früher gewählte Box, die in diesem Moment nicht geprüft werden kann, bleibt erhalten und wird als nicht verifiziert markiert.

Die Erweiterung berechnet keine Live-Tarife, bucht keine Sendungen, druckt keine Etiketten, vergibt keine Sendungsnummern oder Sendungsverfolgungs-E-Mails, bietet keine Zeitfenster für die Budbee-Heimzustellung und zeigt keine Karte. Buchen Sie das Paket für die gewählte Box in Ihren Händlerwerkzeugen von Instabee / Budbee.

Abholstellen

Beim Anlegen der Bestellung wird die Box noch einmal geprüft und in der Bestellung gespeichert. Ab dann kann der Storefront sie nicht mehr ändern. Bei OpenCart 4 behält der Shop eine Bestellung für die Kasse und aktualisiert sie jedes Mal, wenn der Kunde erneut bestätigt; die Box der Bestellung wird dabei mit aktualisiert. Wechselt der Kunde diese Bestellung auf eine andere Versandart, wird ihre Box entfernt. Die Box wird an folgenden Stellen angezeigt:

Versandart der Bestellung: die Box wird dem Namen der Methode hinzugefügt, zum Beispiel Instabee parcel box: (der Methodenname), gefolgt von Boxname und Adresse. Dieser Text erscheint auf den Bestellseiten im Admin und im Kundenkonto, in den Bestell-E-Mails und auf der Rechnung.

Bestellseite im Admin (Sales > Orders): ein Feld Instabee parcel box mit Boxname, Adresse und Box ID. Konnte die Box an der Kasse nicht geprüft werden, ist sie als not verified (Budbee API was unavailable at checkout) markiert. Wurde keine Box gewählt, weil die API nicht verfügbar war, steht im Feld Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. Das Feld ist nur lesbar und wird auch angezeigt, wenn die Methode ausgeschaltet ist. Bei OpenCart 4 wird es über History angezeigt.

E-Mail über neue Bestellungen an den Shop: der Boxname mit ihrer ID oder Instabee parcel box: not chosen (Budbee API unavailable at checkout).

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Instabee ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Instabee > Edit, 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 gilt, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-shipping-instabee und der Link Manage licenses and domains in your account, der zu Ihrem vibefox.net-Konto führt. Nur Admin-Benutzer mit der Berechtigung Modify für die 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 Adresse des Shops geändert hat oder Sie in Ihrem Konto einen Domain-Platz 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 für eine Domain: die 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 Versandmethode Instabee Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Ein Admin-Benutzer, der im Admin im selben Browser angemeldet ist, sieht die Methode im Shop weiterhin, markiert als (unlicensed — visible to admins only), damit Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. Bei OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Methode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint auf dem Dashboard des Admins eine Erinnerung. Schließen Sie sie mit ×, um sie 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.

Wenn eine Lizenz abläuft, arbeitet die Erweiterung weiter, Updates und Support benötigen aber eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Admin-Dashboard oder die Seite Edit öffnen: 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 der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Instabee erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable/Disable eingeschaltet ist. Prüfen Sie Geo zone oder, wenn Ignore shipping zones aktiv ist, ob das Land unter Countries erlaubt ist. Prüfen Sie, ob das Land einen Preis hat oder eine Zeile * bzw. einen Fallback cost gibt. Prüfen Sie die Gewichtsgrenzen und Minimum order amount sowie, ob die Produkte Requires Shipping auf Yes haben. Eine Warnung über den Einstellungen zeigt an, wenn kein Preis konfiguriert ist. Aktivieren Sie Debug log, um den Grund im Feld Log zu sehen.

Kunden sehen die Liste der Paketboxen nicht: die Liste erscheint nur, wenn API key und API secret gesetzt sind, für Schweden, Finnland, Dänemark, die Niederlande und Belgien, und sobald eine Postleitzahl eingegeben wurde. Der letzte API-Fehler wird über den Einstellungen angezeigt. Details stehen im Feld Log auf der Erweiterungsseite. Aktivieren Sie Debug log für mehr Details.

HTTP 401 oder 403 im Protokoll: Budbee hat den API-Schlüssel oder das Geheimnis abgelehnt. Prüfen Sie beides und ob Test environment zu Ihren Zugangsdaten passt (Staging-Zugangsdaten nur mit eingeschalteter Testumgebung).

Keine Boxen für eine Postleitzahl: Budbee bedient diese Postleitzahl nicht. Der Kunde kann nach einer anderen Postleitzahl suchen oder eine andere Versandart wählen.

Der Kunde kann im Schritt Versandart nicht weitergehen: eine Paketbox muss aus der Liste gewählt werden, sofern die Budbee-API nicht erreichbar ist. Eine Box, die nicht in der Liste der gesuchten Postleitzahl steht, wird nicht gespeichert, und der Kunde sieht This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

Alte Boxlisten nach einer Änderung: klicken Sie auf der Erweiterungsseite auf Save. Dadurch werden die zwischengespeicherten Boxlisten gelöscht.

Die Seite zeigt „Warning: You do not have permission to modify VibeFox Instabee!“: Ihre Admin-Benutzergruppe darf die Einstellungen eventuell nur ansehen. Erteilen Sie der Gruppe die Berechtigung zum Ändern für extension/shipping/vfd_instabee (OpenCart 3) oder extension/vfd_instabee/shipping/vfd_instabee (OpenCart 4) unter System > Users > User Groups.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Instabee auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable/Disable, Sort order, Tax class und Geo zone zurück. Die zwischengespeicherten Boxlisten werden immer entfernt. Ist Remove data on uninstall aktiv, werden außerdem die Einstellungen, das Protokoll und die in Kassenvorgängen gewählten Boxen entfernt, die nie zu Bestellungen wurden. Ist es aus, bleiben die übrigen Einstellungen erhalten und werden bei einer erneuten Installation wieder verwendet. In Bestellungen gespeicherte Paketboxen bleiben immer erhalten, und bestehende Bestellungen behalten ihre Versandart und ihre Kosten.

Bei OpenCart 4 entfernen Sie außerdem die Dateien der Erweiterung, indem Sie nach der Deinstallation zu Extensions > Installer gehen, in der Liste der installierten Erweiterungen auf Uninstall (die orange −-Schaltfläche) neben VibeFox Instabee klicken und dann auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Instabee und Budbee sind Marken ihrer jeweiligen Inhaber. Diese Erweiterung ist nicht mit Instabee oder Budbee verbunden und wird von ihnen nicht unterstützt.