Dein Xentral verbinden

Schritt-für-Schritt-Anleitung, wie du dein Xentral-ERP mit FFN Connect verbindest — inklusive API-Account (Benutzername und Initkey) und Personal Access Token.

Schritt 1: Voraussetzungen

FFN Connect spricht zwei Xentral-Schnittstellen an, weil nicht alle benötigten Daten über dieselbe API verfügbar sind:

Schnittstelle Wofür FFN Connect sie nutzt Zugangsdaten
Xentral-API (NextGen) Lager, Lagerplätze, Bestände, Retouren, Auftragsstornierung Personal Access Token
Xentral REST-API (v1) und Standard-API Artikel, Aufträge, Lieferscheine, Rechnungen, Belegs-PDFs, Versandarten, Trackingnummern Benutzername und Initkey / Passwort eines API-Accounts

Du brauchst also insgesamt vier Angaben:

Angabe Wo du sie in Xentral findest
Xentral Domain Die Adresse, unter der dein Xentral im Browser läuft, z. B. https://12345.xentral.biz
Benutzername Feld App Name / Benutzername deines API-Accounts (Schritt 2)
API-Passwort Feld Initkey / Passwort desselben API-Accounts (Schritt 2)
Personal Access Token Kontoeinstellungen → Developer Einstellungen (Schritt 3)

Wichtig

Der Personal Access Token allein genügt nicht. Ohne API-Account (Benutzername + Initkey) schlägt die Einrichtung mit der Meldung „Validierung der Legacy Zugangsdaten fehlgeschlagen" fehl.

Tipp

Lege für die Anbindung einen eigenen API-Account an (z. B. ffn_connect) und verwende nicht die Zugangsdaten eines persönlichen Benutzerkontos. So bleibt die Verbindung bestehen, auch wenn ein Mitarbeiterkonto deaktiviert wird, und du kannst den Zugang jederzeit gezielt entziehen.

Schritt 2: API-Account in Xentral anlegen

Der API-Account liefert Benutzername und Passwort für die Digest-Authentifizierung der Xentral-REST-API.

Hinweis

Xentral führt die REST-API v1 als „Legacy" im Wartungsmodus — sie bekommt keine neuen Funktionen mehr, bleibt aber verfügbar und wird von Xentral weiter dokumentiert. Ein Abschaltdatum ist nicht angekündigt. FFN Connect benötigt sie weiterhin, weil die aktuelle Xentral-API die dafür nötigen Beleg- und Dokument-Endpunkte nicht abdeckt.

  1. Öffne in Xentral das Menü Einstellungen → Administration → Datenaustausch → APIs. Alternativ suchst du in der Smart Search (⌘K) nach APIs. In älteren Xentral-Versionen heißt der Punkt Administration → Einstellungen → API-Account.

  2. Klicke oben rechts auf Übertragungs-Account hinzufügen (in älteren Versionen: Neu).

    Xentral: Übersicht „Einstellungen / Administration / Datenaustausch / APIs" mit der Liste bestehender API-Konten und der Schaltfläche „Übertragungs-Account hinzufügen"

  3. Setze den Haken bei Aktiv — ohne ihn ist der Zugang gesperrt.

  4. Vergib bei Bezeichnung einen Namen, an dem du den Zugang wiedererkennst, z. B. FFN Connect.

  5. Trage bei App Name / Benutzername einen Namen ein, z. B. ffn_connect. Das ist später der Benutzername in FFN Connect.

  6. Trage bei Initkey / Passwort ein zufällig erzeugtes, langes Passwort ein. Das ist später das API-Passwort in FFN Connect.

    Xentral-Maske „API Account" mit den Feldern Aktiv, Bezeichnung, Projekt, App Name / Benutzername und Initkey / Passwort

  7. Klicke auf Speichern.

Hinweis

Die übrigen Felder der Maske brauchst du für FFN Connect nicht: Event URL und Warteschlangename Bezeichnung gehören zur Warteschlangen-Verarbeitung, UTF8 Clean und Ohne HTML Umwandlung sind Kompatibilitätsschalter für andere Fremdsysteme. Projekt lässt du leer (siehe unten).

Hinweis

Das Feld Projekt lässt du leer, solange du die Anbindung nicht bewusst auf ein einzelnes Xentral-Projekt beschränken möchtest.

Hinweis

Notiere dir den Initkey direkt bei der Anlage in deinem Passwort-Manager — er ist reines Zugangsdatum und wird von Xentral nicht noch einmal für dich aufbereitet.

Berechtigungen setzen

Die Rechte eines API-Accounts lassen sich granular einschränken: Öffne den Account über das Stift-Symbol und scrolle zum Bereich Permissions.

Xentral: Bereich „Permissions" eines API-Accounts mit der Schaltfläche „Alle aktivieren"

Tipp

Am einfachsten klickst du auf Alle aktivieren — das empfiehlt auch Xentral selbst für Fulfillment-Anbindungen. Die Einträge in der Liste tragen technische Namen (z. B. standard_artikelget), die sich nicht eins zu eins den unten genannten Bereichen zuordnen lassen.

Möchtest du die Rechte gezielt vergeben, brauchst du Zugriff auf diese Bereiche:

Ressource Zugriff Wofür
artikel lesen Artikelstamm und Artikelbilder
belege/auftraege lesen Auftragsimport
belege/lieferscheine lesen Lieferscheinimport, Versandrückmeldung
belege/rechnungen lesen Rechnungsabruf
dateien lesen Download von Rechnungs- und Lieferschein-PDFs
storage, storage/bin lesen, anlegen, ändern, löschen Lager und Lagerplätze für die Bestandsführung
versandarten lesen Zuordnung der Versandarten
trackingnummern anlegen Rückmeldung der Trackingnummern

Zusätzlich nutzt FFN Connect die Standard-API-Aufrufe AuftragGet, BelegPDF, LieferscheinFreigabe, LieferscheinArchivieren und WeiterfuehrenAuftragZuRechnung.

Hinweis

API-Accounts, die bereits vor Einführung der Berechtigungen existierten, haben automatisch alle Rechte. Bei einem neu angelegten Account musst du die Rechte selbst vergeben — fehlt eines, äußert sich das später als einzelner fehlschlagender Vorgang (z. B. „Rechnung konnte nicht abgerufen werden"), nicht als Verbindungsfehler.

Ressourcen und Authentifizierung: Xentral REST-API-Dokumentation. Hintergrund zur Anbindung: Xentral-Hilfe — 3PL: Vorbereitende Einstellungen für Fulfillment-Anbindungen.

Schritt 3: Personal Access Token erstellen

Der Token wird für die aktuelle Xentral-API benötigt (Lager, Bestände, Retouren).

  1. Klicke unten links auf deinen Benutzernamen und öffne die Kontoeinstellungen.

  2. Navigiere zu Developer Einstellungen → Personal Access Token (je nach Xentral-Version heißt der Punkt Entwickler Einstellungen).

  3. Klicke oben rechts auf Token erzeugen. In der Liste siehst du auch alle bestehenden Token samt Expiration date und Status.

    Xentral: Übersicht der Personal Access Token mit Schaltfläche „Token erzeugen", Ablaufdatum und Status

  4. Vergib im Bereich Allgemein einen sprechenden Namen, z. B. FFN Connect, und optional eine Beschreibung.

  5. Wähle bei Duration (Laufzeit) das längstmögliche Ablaufdatum — voreingestellt sind 180 Tage.

    Xentral: Bereich „Allgemein" beim Anlegen eines Personal Access Token mit Name, Duration und Beschreibung

  6. Weise darunter im Bereich Berechtigungen die Scopes zu. Ganz oben stehen die beiden als Critical markierten Scopes Admin read (Lesezugriff auf alle Endpunkte) und Admin (Vollzugriff). Darunter sind die Rechte nach Bereichen gruppiert — aufklappen und einzeln auswählen:

    Gruppe Für FFN Connect nötig
    Logistik ja — Aufträge und Lieferscheine
    Produkte ja — Artikelstamm, Matrixprodukte, Bilder
    Einstellungen ja — Projekte, Vertriebskanäle, Webhooks
    CRM nur, wenn Kunden- und Lieferantendaten mitlaufen sollen
    Buchhaltung nur bei Rechnungsabruf über die aktuelle API
    Identitäts- und Zugriffsmanagement, Mobile App nein

    Xentral: Bereich „Berechtigungen" eines Personal Access Token mit den Scopes „Admin read" und „Admin" sowie den Gruppen CRM, Buchhaltung, Logistik, Produkte

    Tipp

    Über das Feld Search scopes findest du einzelne Rechte schneller als über das Aufklappen der Gruppen.

    Wichtig

    Xentral vergibt nur Scopes, die dein eigener Benutzer ebenfalls besitzt („Du kannst nur die Scopes gewähren, die du als Nutzer auch hast"). Erstelle den Token deshalb mit einem Benutzer, der die nötigen Rechte hat. Im Zweifel startest du mit Admin und schränkst später mit einem neuen Token ein.

  7. Klicke auf Erstellen und kopiere den Token sofort — er wird nur ein einziges Mal angezeigt.

    Xentral: Dialog „Neuer Personal Access Token erzeugt" mit dem Token und der Schaltfläche „Copy"

Achtung

  • Das Erstellen von Tokens erfordert Administrator-Rechte in Xentral.
  • Läuft der Token ab, bricht die Verbindung ab. Ein Token, der 180 Tage lang nicht genutzt wurde, wird automatisch entfernt — vorher verschickt Xentral Erinnerungsmails.
  • Nachträglich lässt sich nur die Laufzeit ändern. Sollen sich die Rechte ändern, musst du einen neuen Token erstellen, ihn in FFN Connect hinterlegen und den alten löschen.

Hinweis

Die Screenshots stammen aus Xentral 26.31.3. In älteren Versionen sind die Berechtigungen als Matrix mit den Spalten Erstellen, Lesen, Aktualisieren, Löschen und Other aufgebaut — inhaltlich gilt dasselbe. Der Abschluss-Dialog mit dem erzeugten Token stammt aus der Xentral-Hilfe.

Schritt 4: Verkaufskanal in FFN Connect hinzufügen

  1. Wechsle in FFN Connect zu Verkaufskanäle → Verkaufskanal hinzufügen.
  2. Wähle Xentral aus.
  3. Fülle das Formular aus:
    • Name: Frei wählbar (optional), z. B. der Name deines Unternehmens.
    • Xentral Domain: Die Adresse deines Xentral, z. B. https://12345.xentral.biz — sie muss mit https:// beginnen.
    • Benutzername: Der App Name / Benutzername aus Schritt 2.
    • API Passwort: Der Initkey aus Schritt 2 — nicht dein Login-Passwort.
    • Xentral Personal Access Token: Der Token aus Schritt 3.
  4. Klicke auf Weiter. FFN Connect prüft beide Zugänge sofort.

FFN Connect: Formular zum Anlegen des Xentral-Verkaufskanals mit den Feldern Name, Xentral Domain, API Account Benutzername, Initkey / Passwort und Personal Access Token

Hinweis

  • „Validierung der NextGen Zugangsdaten fehlgeschlagen" → Der Personal Access Token stimmt nicht, ist abgelaufen oder hat zu wenig Rechte. Prüfe außerdem die Xentral Domain.
  • „Validierung der Legacy Zugangsdaten fehlgeschlagen" → Benutzername oder Initkey stimmen nicht, oder der API-Account ist nicht auf Aktiv gesetzt.

Schritt 5: Lager verknüpfen

FFN Connect ruft deine Xentral-Lager ab und verknüpft sie mit dem Lager deines Fulfillment-Dienstleisters. Navigiere dazu zum Menüpunkt Lager und klicke auf Synchronisieren.

Wichtig

Die Bestandsführung hängt an dieser Verknüpfung: FFN Connect legt in den verknüpften Xentral-Lagern eigene Lagerplätze an und schreibt die Bestände deines Fulfillment-Dienstleisters dorthin zurück. Ohne Verknüpfung findet kein Bestandsabgleich statt. Details dazu: Warenbestände an Xentral übertragen.

Hinweis

Falls hier noch nichts angezeigt wird, muss dir dein Fulfillment-Dienstleister noch die Freigabe für das Lager gewähren. Halte in diesem Fall Rücksprache und klicke dann erneut auf Synchronisieren.

Schritt 6: Artikel synchronisieren

  1. Öffne deinen Xentral-Verkaufskanal in FFN Connect, indem du zu Verkaufskanäle navigierst und auf den Namen des Verkaufskanals klickst.
  2. Klicke auf Produkte synchronisieren.
  3. Klicke auf Fortfahren und synchronisieren.

Der Vorgang kann je nach Anzahl deiner Artikel einige Minuten dauern. Anschließend siehst du deine Artikel in der Tabelle des Verkaufskanals. Damit dein Fulfillment-Dienstleister sie bearbeiten kann, gib sie im Hauptmenü unter Artikel frei — wie das geht, erklärt der Artikel Artikel an den Fulfiller freigeben.

Hinweis

Von den Artikelbildern importiert FFN Connect nur Dateien mit dem Subjekt Shopbild. Bilder ohne dieses Subjekt werden übersprungen.

Schritt 7: Bestellabruf aktivieren

Nach dem Verbinden ruft FFN Connect noch keine Bestellungen ab — dafür musst du zuerst ein Startdatum setzen und die Abrufart wählen:

  • Lieferscheine importieren (Standard, empfohlen): FFN Connect ruft Lieferscheine ab, sobald sie freigegeben oder bereits versendet sind. Lieferantenretouren werden ausgelassen.
  • Aufträge importieren: FFN Connect ruft stattdessen die Aufträge ab, sobald sie in Xentral den Status freigegeben haben. Aufträge im Status „angelegt" werden bewusst ignoriert.

Die vollständige Anleitung mit allen nötigen Einstellungen findest du unter Automatischen Bestellabruf aktivieren. Die Xentral-spezifischen Optionen für Rechnung, Auftragsbestätigung und Archivierung erklärt Xentral-Einstellungen für Bestellungen.

Wichtig

Bleibt eine Bestellung aus, prüfe als Erstes den Status in Xentral: Ohne Freigabe wird sie nicht abgerufen. Weitere Ursachen findest du unter Es kommen keine Bestellungen an.

Schritt 8: Rückmeldung an Xentral

Sobald dein Fulfillment-Dienstleister versendet hat, meldet FFN Connect das automatisch an Xentral zurück:

  • Trackingnummern werden zum Beleg hinterlegt, der Lieferschein wird freigegeben bzw. archiviert.
  • Optional wird der Auftrag zur Rechnung weitergeführt, die Rechnung als PDF abgerufen und der Auftrag abgeschlossen.
  • Bestandsänderungen aus dem Lager deines Fulfillment-Dienstleisters werden in die verknüpften Xentral-Lagerplätze zurückgeschrieben.

Welche dieser Schritte ausgeführt werden, steuerst du in den Einstellungen des Verkaufskanals (u. a. „Rechnung in Xentral erzeugen", „Rechnung übertragen", „Auftrag abschließen").

Sollen zusätzlich Chargen und MHD zurückgemeldet werden, richte das Übertragungsmodul (SFTP) ein.

Schritt 9: Testbestellungen durchführen

Wir empfehlen, nach Abschluss der Einrichtung eine oder mehrere Testbestellungen durchzuführen, um den Ablauf kennenzulernen:

  • Produkte ignorieren: Teste, wie du bestimmte Produkte aus Bestellungen ausschließen kannst.
  • Regeln festlegen: Lege fest, wie bestimmte Situationen behandelt werden sollen.
  • Bestand prüfen: Erstelle Bestellungen für Produkte ohne Bestand.
  • Fehlerhafte Lieferadressen: Gib bewusst fehlerhafte Adressen an, um zu sehen, wie diese Bestellungen markiert werden.

Wie geht es weiter?

Thema Artikel
Bestellabruf aktivieren Automatischen Bestellabruf aktivieren
Lieferschein oder Auftrag, Rechnungsoptionen Xentral-Einstellungen für Bestellungen
Chargen und MHD zurückmelden Übertragungsmodul (SFTP) einrichten
Bestände und Lagerplätze Warenbestände an Xentral übertragen
Retouren Retouren an Xentral übertragen
Es kommt keine Bestellung an Es kommen keine Bestellungen an

Nicht das Richtige gefunden?

Unser Support-Team hilft dir gerne weiter.

Support kontaktieren