API für Entwickler

Diese Seite richtet sich an Entwickler, die ein anderes System an die Garantiedaten anbinden. Wie der Shopbetreiber die Zugangsdaten anlegt, steht unter Anbindung an andere Systeme.

Anmeldung

Die Anmeldung erfolgt wie bei jeder Shopware-Integration mit der Zugangs-ID und dem Sicherheitsschlüssel:

POST /api/oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "<Zugangs-ID>",
  "client_secret": "<Sicherheitsschlüssel>"
}

Das erhaltene access_token sendest du bei jeder Anfrage als Authorization: Bearer <token>. Mit Accept: application/json erhältst du einfaches JSON.

Endpunkte

Garantie lesen

GET /api/_action/iwv-eu-guarantee/product-configuration?productNumber=LU-20040

Die Antwort enthält drei Teile:

• stored: die Werte, die direkt am Produkt gespeichert sind. Ist leer (null), wenn das Produkt keine eigenen Werte hat.
• resolved: die Garantie, die tatsächlich gilt, nach Vererbung vom Hauptprodukt, einer EU-Label-Regel oder dem Hersteller. sourceLevel nennt die Herkunft: product, parent, label, manufacturer oder none.
• eligibility: der Status für das GARAN-Label, zum Beispiel eligible oder not_eligible, mit den Gründen unter blockingViolations.

Lies für die Frage “Welche Garantie gilt?” immer resolved, nicht stored. Ein Produkt mit stored: null kann trotzdem eine gültige Garantie haben.

Garantie ändern

POST /api/_action/iwv-eu-guarantee/product-configuration
{
  "productNumber": "LU-20040",
  "values": {
    "producerGuaranteeConfirmed": true,
    "informationSuppliedToSeller": true
  }
}

Hat das Produkt noch keine Garantie, wird sie angelegt. Die Antwort hat dasselbe Format wie beim Lesen, ergänzt um created und die geschriebenen fields. Der Status für das Label ist darin bereits neu berechnet.

Viele Produkte ändern

POST /api/_action/iwv-eu-guarantee/bulk-apply
{
  "productIds": ["<uuid>", "<uuid>"],
  "values": { "durationMonths": 36, "producerBrand": "Nordwerk" }
}

Hier werden Produkt-IDs statt Produktnummern erwartet, höchstens 500 je Anfrage. Die Antwort enthält die Anzahl der geänderten und neu angelegten Einträge und den neuen Status je Produkt.

Wichtige Regeln

• Nur gesendete Felder werden geändert. Ein Feld, das nicht in der Anfrage steht, behält seinen Wert. Ein Feld mit dem Wert null wird geleert. Sende deshalb nur die Felder, die dein System pflegt.
• Pflichtfelder lassen sich nicht leeren. configurationMode, active und suppressStatutoryNotice mit null führen zu Fehler 400.
• Unbekannte Produktnummer: Fehler 400 “No product matches the given productId or productNumber.”
• Fehlende Berechtigung: Fehler 403 mit dem fehlenden Recht in missingPrivileges.

Schreibbare Felder

Headless-Shops (Store API)

Für eigene Frontends liefert eine Store-API-Route die Garantieangaben, die Label-Daten und den gesetzlichen Hinweis in der Sprache des Verkaufskanals:

POST /store-api/iwv-eu-guarantee/product
sw-access-key: <Zugangsschlüssel des Verkaufskanals>
{ "productIds": ["<uuid>"], "view": "product" }

Der gesetzliche Hinweis ist in der Antwort immer enthalten, außer du schaltest ihn ausdrücklich ab.