# 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"](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/01-xentral-apis-uebersicht.png)

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](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/02-xentral-api-account-formular.png)

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"](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/03-xentral-api-account-permissions.png)

> [!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](https://update.xentral.biz/apidoc/docs224.html). Hintergrund zur Anbindung: [Xentral-Hilfe — 3PL: Vorbereitende Einstellungen für Fulfillment-Anbindungen](https://help.xentral.com/hc/de/articles/360018710420).*

## 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](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/04-xentral-pat-uebersicht.png)

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](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/05-xentral-pat-allgemein.png)

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](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/06-xentral-pat-berechtigungen.png)

   > [!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"](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/07-xentral-pat-erzeugt.png)

> [!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](https://help.xentral.com/hc/de/articles/22627542067740).

## 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](https://ffn-connect.de/docs-assets/merchants/xentral/connect-xentral/_images/08-ffn-verkaufskanal-formular.png)

> [!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](/docs/merchants/xentral/stock).

> [!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](/docs/merchants/basics/products/release-to-fulfiller).

> [!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](/docs/merchants/xentral/order-import). Die Xentral-spezifischen Optionen für Rechnung, Auftragsbestätigung und Archivierung erklärt [Xentral-Einstellungen für Bestellungen](/docs/merchants/xentral/order-settings).

> [!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](/docs/merchants/xentral/order-troubleshooting).

## 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)](/docs/merchants/xentral/transfer-module) 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](/docs/merchants/xentral/order-import) |
| Lieferschein oder Auftrag, Rechnungsoptionen | [Xentral-Einstellungen für Bestellungen](/docs/merchants/xentral/order-settings) |
| Chargen und MHD zurückmelden | [Übertragungsmodul (SFTP) einrichten](/docs/merchants/xentral/transfer-module) |
| Bestände und Lagerplätze | [Warenbestände an Xentral übertragen](/docs/merchants/xentral/stock) |
| Retouren | [Retouren an Xentral übertragen](/docs/merchants/xentral/returns) |
| Es kommt keine Bestellung an | [Es kommen keine Bestellungen an](/docs/merchants/xentral/order-troubleshooting) |