WooCommerce-Shop mit Billbee verbinden

Billbee unterstützt den Bestellimport aus einem WooCommerce-Shop. WooCommerce ist ein Plugin für WordPress, dass einen kompletten Online-Shop implementiert. Der Datenabgleich mit WooCommerce erfolgt seit Version 2.1 über die offizielle WooCommerce REST API. Wie du deinen WooCommerce-Shop an Billbee anbinden kannst und was du dabei beachten musst, findest du in diesem Artikel.

In diesem Artikel

Schritt-für-Schritt Anleitung zur Einrichtung
wichtig / zu beachten
mögliche Fehlercodes und ihre (mögliche) Bedeutung

Schritt-für-Schritt Anleitung zur Einrichtung

Für die Einrichtung eines WooCommerce-Shops an Billbee musst du zuerst ein paar Einstellungen in deinem WooCommerce-Shop vornehmen. Anschließend kannst du deinen Shop dann mit Billbee verbinden.

Vorbereitung deines WooCommerce-Shops

Bevor du deinen WooCommerce-Shop mit deinem Billbee-Account verbinden kannst, musst du bei WooCommerce einige Einstellungen vornehmen. Zum einen musst du Permalinks aktivieren, die Einstellung "einfach" darf hier nicht gewählt werden. Zudem musst du einen Schlüssel mit Lesen/Schreiben Berechtigung im Bereich der REST-API generieren. Der/die WordPress-Benutzer:in, für den/die dieser Key generiert wird, muss Mitglied der WordPress-Benutzergruppe "admin" sein

WooCommerce mit Billbee verbinden

Um eine neue Shopverbindung bei Billbee einzurichten, klicke unter Einstellungen / Kanäle auf die Kachel "Shop hinzufügen".

Jetzt öffnet sich ein Pop-Up Fenster, in dem dir alle Shop- und Marktplatzverbindungen angezeigt werden, die an Billbee angebunden werden können. Klicke hier auf "WooCommerce-Shop". Fülle nun im Reiter "Eigenschaften" alle Informationen aus:

1: Name: Vergib einen beliebigen Namen für deinen WooCommerce-Shop. Dieser Name wird intern zur Wiedererkennung genutzt.

2: URL: Gib hier die vollständige URL deines Shops ein. Das sieht dann z. B. so aus: https://www.meinshop.com Sollte dies nicht funktionieren versuche es einmal ohne www also dann: https://MeinShop.de

3: WooCommerce API Key: Gib hier den API Key ("Verbraucherschlüssel" oder "Consumer Key") ein, den du im Vorfeld bei WooCommerce generiert hast.

4: WooCommerce API Passwort: Gib hier das Passwort ("Verbraucher-Geheimnis" oder "Consumer Secret") des API Keys ein, den du im Vorfeld generiert hast bei WooCommerce.

5: WooCommerce API Version: Gib an, um welche API Version es sich handelt (V2 oder V3).

6: Erweiterte Einstellungen: Mit einem Klick auf "Anzeigen" werden dir die verschiedenen Bestellstatus Zuordnungen angezeigt. Diese Zuordnungen musst du bitte zwingend vornehmen, damit der Status jeweils korrekt zugeordnet werden kann. Ansonsten kommt es zu einer Fehlermeldung bei der Synchronisierung von Billbee und WooCommerce. Sowohl die Statuszuordnungen von Billbee zu WooCommerce, als auch von WooCommerce zu Billbee müssen vorgenommen werden und müssen stimmig sein. Nur so wird sichergestellt, dass ein geänderter Bestellstatus in Billbee auch in den WooCoomerce Shop übertragen wird. Darüber hinaus kannst du weitere Einstellungen in diesem Bereich vornehmen wie z. B. "Informationen zu Zahlungen" oder "Versandinformationen in den Metadaten übermitteln" (hierfür ist ein eigens programmiertes Plugin notwendig). Die weitere Aufschlüsselung von den "erweiterten Einstellungen" findest du weiter unten.

7: Änderungen an Bestellungen abgleichen: Wähle aus, in welche Richtung die Änderungen abgefragt werden sollen. Du kannst zwischen nie (kein Abgleich), WooCommerce zu Billbee, Billbee zu WooCommerce oder beidseitig. Standardmäßig ist beidseitig ausgewählt (WooCommerce-Shop <-> Billbee)

8: Aufträge einlesen: Lege fest, ob über die Verbindung Bestellungen eingelesen werden sollen. Diese Option ist standardmäßig aktiviert beim Anlegen der Verbindung und muss aktiviert sein, damit Bestellungen von WooCommerce zu Billbee übertragen werden können. Ist die Option aktiviert, dann kannst du noch auswählen, ab welchem Datum die Bestellungen importiert werden sollen.

9: Mindestalter der Bestellung in Minuten: Legt fest, wie alt eine Bestellung beim Shopabruf mindestens sein muss, damit sie importiert wird. Neuere Bestellunegn werden erst zu einem späteren Zeitpunkt importiert. Nutzt du in deinem Shop Apps, die Änderungen an deinen Bestellungen vornehmen, lege mindestens 2 Minuten fest. Beachte: Solltest du in deinem Shop Webhooks verwenden und ein Mindestalter eingestellt haben, wird die Bestellung nicht automatisch X Minuten nach Eingang der Bestellung importiert, sondern erst beim nächsten Shopabruf.

10: Bearbeiten von Auftragspositionen verbieten/ Erzeugen von Rechnungen mit Billbee verbieten: Setzt du den Haken bei "Bearbeiten von Auftragspositionen verbieten", kannst du Bestellpositionen, die mit einer Bestellung aus WooCommerce übermittelt werden quasi "sperren". Dadurch werden Auftragspositionen einer von WooCommerce übertragenen Bestellung in Billbee nicht mehr manuell bearbeitbar sein. Mit einem Haken bei "Erzeugen von Rechnungen mit Billbee verbieten" verbietest du Billbee die Rechnungserstellung für Bestellungen, die aus deinem WooCoomerce-Shop eingelesen wurden. So werden für alle aus WooCommerce übermittelten Bestellungen keine Rechnungen erzeugt. Dies bedeutet jedoch auch, dass generell keine Rechnungen - weder manuell noch automatisch- für Bestellungen von dir erstellt werden können, die dieser Shopverbindung zugeordnet sind.

11: Artikel Preisanpassung: Hier kannst du optional einen Artikel festlegen, der Auftragspositionen zur Preisanpassung zugeordnet wird.

12: SMTP Server: Hast du bereits einen SMTP Server angelegt bei Billbee, kannst du diesen hier über das Dropdown-Menü auswählen.

13: Zahlung fällig nach X Tagen: Hier kannst du die Anzahl an Tagen angeben, ab wann die Zahlung fällig sein soll. Der angegebene Wert wird dann dem Ausstellungsdatum der Rechnung hinzugefügt. Er wird beim Import von Bestellungen übernommen und in das entsprechende Feld in den Bestelldetails eingetragen (wenn die Zahlart einer Bestellung "Rechnung" ist). Hast du hier keinen individuellen Wert angegeben, erfolgt ein Fallback auf das Ausstellungsdatum der Rechnung +30 Tage.

14: Versand aus: Innerhalb der Shopverbindung kann das Feld "Versand aus" gefüllt werden. Der hinterlegte Wert wird auf das gleichnamige Feld in Bestellungen aus der jeweiligen Shopverbindung übertragen.

15: Anonymisieren von Kundendaten aktivieren: Mit dieser Option hast du die Möglichkeiten Kundendaten aus deinen Bestellungen zu anonymisieren. Du kannst als Zeitspanne zwischen 1 - 730 Tagen wählen und weiterhin, ob die Bestellungen bei der Anonymisierung einen von dir hinterlegten Status erhalten sollen. Weitere Informationen zur Anonymisierung findest du hier.

Erweiterte Einstellungen

Statuszuordnung Billbee -> WooCommerce: Ordne hier alle Statuszuordnungen von Billbee zu WooCoomerce zu.
Statuszuordnung WooCommerce -> Billbee: Ordne hier alle Statuszuordnungen von WooCommerce zu Billbee zu.

1: Zahldatum interpolieren: Ist das Häkchen gesetzt, wird kein Zahldatum gesetzt. WooCoomerce hat kein Feld "Zahldatum". Daher interpoliert Billbee das Zahldatum als Zahlart, Status und Bestelldatum.

2: Webhooks deaktivieren: Ist diese Option aktiviert, legt Billbee keine Webhooks an. Das ist u.U. bei Shops mit sehr vielen Bestellungen sinnvoll, damit Billbee nicht bei jeder kleinen Änderung sofort einen Abruf startet.

3: Erstattungen einlesen: Ist das Häkchen gesetzt, liest Billbee die Erstattungen zu Bestellungen in WooCommerce ein.

4: Auftragsdatum als Rechnungsdatum übernehmen: Ist diese Option aktiviert, übernimmt Billbee das Auftragsdatum auch für das Feld "Rechnungsdatum".

5: Versandinformationen in den Metadaten übermitteln: Ist das Häkchen gesetzt, übermittelt Billbee die Versandinformationen (Provider, Versandprodukt, Trackingnummer/-Link) in den Meta-Daten, wenn der Status "versendet" zum Shop übertragen wird.

6: Bestellungen mit unvollständiger Adresse ignorieren: Ist diese Opton aktiv, werden alle Bestellungen von Billbee ignoriert, bei denen die Adressfelder (Straße, Wohnort und PLZ) unvollständig sind und kein Vor- oder Nachname angegeben wurde.

Wechselt du jetzt in den Reiter "Synchronisierung", kannst du die Synchronisierungsintervalle der Shopverbindung konfigurieren, d.h. festlegen, wie häufig Bestellung in einem Zeitfenster eingelesen werden sollen. Besonderheit bei WooCommerce: Selbst wenn der automatische Abruf der Tabelle komplett auf 0 gestellt ist, werden Bestellungen eingelesen, wenn die Webhooks in der Anbindung aktiviert sind. Bei aktivierten Webhooks werden Bestellungen unabhängig davon eingelesen, welche Einstellung in der Tabelle im Reiter "Synchronisierung" vorgenommen wurde.

Wichtig / zu beachten

WooCommerce-Versionen

Die Versionen 2.1.0 bis 2.1.11 enthalten einen Fehler bei der Authentifizierung und können mit Billbee nicht verwendet werden.

Plugins

Billbee ist mit einer Standardinstallation von WooCommerce kompatibel - wegen der Vielzahl möglicher Plugins können wir keine Aussage treffen, welche Plugins grundsätzlich mit Billbee kompatibel sind. Zusätzliche Felder, die durch Plugins zu WooCommerce hinzugefügt werden, werden unter Umständen nicht abgeglichen.

Cloudflare Plugin

Wenn du das Cloudflare Plugin für WooCommerce nutzt, benötigst du folgende Infos, um Billbee auf die Whitelist zu setzen:

Die Domain: api.billbee.io
IP-Ranges: 49.12.91.128/29 & 159.69.228.168/29

Ist Billbee nicht auf der Whitelist, erscheint ein Fehler beim Abruf, der nur "Status" aussagt.

Bitte beachte: Der Bot-Flight Mode in Cloudfare überschreibt noch einmal die IP-Whitelist der Firewall-Rules. Dadurch kann es vorkommen, dass die IP weiterhin blockiert bleibt. Du müsstest den Bot-Flight Mode in diesem Fall deaktivieren oder ihn entsprechend upgraden, um dann die IP-Ranges dort ebenso zu ergänzen.

VAT ID

Billbee unterstützt nur die Standardkonfiguration von WooCommerce und auch nur einige Plugins. Bei manchen Plugins kann es zu Problemen führen, z. B. beim Einlesen der VAT ID. Damit die VAT ID richtig eingelesen werden kann, muss sie den entsprechenden Keys übertragen werden, weshalb du bei der Auswahl des Plugins darauf achten solltest. Folgende Keys werden berücksichtigt:

"_billing_vat_id"
"_billing_vat"
"billing_vat"
"billing_vat_id"
"vat_id"
"_vat_number"
"vat_number"

Mit German Market funktioniert das Einlesen der VAT ID im Normalfall.

Veraltete API

Bitte achte darauf, dass du die aktuelle REST API nutzt und keine veralteten Versionen. Ältere Shopverbindungen sollten auf die neue API umgestellt werden. Wenn du Webhooks nutzt, dann deaktiviere vorher einmal die Webhooks in deinen WooCommerce Einstellungen, speichern diese Einstellung, dann stell auf die neue API um und aktiviere die Webhooks wieder.

Datenaustausch via Webhooks

Wenn die Synchronisierung von Daten ausbleibt, kann es sein, dass euer Shop keine Webhooks an Billbee schickt. Das heißt: Änderungen würden nur dann synchronisiert, wenn sie nach dem letzten Shopabruf erfolgten. Damit der Datenaustausch funktioniert, solltest du deshalb die Webhooks in den Kanaleinstellungen zunächst deaktivieren und speichern und anschließend in den WooCommerce Einstellungen → erweitern → Webhooks prüfen, ob diese gelöscht wurden. Danach kannst du die Weebhooks in Billbee wieder aktivieren. Somit werden die Webhooks auch in WooCommerce wieder gesetzt und der Datenaustausch gewährleistet.

Preise bei WooCommerce

Artikel sollten in dem WooCommerce-Shop als Bruttopreise (inkl. Mehrwertsteuer) hinterlegt werden, da Billbee beim Import von Artikeln Bruttopreise erwartet.

Mögliche Fehlercodes & ihre Bedeutung

Fehlercode/-meldung	Bedeutung	Lösung
401 Unauthorized	Zugangsdaten falsch	überprüfe deine Zugangsdaten und korrigiere sie ggf.
400 HTTP Fehler NotFound	URL falsch REST API nicht korrekt aktiviert	überprüfe die URL deines Shops und ihr Format. überprüfe die REST API in deinem WooCommerce Shop
403 Forbidden	Zugangsdaten korrekt, aber Aktion nicht erlaubt	Überprüfe deine Berechtigungen bei WooCommerce Commerce, sprich ggf. mit dem/der Administrator:in deines Shops
Unexpected character encountered while parsing value: <. Path", line 0, position 0.	Link zum Shop nicht korrekt	Gib die Aderesse zum Shop ohne /shop ein, also "http://meineseite.de" statt "http://meineseite.de/shop"
414 Request URI too long oder "an error has occured"	die gesendete Anfrage vom Shop Server ist zu lang	An der Länge der Abfrage lässt sich nichts ändern, aber an der Einstellung des WebServers. Bei WordPress gibt es dazu eine Einstellung: Security-> Tweaks -> Prevent Long URL Strings. Diese muss abgeschaltet werden, falls sie aktiv ist. Mehr Infos dazu hier.
500 (alle 500er Nummern) internal_server_error	Interne Server Fehler	Hier liegt der Fehler auf dem Server, auf dem dein Shop installiert ist. Häufig liegt ein solcher Fehler an Plugins, mit denen Billbee nicht kompatibel ist. Deaktiviere alle Plugins bei WooCommerce und versuch die Anbindung erneut vorzunehmen
503 Service unavailable	wird oft gesendet, wenn z.B. der Shop im Wartungsmodus ist	Abwarten und zu einem späteren Zeitpunkt erneut versuchen
One or more errors occurred. -> Value was either too large or too small for an Int32.	kann beim Artikelimport auftreten, wenn ein numerischer Wert eines Artikels zu groß ist	Prüfe deine Artikel und ihre numerischen Werte. Häufige Fehlerquelle sind z. B. ein sehr hoher Bestand oder ein zu großes Gewicht.
Signatur stimmt nicht überein	URL falsch Uhrzeit des Servers ist nicht korrekt	überprüfe die URL deines Shops und ihr Format. überprüfe die Uhrzeit des Servers. Geht die Uhrzeit mehr als ein paar Sekunden falsch, kann es zur Fehlermeldung kommen.
Bestand von Artikel mit SKU 123 im Shop ABC konnte nicht gesetzt werden: rest_no_route - Es wurde keine Route gefunden, die mit der URL und der Request-Methode identisch ist.	kann auftreten, wenn kein Artikel mit der entsprechenden Quell-ID im Shop gefunden werden kann	Kontrolliere die Quell-IDs deiner Artikel und korrigiere sie ggf.
Das Konto XY WooCommerce konnte aufgrund eines Fehlers nicht synchronisiert werden: Der Shop antwortet mit HTTP Fehler Unauthorized	Shop noch nicht live Seite, auf die zugegriffen werden soll, ist passwortgeschützt
woocommerce_rest_cannot_view - Entschuldigung, es können keine Ressourcen aufgelistet werden	Der WordPress-Benutzer, für den der Key generiert wurde, ist kein Mitglied der Benutzergruppe "admin"	Entsprechende:n Benutze:in anlegen und für diesen einen neuen Key mit Lese- und Schreibrechten generieren
Status für Auftrag XYZ konnte nicht übermittelt werden. Anfrage fehlgeschlagen: Status Der Zugriff auf die Ressource wurde nicht gestattet. Bitte wende dich an den Support deine Dienstleister.	Billbee hat nicht die Berechtigung, in dem Shop zu schreiben. Möglicherweise hat der Key, den du für die Verbindung verwendest, keine Schreibberechtigung im Shop. Der Status kann ebenfalls aufgrund von in WooCommerce verwendeten Plugins auftreten.	Generiere einen neuen Key mit Schreib- und Leserechten - der/die WooCommerce User:in, für den/die dieser Key generiert wird, muss Mitglied der WordPress-Benutzergruppe "admin" sein. Deaktiviere einmal deine Plugins. Manchmal kann auch ein reines Deaktivieren der Plugins hier nicht ausreichend sein. Selbst wenn man Plugins deaktiviert, setzen manche Plugins wie z. B. Wordfence Einträge in die htaccess welche auch bestehen bleiben, wenn man die Plugins löscht. Es müsste dann die .htaccess Datei der Seite einmal gelöscht und neu geschrieben werden.
Fehler beim Abruf der PayPal Informationen zu einer Bestellung: invalid_client - Client Authentication failed	Bei verschiedenen Zahlarten, vor allem PaypalPlus auf Rechnung, müssen auf der Rechnung Zahlungshinweise für den Kunden ausgegeben werden, die für jede Bestellung verschieden sind. Damit Billbee diese aus dem Shop abrufen kann, müssen unter "erweiterte Einstellungen" die gleichen Zugangsdaten hinterlegt werden, die auch im Paypal Modul im Shop verwendet werden. Der Fehler bedeutet, das hier die falschen Zugangsdaten hinterlegt sind.	In den Einstellungen der Woocommerce-Shopverbindung kannst du unter "Erweiterte Einstellungen" ebenfalls Paypal-Zugangsdaten hinterlegen. (Punkt 6 der Einrichtung) Hier musst du immer die Zugangsdaten eintragen, die du im Paypal-Modul in deinem Shop verwendest - das müssen nicht in jedem Fall die gleichen Paypal-Zugangsdaten sein, die du für den Zahlungsabgleich in Billbee verwendest.