Xentral API: Schnittstellen sinnvoll planen und umsetzen

Die Xentral API verbindet dein ERP mit anderen Anwendungen. Sie ist dann interessant, wenn Daten zwischen Systemen fließen oder Arbeitsschritte automatisiert werden sollen, die eine vorhandene Integration nicht ausreichend abdeckt. Für ein verlässliches Ergebnis brauchst du neben dem technischen Zugriff vor allem klare Regeln: Wer liefert welche Daten, wann werden sie verarbeitet und was passiert bei einem Fehler?

Dieser Leitfaden hilft dir, ein Schnittstellenprojekt vorzubereiten und Angebote von Entwicklern einzuordnen. Die konkrete Verfügbarkeit einzelner Funktionen muss anhand deiner Xentral-Instanz und der jeweiligen Endpunkt-Dokumentation geprüft werden.

Was kostet die Xentral API?

Unterscheide drei Kostenarten: das Xentral-Softwarepaket, mögliche Mehrkosten für API-Aufrufe und die Entwicklung sowie Betreuung deiner Schnittstelle. Der API-Zugang ist laut Xentrals Leistungsbeschreibung in Business, Pro und Scale vorgesehen. Die öffentliche Xentral-Preisseite führt API-Zugriff ebenfalls ab Business auf.

Zur Einordnung: Business beginnt laut Leistungsbeschreibung für Neukunden im Umsatzcluster Standard S unter 750.000 € bei 649 € netto pro Monat im Jahresvertrag mit jährlicher Abrechnung. Im Monatsvertrag mit monatlicher Abrechnung sind es 719 € netto. Das ist der Basispreis für das Softwarepaket inklusive Support, kein separater API-Preis. Höhere Umsatzcluster und zusätzliche Leistungen verändern den Gesamtpreis.

Wie viele API-Aufrufe sind enthalten?

Das monatliche Inklusivvolumen richtet sich nach dem Umsatzcluster. Die Leistungsbeschreibung vom 1. April 2026 nennt:

• Standard S / M / L: 12.500 / 25.000 / 50.000 API-Aufrufe pro Monat.
• Growth S / M / L: 75.000 / 125.000 / 250.000 API-Aufrufe pro Monat.
• Premium S / M / L: 500.000 / 1.000.000 / 2.500.000 API-Aufrufe pro Monat.

Softwarepaket und Umsatzcluster sind unterschiedliche Größen: Pro ist ein Softwarepaket, Premium ein Cluster. Kläre deshalb beides für dein Angebot. Nicht genutztes Inklusivvolumen verfällt laut Leistungsbeschreibung am Monatsende.

Was kosten zusätzliche API-Aufrufe?

Für externe API-Aufrufe oberhalb des Inklusivvolumens nennt die Leistungsbeschreibung 1 € netto je angefangene 1.000 Aufrufe. Aufrufe durch Xentral selbst oder eigene Xentral-Dienste werden laut Beschreibung nicht berechnet.

Rechenbeispiel: Bei 12.500 enthaltenen und 20.000 abrechnungsrelevanten externen Aufrufen in einem Monat bleiben 7.500 zusätzliche Aufrufe. Diese ergeben acht angefangene Tausenderblöcke und damit 8 € netto API-Mehrkosten. Der Software-Basispreis und die Kosten deines Integrationsdienstleisters kommen separat hinzu. Dieses Beispiel ist keine Kundenauswertung.

Bei Nutzung über Xentral Flows oder Connect sieht die Beschreibung keine doppelte Berechnung von API-Aufrufen und den entsprechenden Ausführungen beziehungsweise Jobs vor; es zählt die höher bepreiste Nutzung. Für diese Produkte gelten eigene Volumen und Preise.

Welche Kosten entstehen für die Schnittstelle selbst?

Das API-Volumen bezahlt noch keine individuelle Integration. Konzeption, Programmierung, Tests, Hosting, Überwachung und laufende Anpassungen solltest du im Dienstleisterangebot getrennt prüfen. Ein belastbarer Projektpreis hängt von Datenobjekten, Übertragungsrichtungen, Sonderfällen und Betriebsanforderungen ab. Plane auch Erstimporte, regelmäßige Abfragen und Wiederholungen nach Fehlern in deine erwarteten Aufrufmengen ein.

Preisquelle: Xentral ERP Software GmbH, Leistungsbeschreibung vom 01.04.2026, Seiten 2–3 und 6–7; am 17.09.2026 mit der öffentlichen Preisseite hinsichtlich Business-Einstieg und API-Zugang abgeglichen. Die detaillierten Verbrauchskonditionen stammen aus der Leistungsbeschreibung. Maßgeblich für deine Buchung sind dein konkretes Angebot und die vereinbarten Vertragsbedingungen.

Wann eine individuelle Schnittstelle sinnvoll ist

Beginne mit dem Geschäftsprozess. Welche manuelle Arbeit soll entfallen? Ein guter Ausgangspunkt ist etwa: „Unser Fulfillment-Dienstleister soll freigegebene Lieferdaten erhalten und Tracking zurückmelden.“ Damit lässt sich prüfen, ob eine bestehende Anbindung genügt. „Wir brauchen eine API“ beschreibt dagegen noch kein Ergebnis.

Mögliche Projekte sind die Übergabe an ein externes Lager, ein gezielter Datenaustausch mit einem CRM oder die Bereitstellung von Daten für ein Reporting. Xentral beschreibt solche Integrations- und Automatisierungszwecke im Überblick zur neuen API.

Eine vorhandene Integration kann sinnvoller sein, wenn sie die benötigten Objekte, Übertragungsrichtungen und Sonderfälle bereits unterstützt. Individuelle Entwicklung ist eine Option, wenn eine konkrete Lücke bleibt. Vergleiche dabei auch Wartung, Fehlermeldungen und Zuständigkeiten nach der Inbetriebnahme.

Das führende System pro Datenart festlegen

„Beide Systeme synchronisieren alles“ ist keine ausreichende Spezifikation. Entscheide für jede Datenart, welches System Änderungen vorgeben darf. Beispielsweise können Produkttexte im Shop gepflegt werden, während das ERP den für den Verkauf vorgesehenen Bestand liefert. Das ist eine Projektentscheidung und kein allgemeingültiger Xentral-Standard.

• Identität: Welche stabile Nummer verbindet denselben Artikel oder Auftrag in beiden Systemen?
• Richtung: Welches System schreibt, welches liest?
• Auslöser: Startet die Übertragung nach einem Ereignis oder in vereinbarten Zeitabständen?
• Konflikt: Was passiert, wenn beide Seiten denselben Datensatz ändern?
• Ausnahme: Wer bearbeitet fehlende Zuordnungen oder unvollständige Daten?

Halte diese Regeln an konkreten Beispieldatensätzen fest. Ein Artikel mit Varianten oder ein Auftrag mit mehreren Lieferungen zeigt oft früher als eine abstrakte Feldliste, ob das Konzept vollständig ist.

Beispiel: Eine Übergabe an den Fulfillment-Dienstleister

Im offiziellen Fulfillment-Leitfaden beschreibt Xentral einen Ablauf, bei dem die externe Anwendung auf ein Versandübergabe-Ereignis reagiert, zugehörige Daten abruft und später Tracking ergänzt. Die Freigabe innerhalb von Xentral und die Bearbeitung im externen Lager bleiben dabei getrennte Schritte.

Für dein Projekt bedeutet das: Definiere zuerst den fachlichen Übergabepunkt. Danach legst du fest, wie der Empfänger den Vorgang wiedererkennt und bestätigt. Kommt dieselbe Nachricht erneut, darf daraus kein zweiter Versandauftrag entstehen. Diese Wiederholungssicherheit muss die Integration bewusst herstellen.

Auch Statusbezeichnungen verdienen Aufmerksamkeit. Laut Xentrals Leitfaden ist der Status eines Lieferscheins nicht mit dem physischen Paketversand gleichzusetzen. Prüfe deshalb, welche Information der Shop tatsächlich als Versandbestätigung erhalten soll. Weitere organisatorische Fragen behandelt unser Ratgeber zur Fulfillment-Anbindung.

Zugriff, Datenmengen und API-Versionen prüfen

Xentral dokumentiert persönliche Zugangstoken für den API-Zugriff. Behandle diese wie Zugangsdaten: Sie gehören in die geschützte Konfiguration der Integration, nicht in öffentliche Webseiten oder ein Projektbriefing. Lege außerdem fest, wer den Zugriff verwaltet und bei einem Wechsel des Dienstleisters übergibt.

Plane die benötigten Aktionen pro Endpunkt. Übertrage keine Parameter ungeprüft zwischen API-Versionen. Beispielsweise beschreibt die V3-Dokumentation zu Filterung und Seitennavigation mehrere Arten, größere Ergebnismengen abzurufen. Welche Felder und Grenzen gelten, hängt vom Endpunkt ab.

Für die Kapazitätsplanung sind außerdem die aktuellen Zugriffslimits wichtig. Xentral kennzeichnet die Werte als veränderlich und verweist auf die Antwort-Header der jeweiligen Instanz. Bei einer Begrenzung muss die Integration warten und kontrolliert fortsetzen können. Eine feste Zusage für beliebig viele Echtzeitabrufe wäre deshalb keine belastbare Projektgrundlage.

Fehlerbehandlung gehört zum Leistungsumfang

Eine erfolgreiche Testübertragung beweist noch keinen stabilen Betrieb. Vereinbare, wie fehlgeschlagene Vorgänge sichtbar werden, wer sie übernimmt und wie sie erneut verarbeitet werden. Die Protokollierung sollte den betroffenen Vorgang erkennen lassen, ohne unnötig Zugangsdaten oder vollständige Kundendaten zu speichern.

Prüfe mindestens vier Situationen: Das Zielsystem antwortet nicht; ein Pflichtfeld fehlt; dieselbe Übertragung wird wiederholt; ein längerer Rückstand muss aufgeholt werden. Ein regelmäßiger Abgleich zwischen Quelle und Ziel hilft, Lücken zu finden, die eine reine Erfolgsmeldung einzelner Aufrufe nicht zeigt.

Zur Übergabe gehören deshalb eine verständliche Betriebsbeschreibung, Zuständigkeiten, eine Möglichkeit zur Fehleranalyse und ein vereinbartes Vorgehen bei Änderungen. Das sollte im Angebot genauso erkennbar sein wie die eigentliche Programmierung.

Für die technische Vorbereitung findest du eine eigene Anleitung zu API-Token, Rechten und Laufzeiten. Wenn mehrere Systeme beteiligt sind, hilft die Entscheidungshilfe zu Middleware zwischen Shop und ERP. Beide Fragen sollten vor dem Entwickler-Briefing geklärt sein.

Vom Geschäftsprozess zu einem prüfbaren Datenvertrag

Bevor ein Entwickler die erste Verbindung baut, sollte für jeden übertragenen Vorgang eine kurze Vereinbarung vorliegen. Gemeint ist kein juristischer Vertrag, sondern eine lesbare Beschreibung von Eingabe, Verarbeitung und erwartetem Ergebnis. Damit können auch Operations und Kundenservice beurteilen, ob die Integration richtig arbeitet.

Ein illustratives Beispiel für eine Lageranbindung: Xentral übergibt einen freigegebenen Liefervorgang mit einer stabilen Vorgangskennung. Das Lager muss die Artikel anhand vereinbarter Artikelnummern erkennen. Es meldet nach der Bearbeitung die vereinbarten Versandinformationen zurück. Eine unbekannte Artikelnummer wird als Ausnahme sichtbar und erzeugt keinen stillschweigend unvollständigen Versandauftrag.

• Objekt und Identität: Welche Xentral-ID und welche externe ID gehören zusammen? Wo wird die Zuordnung dauerhaft gespeichert?
• Pflichtdaten: Welche Angaben braucht der Empfänger zwingend, und wer korrigiert fehlende Angaben?
• Einheiten und Formate: Was bedeuten Mengen, Zeitangaben und Statuswerte? Welche Umrechnung ist vereinbart?
• Änderungsregeln: Darf ein Auftrag nach der Übergabe noch verändert werden? Wie werden Korrektur und Storno behandelt?
• Bestätigung: Reicht die Annahme einer Nachricht, oder muss der Zielvorgang bereits erstellt sein, bevor die Übertragung als erledigt gilt?

Trage anschließend den konkreten Endpunkt mit Methode, API-Version und Dokumentationslink daneben ein. Prüfe an einem freigegebenen Testdatensatz, ob die Antwort tatsächlich die benötigten Felder liefert. Ein vorhandener Lese-Endpunkt belegt weder eine Schreibfunktion noch die Unterstützung aller fachlichen Sonderfälle. Der Einstieg für diese Prüfung ist die offizielle Xentral-API-Dokumentation.

Aufrufmengen planen: Ein kleiner Zeitplan kann viele Requests erzeugen

Das monatliche Abrechnungsvolumen und das technische Zugriffslimit sind zwei unterschiedliche Grenzen. Ein Prozess kann das monatliche Budget überschreiten, obwohl er zu keinem Zeitpunkt besonders schnell arbeitet. Umgekehrt kann ein kurzer Erstimport das technische Limit erreichen, obwohl noch ausreichend Monatsvolumen vorhanden ist.

Illustrative Rechnung: Eine einzelne Abfrage pro Minute rund um die Uhr verursacht in einem angenommenen Monat mit 30 Tagen bereits 43.200 Aufrufe: 60 Minuten mal 24 Stunden mal 30 Tage. Das gilt auch dann, wenn diese Abfragen überwiegend keine neuen Datensätze finden. Weitere Listenseiten, Detailabrufe, Schreibvorgänge und Wiederholungen kommen in dieser vereinfachten Rechnung noch hinzu.

Erstelle deshalb eine Mengenplanung pro Prozess: reguläre Abfragen, Verarbeitung neuer Vorgänge, Erstübernahme, Abgleich und Fehlerwiederholungen. Schätze zusätzlich, welchen Rückstand die Integration nach einer Unterbrechung aufholen muss. Prüfe danach, ob verfügbare Ereignisse den regelmäßigen Abruf reduzieren können. Ein Ereignis kann weitere Detailabrufe auslösen und macht die Integration daher nicht automatisch aufruffrei.

Auch die Seitennavigation beeinflusst die Last. Die V3-Dokumentation unterscheidet einfache Seitennavigation, eine Variante mit Gesamtanzahl und Cursor-Navigation. Eine Gesamtanzahl kann zusätzliche Datenbankarbeit verursachen; Cursor-Navigation eignet sich für das schrittweise Weiterarbeiten, erlaubt aber keinen beliebigen Sprung auf eine bestimmte Seite. Welche Variante dein Endpunkt unterstützt, prüfst du in der Referenz zu Filterung, Sortierung und Pagination.

Was nach einem Timeout passieren soll

Ein besonders wichtiger Testfall ist eine unterbrochene Antwort: Das Zielsystem könnte den Auftrag bereits angelegt haben, obwohl deine Integration keine Bestätigung empfangen hat. „Noch einmal senden“ ist dann keine vollständige Fehlerstrategie. Ohne Wiedererkennung kann derselbe Vorgang zweimal entstehen.

Unsere Empfehlung ist ein nachvollziehbarer Verarbeitungsnachweis pro Vorgang. Er enthält die stabile Quellkennung, die bekannte Zielkennung, den letzten bestätigten Schritt und den Fehlerstatus. Vor einer Wiederholung muss die Integration erkennen können, ob der Vorgang bereits verarbeitet wurde. Das ist das Ziel von Wiederholungssicherheit, häufig als Idempotenz bezeichnet. Ob ein bestimmter Endpunkt dafür eine eigene technische Funktion anbietet, muss separat in seiner Referenz geprüft werden.

• Zugriff abgelehnt: Token, Berechtigung und Zielinstanz prüfen. Eine unveränderte Anfrage nicht endlos wiederholen.
• Daten zurückgewiesen: Den beanstandeten Datensatz mit Feld und Vorgangskennung einer zuständigen Person zuordnen. Nach Korrektur gezielt erneut verarbeiten.
• Zeitüberschreitung: Vor einem erneuten schreibenden Vorgang dessen möglichen Erfolg im Zielsystem klären.
• Aufruflimit erreicht: Die dokumentierten Antwortinformationen berücksichtigen, kontrolliert warten und den Rückstand beobachten.
• Ereignis fehlt oder kommt verspätet: Über einen vereinbarten Abgleich erkennen, welche fachlichen Vorgänge noch nicht im Zielsystem angekommen sind.

Diese Punkte sind Anforderungen an das Integrationskonzept, keine Zusage, dass Xentral oder ein beliebiger Connector sie automatisch übernimmt. Für die Ereignisauswahl bietet die Webhook-Referenz den technischen Einstieg; für den Versandprozess zeigt der Fulfillment-Leitfaden das Zusammenspiel von Ereignis, Datenabruf und Rückmeldung.

Eine Abnahme, die mehr als den Erfolgsfall prüft

Vereinbare zu jedem Test vorab das erwartete Ergebnis. Bei einem wiederholten Ereignis lautet es beispielsweise: derselbe Zielvorgang bleibt erhalten, es entsteht kein zweiter Auftrag, und die Wiederholung ist im Verarbeitungsnachweis erkennbar. Bei einer unbekannten Artikelnummer lautet es: keine unvollständige Übergabe, eine verständliche Ausnahme und ein festgelegter Weg zur Korrektur.

1. Einen vollständigen Standardvorgang von der Quelle bis zum fachlich nutzbaren Zielzustand verfolgen.
2. Dasselbe Ereignis erneut verarbeiten und die Wiederholungssicherheit prüfen.
3. Einen unvollständigen Testdatensatz verwenden und den Korrekturprozess durchspielen.
4. Eine kontrollierte Unterbrechung simulieren und anschließend den Abgleich sowie das Aufholen prüfen.
5. Eine zulässige Korrektur oder einen Storno anhand der vereinbarten Änderungsregeln testen.
6. Die Übernahme durch die später zuständige Person prüfen: Kann sie einen offenen Vorgang finden, verstehen und bearbeiten?

Nutze dafür einen abgestimmten Testkontext, in dem keine echten Pakete, Rechnungen oder Kundennachrichten ausgelöst werden. Zur Übergabe gehören außerdem der Verantwortliche für Zugangstoken, die Dokumentation der eingesetzten Endpunkte, die Überwachung offener Vorgänge und der vereinbarte Umgang mit API-Änderungen. Diese Ergebnisse kannst du direkt in die Go-live-Checkliste übernehmen.

Checkliste für dein Entwickler-Briefing

1. Beschreibe den heutigen Ablauf und das gewünschte Ergebnis.
2. Nenne Quell- und Zielsystem sowie die betroffenen Datenarten.
3. Lege Datenhoheit, Zuordnungsschlüssel und Übertragungsrichtung fest.
4. Gib typische Mengen, Spitzen und die fachlich erlaubte Verzögerung an.
5. Beschreibe Sonderfälle wie Storno, Teillieferung und doppelte Nachrichten.
6. Vereinbare messbare Abnahmeszenarien mit erwartetem Ergebnis.
7. Kläre Überwachung, Fehlerbearbeitung, Dokumentation und Übergabe.

Mit diesen Angaben kann ein Dienstleister prüfen, ob Konfiguration, eine bestehende Anbindung oder individuelle Entwicklung passt. Wenn du Unterstützung bei der Einordnung brauchst, nutze unser bestehendes ERP-Audit. Bringe dazu deinen Ablauf, die beteiligten Systeme und ein bis zwei typische Problemfälle mit.

Quellenstand: 17. September 2026. Die verlinkten Xentral-Dokumentationen belegen die Produktangaben. Briefing, Prüfschritte und Projektentscheidungen sind unsere redaktionellen Empfehlungen.