API-Referenz

Diese lange Seite zeigt den Aufbau einer Referenz. Rechts steht das Inhaltsverzeichnis, jeder Endpunkt hat eine feste Sprungmarke, die sich als Link teilen lässt (z. B. api-referenz#store-get-notice).

Basis-URLs

API	Basis-URL	Authentifizierung
Store API	/store-api	Header sw-access-key
Admin API	/api	OAuth 2 Bearer-Token

Store API

Hinweis zu einem Produkt laden

GET /store-api/gb-notice/{productId}

Liefert den aktuell gültigen Hinweis eines Produkts. Ist kein Hinweis gültig, antwortet die Route mit 204 No Content.

Pfad-Parameter

Name	Typ	Pflicht	Beschreibung
productId	UUID	✓	ID des Produkts

Antwort 200 OK

{
  "apiAlias": "gb_notice",
  "id": "0190a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
  "text": "Versand nur innerhalb Deutschlands.",
  "position": "below_price",
  "validFrom": null,
  "validUntil": "2026-12-24T23:59:59+00:00"
}

Fehler

Status	Code	Bedeutung
400	GB_NOTICE__INVALID_ID	productId ist keine gültige UUID
404	CONTENT__PRODUCT_NOT_FOUND	Produkt existiert nicht oder ist nicht sichtbar

Hinweise mehrerer Produkte laden

POST /store-api/gb-notice/list

Request-Body

Feld	Typ	Pflicht	Beschreibung
productIds	UUID[]	✓	Höchstens 100 IDs
includeExpired	bool		Auch abgelaufene Hinweise liefern (Standard false)

Beispiel-Request

{
  "productIds": ["0190a1b2c3d4e5f6a7b8c9d0e1f2a3b4", "0190b2c3d4e5f6a7b8c9d0e1f2a3b4c5"]
}

Beispiel-Antwort

{
  "elements": {
    "0190a1b2c3d4e5f6a7b8c9d0e1f2a3b4": { "text": "Versand nur innerhalb Deutschlands." }
  }
}

hinweis

Produkte ohne gültigen Hinweis fehlen in elements, statt mit null aufzutauchen.

Admin API

Die Entität gb_notice ist über die generische Admin API erreichbar. Es gelten die üblichen Shopware-Routen.

Hinweise suchen

POST /api/search/gb-notice

Nur aktive Hinweise, neueste zuerst

{
  "filter": [{ "type": "equals", "field": "active", "value": true }],
  "sort": [{ "field": "createdAt", "order": "DESC" }],
  "limit": 25
}

Hinweis anlegen

POST /api/gb-notice

Feld	Typ	Pflicht	Beschreibung
text	string (übersetzbar)	✓	Höchstens 255 Zeichen
position	enum		below_price, below_buy_button, description
validFrom	datetime		Beginn der Gültigkeit
validUntil	datetime		Ende der Gültigkeit

Hinweis ändern

PATCH /api/gb-notice/{id}

Nur geänderte Felder senden. Übersetzungen über translations:

{
  "translations": {
    "en-GB": { "text": "Shipping within Germany only." }
  }
}

Hinweis löschen

DELETE /api/gb-notice/{id}

gefahr

Das Löschen entfernt auch alle Zuweisungen zu Produkten und Kategorien. Es gibt keinen Papierkorb.

Events

Event	Wann	Nutzen
GbNoticeLoadedEvent	Nach dem Laden eines Hinweises	Text oder Position anpassen
GbNoticeCriteriaEvent	Vor der Datenbankabfrage	Eigene Filter ergänzen
gb_notice.written	Nach dem Speichern (DAL)	Caches invalidieren

GbNoticeLoadedEvent

public function onNoticeLoaded(GbNoticeLoadedEvent $event): void
{
    $notice = $event->getNotice();
    $notice->setText(mb_strtoupper($notice->getText()));
}

GbNoticeCriteriaEvent

public function onNoticeCriteria(GbNoticeCriteriaEvent $event): void
{
    $event->getCriteria()->addFilter(new EqualsFilter('salesChannelId', $event->getSalesChannelId()));
}

Fehlercodes

Code	HTTP	Beschreibung
GB_NOTICE__INVALID_ID	400	Ungültige UUID
GB_NOTICE__TOO_MANY_IDS	400	Mehr als 100 IDs angefragt
GB_NOTICE__TEXT_TOO_LONG	400	Text länger als 255 Zeichen
GB_NOTICE__NOT_FOUND	404	Hinweis existiert nicht

Kompatibilität

Plugin	Shopware	PHP
1.0	6.6.x	8.2 – 8.3

Siehe auch Datenmodell und Verlinkung.