> ## 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).

# De API gebruiken

Met de API kunnen je eigen systemen abonnementen lezen en wijzigen zonder dat iemand de app opent, en krijg je een melding zodra een abonnement verandert, zodat je niet steeds hoeft te vragen of er iets is gewijzigd.

Het is handig als je een headless webwinkel hebt, abonnementen synchroniseert met een ERP- of magazijnsysteem, of een bericht in Slack wilt als iemand opzegt.

Zolang de API nieuw is, zetten we hem winkel voor winkel aan. Staat er bij **Instellingen > Integraties > API** "Neem contact op met support om de API voor deze winkel te laten inschakelen", stuur ons dan een bericht in de livechat, dan zetten we hem voor jou aan.

## Een token ophalen

Ga naar [**Supr Bundles & Subscriptions > Instellingen > Integraties > API**](https://admin.shopify.com/apps/super-subscriptions/app/settings/integrations/api). In de kaart **API-tokens**:

Geef het token een **Naam** die beschrijft wat het gaat gebruiken, zodat een uitgelekt token kan worden herleid, en kies wat het mag doen:

- **Abonnementen lezen**, voor een systeem dat alleen rapporteert.
- **Abonnementen wijzigen**, voor een systeem dat abonnementen pauzeert, opzegt of opnieuw inplant.
- **Webhook-endpoints lezen** en **Webhook-endpoints beheren**, om gebeurtenismeldingen vanuit je eigen code in te stellen in plaats van op deze pagina.

Klik daarna op **Token maken**.

Geef elk systeem een eigen token, zodat je er één kunt uitzetten zonder de rest te raken.

**Het token wordt maar één keer getoond.** Kopieer het meteen. We slaan het niet op, dus als je het kwijtraakt, moet je een nieuw token maken. Met **Intrekken** stopt alles wat dat token gebruikt onmiddellijk.

## De API aanroepen

Stuur het token mee als bearer-token:

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

Je kunt abonnementen weergeven en één opvragen, en daarna pauzeren, hervatten, opzeggen, een bestelling overslaan of weer terugzetten, de volgende factuurdatum of het abonnement wijzigen, en de producten erin toevoegen, wijzigen of verwijderen. Elke wijziging antwoordt met het abonnement zoals het er nu uitziet, zodat je er daarna niet nogmaals naar hoeft te vragen.

De API is bedoeld om door je eigen servers te worden aangeroepen. Zet een token nooit in een browser, een mobiele app of iets anders wat een klant kan zien, want iedereen die het vindt, kan je abonnementen wijzigen.

### Veilig opnieuw proberen

Als een aanroep een time-out krijgt, kun je niet zien of hij is uitgevoerd. Stuur bij alles wat een abonnement wijzigt een `Idempotency-Key`-header mee met een eigen waarde. Als je het opnieuw probeert met dezelfde sleutel, geven we het eerste antwoord terug in plaats van het twee keer uit te voeren:

```
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"
```

Sleutels gelden een dag. Een sleutel hergebruiken met een ander verzoek wordt geweigerd in plaats van beantwoord, zodat je nooit per ongeluk het verkeerde antwoord krijgt.

### Hoeveel aanroepen je krijgt

Elke winkel begint met het standaardlimiet, dat je ziet in de lijst **Limiet** wanneer je een token maakt. Heeft je integratie meer nodig, vraag het ons dan, dan verhogen we het en verschijnen de hogere opties in die lijst.

Elk antwoord bevat `X-RateLimit-Limit`, `X-RateLimit-Remaining` en `X-RateLimit-Reset`. Als je over het limiet gaat, krijg je een `429` met een `Retry-After` die aangeeft hoeveel seconden je moet wachten.

Daarnaast is er een limiet voor alle tokens van je winkel samen, omdat elke aanroep ook van het Shopify-tegoed van je winkel gebruikmaakt. Als één integratie fout gaat, voorkomt dat limiet dat je beheeromgeving en webwinkel trager worden.

## Gebeurtenismeldingen

In plaats van ons naar wijzigingen te vragen, kun je ze ook door ons laten melden. Voer in **Supr Bundles & Subscriptions > Instellingen > Integraties > API**, in de kaart **Gebeurtenismeldingen**, een **URL** in, vink de gewenste gebeurtenissen aan en klik op **Endpoint toevoegen**. We sturen een POST-verzoek naar die URL zodra er een gebeurtenis plaatsvindt, en de body bevat het abonnement precies zoals de API het zou teruggeven.

Beschikbare gebeurtenissen zijn onder meer dat een abonnement wordt gemaakt, gepauzeerd, hervat, opgezegd, verlengd of mislukt, dat de volgende factuurdatum verandert, dat een bestelling wordt overgeslagen of weer teruggezet, dat de producten of het abonnement veranderen, en dat de betaalmethode of het verzendadres wordt bijgewerkt.

Je URL moet https gebruiken en bereikbaar zijn vanaf internet.

### Controleren of een melding echt van ons komt

Wanneer je een endpoint toevoegt, tonen we je eenmalig een ondertekeningsgeheim. Elke levering bevat deze headers:

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

De handtekening is de base64-HMAC-SHA256 van het tijdstempel, een punt en de exacte body die we hebben verstuurd, met jouw geheim als sleutel. Controleer hem voordat je iets vertrouwt:

```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` is de volledige tekenreeks die we je hebben getoond, beginnend met `sss_whsec_`. Gebruik hem zoals hij is, inclusief dat voorvoegsel.

Gebruik de ruwe body precies zoals die is binnengekomen, niet een opnieuw gecodeerde versie van de geparseerde JSON, anders klopt de handtekening niet.

Weiger ook alles waarvan het tijdstempel meer dan vijf minuten oud is. Het tijdstempel maakt deel uit van wat is ondertekend, en daarmee voorkom je dat iemand een eerder onderschepte levering opnieuw afspeelt.

Je kunt het geheim van een endpoint op elk moment vernieuwen met **Nieuw geheim** op dezelfde pagina. Dat wijzigt alleen dat endpoint. Met **Uitzetten** pauzeer je de leveringen aan een endpoint en met **Verwijderen** verwijder je het.

### Als je endpoint niet bereikbaar is

Een mislukte levering wordt ongeveer een dag lang opnieuw geprobeerd met steeds grotere tussenpozen voordat we het opgeven. Als een endpoint 20 keer achter elkaar weigert, zetten we het uit en laten we je zien waarom, zodat een URL die je niet meer gebruikt niet eindeloos wordt geprobeerd. Met **Aanzetten** wis je dat.

## Hulp krijgen

Als er iets niet werkt zoals verwacht, bevat elk antwoord een `X-Request-Id`. Geef die door aan support, dan kunnen we precies die aanroep terugvinden.

## Veelgestelde vragen

- **Is er een API voor abonnementen?**
  Ja, deze. Zolang hij nieuw is, zetten we hem winkel voor winkel aan, dus neem contact op met support om hem aan te zetten.
- **Heb ik de API nodig om veel abonnementen tegelijk te wijzigen, bijvoorbeeld hun verlengingsdatums te verplaatsen?**
  Niet voor een eenmalige wijziging. Filter in **Abonnementen** de lijst, vink de abonnementen aan en gebruik de bulkactie **Opnieuw plannen**. De API is voor wijzigingen die je eigen systemen regelmatig doorvoeren.
- **Kan een andere app (bijvoorbeeld een affiliate- of ERP-app) abonnementsgegevens lezen?**
  Shopify laat alleen de app die een abonnement heeft gemaakt het lezen, dus andere apps kunnen onze abonnementen niet rechtstreeks zien. Koppel je systeem aan deze API, of laat de andere app de bestel- en klanttags lezen die de app kan toevoegen, zie [Tag-instellingen](https://supr-bundles-and-subscriptions.crisp.help/nl/article/tag-settings-vaqpe4/).
- **Ik ben mijn token kwijt.**
  We kunnen het niet opnieuw tonen. Trek het oude token in met **Intrekken** en maak een nieuw token.
- **Kan ik het token in mijn webwinkelthema of een mobiele app zetten?**
  Nee. Iedereen die het kan zien, kan je abonnementen wijzigen. Roep de API alleen aan vanaf je eigen server.