Admin-API: Die Backend-Schnittstelle von Shopware 6 für ERP und Automatisierung

Die Admin-API ist die Schnittstelle, über die Shopware 6 von außen verwaltet wird: Produkte, Bestände, Bestellungen, Kunden und Einstellungen lassen sich damit lesen und schreiben. Sie ist der Standardweg, um ERP, PIM, CRM und Middleware an den Shop anzubinden, für Onlinehändler in Österreich genauso wie in Deutschland.

Alles, was Sie in der Administration von Shopware 6 tun können, lässt sich auch über die Admin-API erledigen: Produkte anlegen, Bestände ändern, Bestellungen lesen, Kunden aktualisieren, Statuswechsel auslösen. Die Administration selbst ist nur ein Client dieser API; jede Aktion im Backend ist ein API-Aufruf.

Genau deshalb ist die Admin-API der Standardweg für Anbindungen an Drittsysteme. ERP, PIM, Warenwirtschaft, CRM und Middleware sprechen mit Shopware über diese Schnittstelle, meist im Hintergrund und ohne Nutzerinteraktion. Sie ist REST-basiert, liefert JSON und erreicht alle Entitäten des Data Abstraction Layer.

Shopware 6 stellt zwei Schnittstellen bereit, die oft verwechselt werden:

• Admin-API: für Backend-Prozesse und Systemintegrationen. Vollzugriff im Rahmen der vergebenen Rechte, Authentifizierung per OAuth 2.0, Endpunkte unter /api/.
• Store-API: für Kunden-Frontends wie Storefront, Apps oder Headless-Shops. Arbeitet im Kontext eines Verkaufskanals und eines Kunden, Authentifizierung per sw-access-key, Endpunkte unter /store-api/.

Faustregel: Was ein Mitarbeiter in der Administration tut, gehört zur Admin-API. Was ein Kunde im Shop tut, gehört zur Store-API. Die Unterschiede im Detail erklärt unser Beitrag zu GraphQL und REST-APIs in Shopware.

Der Zugriff läuft über OAuth 2.0. Für Systemintegrationen legen Sie unter Einstellungen → System → Integrationen eine Integration mit eigener Rolle an und erhalten Zugriffsschlüssel-ID und Sicherheitsschlüssel. Damit fordern Sie ein Token an:

POST /api/oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "IHRE_ZUGRIFFSSCHLUESSEL_ID",
  "client_secret": "IHR_SICHERHEITSSCHLUESSEL"
}

Das Token ist zehn Minuten gültig und wird als Authorization: Bearer-Header mitgeschickt. Für Werkzeuge, die im Namen eines Benutzers arbeiten, gibt es zusätzlich den Grant-Typ password mit Refresh-Token. Vergeben Sie je Integration nur die Rechte, die der Prozess braucht; mit ACL-Rollen lässt sich der Zugriff bis auf einzelne Entitäten und Operationen einschränken. Hintergründe zum Protokoll finden Sie im Eintrag OAuth.

• Entitäten lesen und schreiben: GET /api/product, POST /api/product, PATCH /api/product/{id}, DELETE /api/product/{id}, analog für Bestellungen, Kunden, Kategorien, Medien und alle weiteren Entitäten.
• Suche mit Kriterien: POST /api/search/product mit Filtern, Sortierung, Paginierung, Aggregationen und Assoziationen. So laden Sie etwa alle Bestellungen eines Tages inklusive Positionen in einem Aufruf.
• Sync-API: POST /api/_action/sync schreibt viele Datensätze mehrerer Entitäten in einer Anfrage. Der richtige Weg für Bestands- und Preisabgleiche mit tausenden Artikeln.
• Aktionen: Statuswechsel per State Machine (/api/_action/order/{id}/state/…), Dokumente erzeugen, Mails versenden, Indexierung anstoßen.
• Versionierung und Metadaten: /api/_info/ liefert Version, verfügbare Entitäten und das OpenAPI-Schema; die Swagger-Oberfläche unter /api/_info/swagger.html dokumentiert alle Endpunkte.

In einer typischen ERP-Integration übernimmt die Admin-API diese Datenflüsse:

• Artikel und Preise: Das ERP ist führend, Shopware empfängt Stammdaten, Varianten und Preise per Sync-API.
• Bestände: Lagerbestände werden in kurzen Intervallen oder ereignisgesteuert aktualisiert, damit Verfügbarkeiten im Shop stimmen.
• Bestellungen: Das ERP holt neue Bestellungen per Suche mit Kriterium „Bestellstatus offen und noch nicht exportiert“ ab und markiert sie anschließend, etwa über ein Zusatzfeld.
• Status und Sendungsnummern: Versand- und Zahlungsstatus werden per State-Machine-Aktion zurückgeschrieben, Sendungsnummern an die Lieferung gehängt.

Statt zyklisch abzufragen, können Sie sich von Shopware benachrichtigen lassen: Webhooks melden neue Bestellungen oder geänderte Produkte, und die Integration lädt dann nur, was sich geändert hat. Welche Systeme sich so anbinden lassen, zeigt unsere Übersicht zu ERP- und CRM-Integrationen, ein konkretes Beispiel die Anleitung zu Xentral und Shopware 6.

• Sync-API für Massendaten: Einzelaufrufe pro Artikel sind bei großen Katalogen zu langsam; bündeln Sie Schreibvorgänge in Paketen von einigen hundert Datensätzen.
• Nur Änderungen übertragen: Mit updatedAt-Filtern oder Webhooks übertragen Sie nur Deltas statt des gesamten Bestands.
• Idempotent arbeiten: Verwenden Sie feste IDs (UUIDs) aus Ihrem Führungssystem, damit wiederholte Aufrufe keine Dubletten erzeugen.
• Fehler behandeln: Die Sync-API meldet Fehler je Datensatz; protokollieren und wiederholen Sie fehlgeschlagene Einträge gezielt.
• Indexierung beachten: Nach großen Importen laufen Indexer über die Message Queue; der Worker muss aktiv sein, sonst erscheinen Daten verzögert im Shop.
• Rechte und Secrets: eigene Integration je System, minimale Rolle, Schlüssel im Secret-Store, regelmäßige Rotation.

• 401 Unauthorized: Token abgelaufen oder falsche Zugangsdaten. Token erneuern, Integration prüfen.
• 403 Forbidden: Die Rolle der Integration hat das Recht für diese Entität oder Operation nicht.
• 400 bei Schreibvorgängen: Pflichtfelder fehlen oder Datentypen stimmen nicht; die Fehlermeldung nennt Feld und Pfad.
• Daten erscheinen nicht im Shop: Indexer oder Cache. Message-Queue-Worker prüfen, Cache leeren.
• Langsame Importe: Einzelaufrufe statt Sync-API oder zu große Pakete; mit dem Header indexing-behavior: use-queue-indexing lässt sich die Indexierung in die Warteschlange verlagern.

Die Admin-API ist das Rückgrat jeder Shopware-Integration. Wer ihre Logik versteht, mit OAuth 2.0, Suche mit Kriterien, Sync-API und State Machine, kann ERP, PIM und CRM zuverlässig anbinden. Für individuelle Anbindungen und Plugins, die die Admin-API um eigene Endpunkte erweitern, unterstützen wir Sie mit Shopware-Plugin-Entwicklung. Wir betreuen Händler in Österreich und Deutschland aus Bremen und Prishtina.