Admin API

Für wen ist diese Anleitung?

Für Sie als Shop-Betreiber, wenn Sie das Bonus System an ein anderes System anbinden wollen — zum Beispiel an eine Warenwirtschaft, ein CRM oder ein Kassensystem — und für Entwickler, die Punkte von außerhalb von Shopware lesen oder buchen möchten.

Was die Admin API ist

Die Admin API ist die Schnittstelle, über die die Shopware-Administration mit dem Server kommuniziert. Das Bonus System nutzt sie vollständig — direkt nach der Installation, ohne dass Sie etwas konfigurieren müssen. Speichern, Bearbeiten und Anzeigen im Admin-Modul läuft darauf.

Entitäten

Die Daten des Plugins sind reguläre Shopware-Entitäten. Shopware stellt dafür automatisch die CRUD-Endpunkte bereit und dokumentiert sie in Ihrem Shop:

/api/_info/stoplightio.html#/schemas/PremsBonusSystemUserPoint — Punktekonto eines Kunden
/api/_info/stoplightio.html#/schemas/PremsBonusSystemBooking — Buchungen
/api/_info/stoplightio.html#/schemas/PremsBonusSystemCondition — Bedingungen
/api/_info/stoplightio.html#/schemas/PremsBonusSystemBonusProduct — Bonus Produkte
/api/_info/stoplightio.html#/schemas/PremsBonusSystemImportPoint — Import-Tabelle für die Migration

Punktekonten sollten Sie nicht direkt über die Entität schreiben. Nutzen Sie stattdessen die Endpunkte zum Buchen — nur so entsteht eine nachvollziehbare Buchung, und der Flow-Builder-Trigger Bonus Punkte verändert wird ausgelöst.

Endpunkte des Bonus Systems

Alle Endpunkte benötigen ein gültiges Admin-API-Token (POST /api/oauth/token). Ein vollständiges Beispiel inklusive Postman-Sammlung finden Sie unter Update von Bonus Punkten mit der API.

Methode	Pfad	Zweck
POST	`/api/v2/prems-bonus-system/create-bonus-booking`	Punkte über die Kundennummer buchen. Body: `customerNumber`, `points` (positiv oder negativ), `description`, optional `salesChannelId`.
POST	`/api/_action/prems/create-bonus-booking-by-customer-id`	Punkte über die Kunden-ID buchen. Body: `customerId`, `points`, `description`, optional `salesChannelId`.
GET	`/api/v2/prems-bonus-system/get-bonus-points/{customerNumber}`	Aktuellen Punktestand zu einer Kundennummer lesen.
GET	`/api/prems-bonus-system/get-bonus-points-by-customer-id/{customerId}`	Aktuellen Punktestand zu einer Kunden-ID lesen.
GET	`/api/v2/prems-bonus-system/get-bonus-bookings/{customerNumber}`	Buchungen eines Kunden lesen, optional eingeschränkt über die Parameter `startDate` und `endDate`.
POST	`/api/prems-bonus-system/get-points-expire-in-days`	Punkte lesen, die bald verfallen. Body optional: `customerNumber` oder `customerId`, `days`, `limit`, `offset`.
POST	`/api/prems-bonus-system/reset-bonus-bookings`	Punktekonto zurücksetzen — optional nur für einen Kunden über `customerNumber`, mit `description` als Buchungsgrund.

reset-bonus-bookings setzt Punktestände zurück und ist nicht umkehrbar. Ohne customerNumber betrifft der Aufruf alle Kunden. Vorher sichern und auf einem Testsystem prüfen.

Berechtigungen

Für den Zugriff über einen Integrations-Zugang oder eine Benutzerrolle müssen die Rechte auf die Entitäten des Bonus Systems gesetzt sein. Können Sie im Admin-Modul keine Punkte speichern oder bleiben Listen leer, fehlt in der Regel eine Berechtigung in der Benutzerrolle.

Alternative: Buchungen per Flow oder Export

Punkte automatisiert innerhalb von Shopware buchen: Flow Builder und Regeln
Buchungen als CSV auswerten: Import/Export-Profil mit der Entität Bonussystem: Buchungen, siehe Buchungen