Authentifizierung

Alle Anfragen an die Umbrella API erfordern eine Authentifizierung. Je nach Endpunkt gibt es zwei Methoden.

Authentifizierung per Shopify-Header

Öffentliche Endpunkte (Widget-Daten, Ansprüche, Abfragen von Policen) authentifizieren sich über Header mit der Shopify-Shop-Domain:

X-Shopify-Shop-Domain: your-store.myshopify.com
X-Shopify-Customer-Id: 1234567890

Wenn Sie die Umbrella-App für Shopify installieren, wird Ihre Shop-Domain automatisch registriert. Für Storefront-Endpunkte ist keine manuelle Einrichtung nötig.

Authentifizierung per internem API-Schlüssel

Serverseitige Endpunkte (Berechtigungsprüfung, Produktsynchronisierung) authentifizieren sich mit einem API-Schlüssel im Request-Body:

{
  "internalApiKey": "your-internal-api-key",
  "orgId": "your-org-id"
}

So erzeugen oder rotieren Sie einen internen API-Schlüssel:

1. Gehen Sie zu Dashboard > Einstellungen > Integrationen
2. Suchen Sie den Bereich „API-Schlüssel“
3. Klicken Sie auf Neuen Schlüssel erzeugen oder Schlüssel rotieren

Beim Rotieren wird der bisherige Schlüssel sofort ungültig. Aktualisieren Sie alle Integrationen, bevor Sie rotieren.

Test- und Live-Umgebung

Anfragen im Testmodus liefern in der Antwort "testingMode": true und verwenden Beispiel-Garantiedaten.

Fehlerbehandlung

Häufige Fehlerstatuscodes aller Endpunkte:

Erhalten Sie eine 429-Antwort, warten Sie die Wartezeit ab, bevor Sie weitere Anfragen senden. Implementieren Sie bei hohem Anfragevolumen einen exponentiellen Backoff.

Verwandte Themen

• Endpunkte im Überblick — Vollständige Liste der verfügbaren Endpunkte
• Warranty API — Endpunkte zur Verwaltung von Garantieplänen
• Webhook-Referenz — Ereignisgesteuerte Integrationen