> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://supr-bundles-and-subscriptions.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Die API verwenden

Mit der API können deine eigenen Systeme Abonnements lesen und ändern, ohne dass jemand die App öffnen muss. Außerdem informiert sie dich, sobald sich ein Abonnement ändert, sodass du nicht ständig nachfragen musst.

Sie ist nützlich, wenn du einen Headless-Shop betreibst, Abonnements mit einem ERP- oder Lagerverwaltungssystem synchronisierst oder eine Nachricht in Slack erhalten möchtest, wenn jemand kündigt.

Solange die API neu ist, schalten wir sie Shop für Shop frei. Wenn unter **Einstellungen > Integrationen > API** „Kontaktiere den Support, um die API für diesen Shop freizuschalten.“ steht, schreib uns im Live-Chat, und wir schalten sie für deinen Shop frei.

## Ein Token erhalten

Gehe zu [**Supr Bundles & Subscriptions > Einstellungen > Integrationen > API**](https://admin.shopify.com/apps/super-subscriptions/app/settings/integrations/api). In der Karte **API-Tokens**:

Gib dem Token einen **Namen**, der beschreibt, was es verwenden wird, damit sich ein geleaktes Token zurückverfolgen lässt, und wähle, was es tun darf:

- **Abonnements lesen** für ein System, das nur auswertet.
- **Abonnements ändern** für eines, das pausiert, kündigt oder verschiebt.
- **Webhook-Endpunkte lesen** und **Webhook-Endpunkte verwalten**, um Ereignisbenachrichtigungen aus deinem eigenen Code einzurichten statt über diese Seite.

Klicke dann auf **Token erstellen**.

Gib jedem System ein eigenes Token, damit du eines abschalten kannst, ohne die anderen anzufassen.

**Das Token wird nur einmal angezeigt.** Kopiere es sofort. Wir speichern es nicht. Wenn du es verlierst, musst du ein neues erstellen. **Widerrufen** stoppt sofort alles, was dieses Token verwendet.

## Die API aufrufen

Sende das Token als Bearer-Token:

```
curl https://subscriptions.super-simple.co/api/v1/subscriptions \
  -H "Authorization: Bearer sss_live_..."
```

Du kannst Abonnements auflisten, ein einzelnes abrufen und dann eine Bestellung pausieren, fortsetzen, kündigen, überspringen oder das Überspringen aufheben, das nächste Abrechnungsdatum oder den Plan ändern und die Produkte darin hinzufügen, ändern oder entfernen. Jede Änderung antwortet mit dem Abonnement in seinem aktuellen Zustand, sodass du direkt danach nie erneut nachfragen musst.

Die API ist für Aufrufe von deinen eigenen Servern gedacht. Lege ein Token niemals in einen Browser, eine mobile App oder irgendetwas anderes, das ein Kunde sehen kann, denn jeder, der es findet, kann deine Abonnements ändern.

### Sicher wiederholen

Wenn bei einem Aufruf eine Zeitüberschreitung auftritt, weißt du nicht, ob er ausgeführt wurde. Sende bei allem, was ein Abonnement ändert, einen `Idempotency-Key`-Header mit einem eigenen Wert. Wiederholst du den Aufruf mit demselben Schlüssel, geben wir die erste Antwort zurück, statt die Aktion zweimal auszuführen:

```
curl -X POST https://subscriptions.super-simple.co/api/v1/subscriptions/123/pause \
  -H "Authorization: Bearer sss_live_..." \
  -H "Idempotency-Key: 9f1c2a7e-4b0d-4f2a-9c3e-8a1b2c3d4e5f"
```

Schlüssel gelten einen Tag. Wird einer mit einer anderen Anfrage wiederverwendet, lehnen wir sie ab, statt zu antworten, sodass du nicht versehentlich die falsche Antwort erhältst.

### Wie viele Aufrufe du hast

Jeder Shop startet mit dem Standardkontingent, das beim Erstellen eines Tokens in der Liste **Ratenlimit** angezeigt wird. Wenn deine Integration mehr braucht, frag uns, und wir erhöhen es. Die höheren Optionen erscheinen dann in dieser Liste.

Jede Antwort enthält `X-RateLimit-Limit`, `X-RateLimit-Remaining` und `X-RateLimit-Reset`. Wer darüber liegt, erhält eine `429` mit einem `Retry-After`, der angibt, wie viele Sekunden du warten musst.

Außerdem gibt es ein Limit für alle Tokens deines Shops zusammen, weil jeder Aufruf auch das Shopify-Kontingent deines Shops verbraucht. Wenn eine Integration aus dem Ruder läuft, verhindert dieses Limit, dass sie deinen Adminbereich und deinen Onlineshop verlangsamt.

## Ereignisbenachrichtigungen

Statt uns nach Änderungen zu fragen, lass dich von uns informieren. Gib in **Supr Bundles & Subscriptions > Einstellungen > Integrationen > API** in der Karte **Ereignisbenachrichtigungen** eine **URL** ein, hake die gewünschten Ereignisse an und klicke auf **Endpunkt hinzufügen**. Wir senden einen POST an diese URL, sobald eines davon eintritt, und der Inhalt enthält das Abonnement genau so, wie die API es zurückgeben würde.

Zu den verfügbaren Ereignissen gehören: ein Abonnement wird erstellt, pausiert, fortgesetzt, gekündigt, verlängert oder schlägt fehl, sein nächstes Abrechnungsdatum ändert sich, eine Bestellung wird übersprungen oder das Überspringen aufgehoben, seine Produkte oder sein Plan ändern sich, und seine Zahlungsmethode oder Lieferadresse wird aktualisiert.

Deine URL muss https verwenden und aus dem Internet erreichbar sein.

### Prüfen, ob eine Benachrichtigung wirklich von uns stammt

Wenn du einen Endpunkt hinzufügst, zeigen wir dir einmalig ein Signatur-Secret. Jede Zustellung enthält diese Header:

```
X-SSS-Topic: subscription.paused
X-SSS-Shop-Domain: your-store.myshopify.com
X-SSS-Timestamp: 1758300000
X-SSS-Hmac-SHA256: <signature>
```

Die Signatur ist der base64-kodierte HMAC SHA256 aus dem Zeitstempel, einem Punkt und dem exakten Inhalt, den wir gesendet haben, mit deinem Secret. Prüfe sie, bevor du irgendetwas vertraust:

```js
const crypto = require("crypto");

const expected = crypto
  .createHmac("sha256", YOUR_SECRET)
  .update(`${req.headers["x-sss-timestamp"]}.${rawBody}`)
  .digest("base64");

const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-sss-hmac-sha256"])
);
```

`YOUR_SECRET` ist die gesamte Zeichenfolge, die wir dir gezeigt haben, beginnend mit `sss_whsec_`. Verwende sie unverändert, einschließlich dieses Präfixes.

Verwende den Rohinhalt genau so, wie er angekommen ist, nicht eine neu kodierte Version des geparsten JSON, sonst stimmt die Signatur nicht überein.

Lehne außerdem alles ab, dessen Zeitstempel älter als fünf Minuten ist. Der Zeitstempel ist Teil der Signatur. Das verhindert, dass jemand eine früher abgefangene Zustellung erneut abspielt.

Du kannst das Secret eines Endpunkts jederzeit mit **Neues Secret** auf derselben Seite erneuern. Das ändert nur diesen Endpunkt. **Ausschalten** pausiert die Zustellungen an einen Endpunkt, und **Entfernen** löscht ihn.

### Wenn dein Endpunkt nicht erreichbar ist

Eine fehlgeschlagene Zustellung wird mit wachsenden Abständen etwa einen Tag lang wiederholt, bevor wir aufgeben. Lehnt ein Endpunkt 20 Mal in Folge ab, schalten wir ihn aus und zeigen dir den Grund, damit eine URL, die du nicht mehr verwendest, nicht endlos weiter angesprochen wird. Ein Klick auf **Einschalten** hebt das auf.

## Hilfe erhalten

Wenn etwas nicht wie erwartet funktioniert: Jede Antwort enthält eine `X-Request-Id`. Nenne sie dem Support, dann finden wir genau diesen Aufruf.

## Häufige Fragen

- **Gibt es eine API für Abonnements?**
  Ja, diese hier. Solange sie neu ist, wird sie Shop für Shop freigeschaltet. Wende dich also an den Support, um sie aktivieren zu lassen.
- **Brauche ich die API, um viele Abonnements auf einmal zu ändern, zum Beispiel ihre Verlängerungsdaten zu verschieben?**
  Nicht für eine einmalige Änderung. Filtere unter **Abonnements** die Liste, hake die Abonnements an und verwende die Massenaktion **Verschieben**. Die API ist für Änderungen gedacht, die deine eigenen Systeme regelmäßig vornehmen.
- **Kann eine andere App (zum Beispiel eine Affiliate- oder ERP-App) Abonnementdaten lesen?**
  Shopify erlaubt nur der App, die ein Abonnement erstellt hat, es zu lesen. Andere Apps können unsere Abonnements also nicht direkt sehen. Verbinde entweder dein System mit dieser API oder lass die andere App die Bestellungs- und Kunden-Tags lesen, die die App hinzufügen kann, siehe [Tag-Einstellungen](https://supr-bundles-and-subscriptions.crisp.help/de/article/tag-settings-1afx3g9/).
- **Ich habe mein Token verloren.**
  Wir können es nicht erneut anzeigen. **Widerrufe** das alte und erstelle ein neues Token.
- **Kann ich das Token in mein Onlineshop-Theme oder eine mobile App einbauen?**
  Nein. Jeder, der es sehen kann, könnte deine Abonnements ändern. Rufe die API nur von deinem eigenen Server aus auf.