Einrichtung

Mit wenigen Angaben verbinden Sie OBS mit Ihrem brShop24: Danach liest OBS Ihre Shop-Bestellungen automatisch als Aufträge ein und überträgt Preise, Kunden und Bestellvorlagen in den Shop. Am schnellsten geht das mit dem Einrichtungsassistenten, der in fünf Schritten Konfiguration, FTP-Abholung und Automatiken anlegt. Die Einrichtung dauert nur wenige Minuten. Alternativ richten Sie die Schnittstelle von Hand ein.

Auf einen Blick

Freischaltung. Der OBS-Support schaltet eine neue Shop-Schnittstelle frei.
Zugangsdaten. API-Endpunkt, OAuth2-Daten und FTP-Zugang finden Sie im Adminbereich Ihres Shops oder erhalten sie vom Büroring-Support.
Assistent. F9 in der Liste der Internet-Shops führt Sie in fünf Schritten durch die Einrichtung.
Ergebnis. Konfiguration, Definitionen, FTP-Abholung und Automatiken sind angelegt, die Schnittstelle ist aktiv.

Auf Wunsch übernimmt der OBS-Support die vollständige Einrichtung. Zu den Kosten sprechen Sie Ihren OBS-Betreuer an. Stellen Sie dem Support dafür die benötigten Daten bereit und teilen Sie mit:

welche Automatiken er anlegen soll. Standardmäßig richtet er die Automatiken für den Auftragsimport (ShopGetBestellungen) und für die Jobinformationen (ShopCheckExterneJobs) ein, die automatische Preispflege (ShopSetPreise) auf Wunsch. Ohne Angabe richtet er sich nach einer vorhandenen VShop-4.0-Schnittstelle.
welche Schnittstelle als Vorlage für die Einstellungen dienen soll, falls Sie mehrere haben. Ohne Angabe übernimmt er die Einstellungen einer vorhandenen VShop-4.0-Schnittstelle.
ob er nach der Einrichtung die Migration starten soll.

HINWEIS: Die Einrichtung umfasst nicht die Migration. Sie ist optional. Sind Sie von VShop 4.0 auf brShop24 gewechselt, empfehlen wir sie. Nutzen Sie die Schnittstelle zum Beispiel nur zum Einlesen der Bestellungen, kann sie entfallen. Sie können die Migration auch später ausführen.

ACHTUNG: Test vor dem Live-Betrieb: Büroring ermöglicht einen Test der Schnittstelle. Haben Sie bereits einen VShop, übernimmt Büroring dafür Ihre VShop-Daten. Nach dem Test setzt Büroring die Daten zurück und übernimmt für den Live-Betrieb den aktuellen Stand aus dem VShop 4.0. Dann muss auch die Schnittstelle in OBS zurückgesetzt werden, denn die Verknüpfungen zwischen OBS und Shop stimmen nicht mehr. OBS kann lokale Änderungen sonst nicht zuverlässig übertragen. Geben Sie dem OBS-Support deshalb vor der Umstellung auf den Live-Betrieb Bescheid, wann sie erfolgt. Das Zurücksetzen beschreibt Konfiguration.

Bei Fragen zur Einrichtung, für einen Termin oder eine Schulung erreichen Sie den OBS-Support per E-Mail oder über das Ticket-System.

Voraussetzungen

Der OBS-Support hat eine neue Shop-Schnittstelle freigegeben. Fordern Sie sie bei Bedarf über das Ticket-System oder per E-Mail an.
Für die Preispflege über die Schnittstelle arbeitet OBS mit Preislisten (kostenpflichtiges Modul).
Der Lieferant Büroring ist als Person in OBS angelegt. Mit dieser Personennummer sind die Einkaufsdaten in Ihrem Artikelstamm gepflegt.

ACHTUNG: Mit der Freigabe ist nur eine weitere Schnittstelle in OBS vorhanden. Eingerichtet und funktionsfähig ist sie damit noch nicht.

Benötigte Daten

Die Daten finden Sie im Adminbereich Ihres Shops. Alternativ erhalten Sie sie vom Büroring-Support. Von dort kommen sie meist als Textblock wie in diesem Beispiel:

Programmierschnittstelle (API) – immer erforderlich:

Angabe	Inhalt	Wo zu finden
URL API-Endpunkt	Über diese Adresse ruft OBS die API Ihres Shops auf. Es ist die Adresse Ihrer Shop-Hauptseite mit der Erweiterung `/apitest`, z.B. `https://<Ihre-Shop-Adresse>/apitest`.	Adminbereich, Administratoren → OAuth Clients, Eintrag Warenwirtschaft. Die URL des API-Endpunkts ergibt sich aus der Shop-Adresse.
OAuth2 Client ID	Mit OAuth2 meldet sich OBS an der API an. Ohne gültige Anmeldedaten lehnt der Server jeden Zugriff ab.
OAuth2 Client Secret	Längere Zeichenkette aus Buchstaben und Zahlen.
OAuth2 Token-Endpunkt	In der Regel die Adresse Ihrer Shop-Hauptseite mit der Erweiterung `/oauth/token`, z.B. `https://<Ihre-Shop-Adresse>/oauth/token`.

FTP – für das automatische Einlesen der Bestellungen:

Angabe	Inhalt	Wo zu finden
FTP Host	Adresse des FTP-Servers.	Adminbereich, Einstellungen → Accounts, Zugang FTP EDI Transfer (Büroring Server). Sind die Daten unvollständig, wenden Sie sich an den Büroring-Support.
FTP Benutzer	Benutzername für den FTP-Server.
FTP Passwort	Passwort für den FTP-Server.
FTP Abholverzeichnis	Verzeichnis mit den Bestelldateien, zusammen mit der Maske `order-be-`, z.B. `123456/order-be-`.

Soll der OBS-Support die Schnittstelle einrichten, prüfen Sie die Daten auf Vollständigkeit und ergänzen Sie fehlende Angaben.

Vorgehen

Einrichtung mit dem Einrichtungsassistenten

Öffnen Sie Stammdaten → Schnittstellen → Internet-Shop, markieren Sie die freigegebene Schnittstelle vom Typ brShop24 und drücken Sie F9 (F9 Einrich). Es öffnet sich der Assistent Shop-Schnittstelle einrichten. Mit Weiter gelangen Sie zum nächsten Schritt.

Schritt 1: Kommunikation API. Tragen Sie URL API-Endpunkt, OAuth2 Token-Endpunkt, OAuth2 Client ID und OAuth2 Client Secret ein. Die leeren Felder zeigen Beispiele, wie die Angaben aussehen. Alle vier Felder sind Pflicht.
Schritt 2: Einstellungen übernehmen. Möchten Sie die Einstellungen einer anderen Shop-Schnittstelle übernehmen, tragen Sie deren dreistellige Nummer in Kopieren von ein. Sonst lassen Sie das Feld leer. Übernommen werden vor allem die Einstellungen für den Auftragsimport. API-Zugangsdaten, Allgemein.Aktiv und die Debug-Einstellungen werden nicht übernommen.
Schritt 3: Stammdaten Büroring bestätigen. Prüfen Sie in OBS-Personennr. die Personennummer des Lieferanten Büroring, mit der die Einkaufsdaten in Ihrem Artikelstamm gepflegt sind. OBS belegt das Feld aus Programmparameter 0696 vor, in der Regel stimmt der Wert schon.
Schritt 4: Automatiken. Tragen Sie FTP Abholverzeichnis, FTP Host, FTP Benutzer und FTP Passwort für die Abholung der Bestelldateien ein. Besteht bereits eine Abholung, lassen Sie die Felder leer. Wählen Sie dann die Automatiken aus, die der Assistent anlegen soll, siehe Automatiken des Assistenten.
Schritt 5: Einrichtung ausführen. Klicken Sie auf Ausführen. Der Assistent arbeitet die fünf Punkte der Liste ab, siehe Was der Assistent ausführt. Beim Punkt Definitionen importieren fragt OBS im Fenster Auswahl Definitionsimport, welche Definitionen es einlesen soll. Übernehmen Sie die Auswahl. Hinter jedem Punkt erscheint ein grünes Häkchen oder ein rotes Kreuz.
Klicken Sie auf Fertig, um den Assistenten zu schließen.

HINWEIS: Solange der Assistent geöffnet ist, ist die Schnittstelle inaktiv: Beim Start setzt er Allgemein.Aktiv auf N. Brechen Sie mit Abbrechen ab, stellt OBS den vorherigen Wert wieder her. Schritt 5 schaltet die Schnittstelle aktiv.

Automatiken des Assistenten

Die Automatiken legt der Assistent mit Standardzeiten in den automatischen Vorgängen an. Ihre Bemerkung beginnt mit „Shop“ und der Schnittstellennummer, z.B. Shop 001 Bestellungen importieren. Die Zeiten können Sie später anpassen. Was die Automatiken tun, steht unter Automatiken.

Im Feld Ausführung auf PC trägt der Assistent Vorgaben ein: 999 steht für den Dienst OBS und gilt für den Bestellimport, 998 steht für den Dienst Shop und gilt für die übrigen Automatiken. Auf das Feld haben nur wenige Benutzer Zugriff. Ändern müssen Sie die Werte in der Regel nicht.

Auswahl in Schritt 4	Automatik	Vorbelegt	Ausführung
Bestellung importieren (wichtig)	`ShopGetBestellungen` – liest die Bestelldateien im Format OpenTRANS als Aufträge ein.	✓	alle 5 Minuten
Preispflege-Protokoll verarbeiten (wichtig)	`ShopCheckExterneJobs` – holt Status und Protokoll der Preispflege-Jobs ab. Der Shop übernimmt Preise nicht direkt, sondern arbeitet sie aus einer Aufgabenliste ab. So erfährt OBS, welche Jobs erledigt sind und wo Probleme auftraten.	✓	alle 30 Minuten
Automatische Preispflege (empfohlen)	`ShopSetPreise` – überträgt Preisänderungen automatisch in den Shop. Sinnvoll, wenn Sie die automatische Artikelpflege nutzen und sich Preise täglich ändern können.	–	täglich um 7:30 Uhr, ab dem folgenden Tag
Definitionen aktualisieren (optional)	`BrShop24ImportDefinitionen` – liest die Definitionen des Shops ein, z.B. Lager, Anreden und Steuersätze. So hat OBS nach Änderungen im Shop wieder den aktuellen Stand. Manuell geht das im Shop-Menü mit W Definitionen importieren.	–	wöchentlich sonntags um 16:00 Uhr

HINWEIS: Hat Büroring Preisdaten aus einem früheren VShop in den brShop24 übernommen, richten Sie die automatische Preispflege erst nach der Migration der Preislisten ein.

Was der Assistent ausführt

Punkt in Schritt 5	Was passiert
Konfiguration der Schnittstelle	Übernimmt die Einstellungen der Schnittstelle aus Schritt 2 und trägt die API-Daten aus Schritt 1 ein. Schaltet die Schnittstelle aktiv und den Debugmodus ein.
Verbindungstest	Baut eine Verbindung zum Shop auf. Läuft nur, wenn der erste Punkt geklappt hat.
Definitionen importieren	Liest die Definitionen aus dem Shop ein, z.B. Lager und Partner, Anreden, Kundentypen und Kunden-Klassifizierungen. Setzt die Standardeinstellungen für die Lager des Büroring und trägt die OBS-Personennummer aus Schritt 3 beim Partner ein. Läuft nur, wenn die ersten beiden Punkte geklappt haben.
FTP-Abholung einrichten	Legt in der FTP Jobliste den Job brShop24 Bestellabholung an. Er holt die Bestelldateien in das Verzeichnis `data\shop\<Schnittstellennummer>\xml`. Prüfen Sie danach im Job, dass Source-File nicht löschen nicht gesetzt ist, siehe Abholung der Bestellungen.
Automatiken anlegen	Legt die in Schritt 4 gewählten Automatiken an.

So sieht eine erfolgreiche Einrichtung aus:

Manuelle Einrichtung

Öffnen Sie Stammdaten → Schnittstellen → Internet-Shop, markieren Sie die Schnittstelle vom Typ brShop24, drücken Sie F10 und wählen Sie X Konfiguration.
Tragen Sie die API-Daten ein: Allgemein.Shop.URL (URL mit API-Endpunkt, z.B. https://<Ihre-Shop-Adresse>/apitest), OAuth2.ClientId, OAuth2.ClientSecret und OAuth2.TokenEndpoint (z.B. https://<Ihre-Shop-Adresse>/oauth/token).
Prüfen Sie, dass Allgemein.Aktiv auf J steht. Mit N ist die Schnittstelle inaktiv.
Drücken Sie F9 für den Verbindungstest. OBS meldet „Verbindung erfolgreich.“
Schließen Sie die Konfiguration und wählen Sie im Shop-Menü (F10) W Definitionen importieren.
Öffnen Sie wieder X Konfiguration und drücken Sie F8. Ordnen Sie im Zuordnungsmenü mindestens zu:
- A Anreden – nötig für die Übertragung von Personen, siehe Anreden.
- L Lager und Lagerlieferanten – Voraussetzung für die Übertragung von Preisen und Artikeln, siehe Lager und Lagerlieferanten.
Richten Sie die Abholung der Bestellungen ein, siehe Abholung der Bestellungen.
Legen Sie die Automatiken an, siehe Automatiken einrichten.

ACHTUNG: Wollen Sie die Migration für Preislisten ausführen, verknüpfen Sie vorher mindestens die Lager und Lieferanten mit Ihren OBS-Daten (L Lager und Lagerlieferanten).

Weitere Zuordnungen beschreibt Konfiguration.

Abholung der Bestellungen

OBS erzeugt die Aufträge aus XML-Dateien im Format OpenTRANS. Büroring stellt sie per FTP oder per E-Mail bereit. Je nach Weg richten Sie in OBS die FTP-Abholung oder das E-Mail-Konto ein. Die Dateien müssen im Verzeichnis data\shop\<Schnittstellennummer>\xml der OBS-Installation landen.

Abholung per FTP

Sie brauchen mindestens Host-Adresse oder IP des FTP-Servers, Benutzername und Passwort. Wie Sie einen FTP-Job anlegen, steht unter FTP Jobliste. So sieht ein Beispiel aus:

Nummer, Name und Bezeichnung vergeben Sie frei. Tragen Sie bei Kunden-Nr die Personennummer des Lieferanten Büroring ein. Status muss auf 01 stehen, damit der Job aktiv ist.
In Source-File tragen Sie den Pfad vom Startverzeichnis des FTP-Zugangs aus zusammen mit der Dateimaske ein. Arbeiten Sie mit dem Präfix der Dateinamen, damit keine falschen Dateien abgeholt werden. Die Bestelldateien des brShop24 beginnen mit order-be-. Soweit bekannt, nutzt der Shop denselben FTP-Server wie der Austausch von Bestellungen und Lieferavisen. Den Pfad können Sie dann aus dem Job für die Lieferavise übernehmen.
In Destination-File tragen Sie das xml-Verzeichnis der Shop-Schnittstelle ein. Die Kurzform genügt, OBS ergänzt den Pfad beim Abholen, z.B. für Schnittstelle 001: data\shop\001\xml\
Tragen Sie als Typ BR24 ein. FTP-Auftrag steht auf empfangen.
Setzen Sie Source-File nicht löschen nicht. Dann löscht der Job die Bestelldateien nach der Abholung auf dem FTP-Server. Ist das Häkchen gesetzt, bleiben die Dateien dort, sammeln sich an und werden bei jedem Lauf erneut abgeholt. OBS erkennt bereits eingelesene Dateien zwar an Dateiname und Prüfsumme und legt den Auftrag nicht doppelt an. Unnötige Dateien im Import führen aber leicht zu Problemen. Auch Job nach Ausführung Löschen (nur bei empfangen) bleibt leer, sonst entfernt OBS den Job nach dem ersten Lauf.
Übertragungsart bleibt auf FTP/S. Tragen Sie in Host die Adresse des FTP-Servers und in Benutzer und Passwort Ihre Zugangsdaten ein. Behalten Sie Port 21 und Passiv Ja bei, sofern Sie keine anderen Angaben erhalten haben.

Abholung per E-Mail

Für den Empfang per E-Mail muss das Konto in OBS eingerichtet sein und eine Regel den Anhang in einem Verzeichnis speichern:

So sieht ein Beispiel aus:

Tragen Sie in Konto das E-Mail-Konto ein. Es muss in OBS eingerichtet sein und E-Mails empfangen können. Legen Sie die Bedingungen der Regel fest.
Wählen Sie als Aktion Anhang speichern unter und wählen Sie mit der Schaltfläche # rechts daneben das xml-Verzeichnis der Shop-Schnittstelle aus. Die Aktionen Als gelesen markieren und Als erledigt markieren sind optional. Sie halten die Liste der empfangenen E-Mails übersichtlich.

Automatiken einrichten

Wie Sie Automatiken anlegen, steht unter Automatiken. Für brShop24 richten Sie diese ein:

Muss: ShopGetBestellungen (Bestellungen einlesen) und ShopCheckExterneJobs (Jobinformationen der Preispflege).
Empfohlen: ShopSetPreise (automatische Preispflege), beachten Sie den Hinweis unter Automatiken des Assistenten.
Optional: BrShop24ImportDefinitionen (Definitionen importieren).

Für Ausführung auf PC gelten dieselben Vorgaben wie beim Assistenten: 999 (Dienst OBS) für ShopGetBestellungen, 998 (Dienst Shop) für die übrigen Automatiken.

Ergebnis

Im Assistenten steht hinter allen fünf Punkten ein grünes Häkchen.
In der Konfiguration steht Allgemein.Aktiv auf J, und F9 meldet „Verbindung erfolgreich.“
In den automatischen Vorgängen stehen die gewählten Automatiken, in der FTP Jobliste der Job brShop24 Bestellabholung.
Neue Bestellungen aus dem Shop erscheinen nach dem nächsten Lauf von ShopGetBestellungen als Aufträge in OBS.

HINWEIS: Nach dem Assistenten ist der Debugmodus eingeschaltet: Allgemein.Debug steht auf J, Allgemein.Debug.LogLevel auf 5. Das ist gewollt. Der Debugmodus erweitert das Protokoll und ist für Problemfälle gedacht. Läuft die Schnittstelle zuverlässig, schalten Sie ihn in der Konfiguration aus (Allgemein.Debug = N). Dafür brauchen Sie Level 9 für die Shop-Schnittstellen.

Haben Sie vorher den VShop 4.0 genutzt, führen Sie jetzt die Migration durch.

Wenn es nicht klappt

Meldung	Ursache
„Bitte alle Felder füllen“	In Schritt 1 des Assistenten ist ein Feld leer.
„FTP-Daten sind unvollständig. FTP-Abholung nicht eingerichtet.“	In Schritt 4 sind nicht alle vier FTP-Felder gefüllt. Der Punkt FTP-Abholung einrichten erhält ein rotes Kreuz. Besteht bereits eine Abholung, ist das ohne Bedeutung.
Rotes Kreuz bei Definitionen importieren	Der Zugriff auf die API ist noch nicht freigegeben. OBS kann zwar eine Verbindung aufbauen, darf aber nicht lesen und schreiben. Wenden Sie sich an den Büroring-Support. Schlug schon der Verbindungstest fehl, liegt die Ursache dort.
„Es ist ein Fehler bei der Ausführung aufgetreten.“	Bei einem Punkt in Schritt 5 ist ein unerwarteter Fehler aufgetreten. Der betroffene Punkt hat ein rotes Kreuz.
„Verbindung konnte nicht aufgebaut werden.“ (F9 in der Konfiguration)	`Allgemein.Aktiv` steht auf N, oder die Zugangsdaten stimmen nicht. Die Ursachen der folgenden HTTP-Fehler prüfen.
HTTP-Fehler 401 (nicht authentifiziert)	Client-ID oder Client-Secret sind falsch eingegeben oder nicht (mehr) gültig. Prüfen Sie die Konfiguration und klären Sie bei Bedarf mit Büroring, ob die Daten noch gelten.
HTTP-Fehler 404 (nicht gefunden)	Die Adresse für die Anmeldung (`OAuth2.TokenEndpoint`) oder für die API (`Allgemein.Shop.URL`) ist falsch. Am häufigsten ist der Token-Endpunkt falsch: Auf die Adresse der Shop-Hauptseite folgt nur `/oauth/token`. Enthält die Adresse davor noch `apitest` (z.B. `https://<Ihre-Shop-Adresse>/apitest/oauth/token`), entfernen Sie `apitest`. Stimmt der Token-Endpunkt, prüfen Sie die API-Adresse. Sie endet in der Regel auf `/apitest`. Fragen Sie bei Bedarf beim Büroring-Support nach, ob die Adressen stimmen und die API freigeschaltet ist.
HTTP-Fehler 500 (interner Serverfehler)	Der Fehler entsteht bei der Abfrage auf der Seite von Büroring und muss dort geprüft werden. Meist sind es Altdaten aus der Migration, die sich schnell beheben lassen.
(12175) Es ist ein Sicherheitsfehler aufgetreten	Die Verbindung lässt sich nicht mit dem erwarteten Sicherheitsprotokoll aufbauen. Möglich ist, dass TLS 1.2 auf dem Server nicht richtig eingerichtet ist. Das ist bei aktuellen Windows-Server-Versionen Standard, lassen Sie es bei Bedarf von Ihrem Server-Administrator prüfen. Möglich ist auch eine falsche Adresse, z.B. ohne `www` (`https://meinshop.de/apitest` statt `https://www.meinshop.de/apitest`). Vergleichen Sie die Konfiguration mit den Daten von Büroring und testen Sie die mitgeteilte Adresse. Auch Umleitungen ohne gültiges SSL-Zertifikat für die Adresse können den Fehler auslösen.

Siehe auch