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

# Използване на API

API позволява вашите собствени системи да четат и променят абонаменти, без никой да отваря приложението, и ви известява всеки път, когато абонамент се промени, така че да не се налага постоянно да питате.

Полезно е, ако имате headless магазин, синхронизирате абонаменти с ERP или складова система или искате съобщение в Slack, когато някой откаже абонамент.

Докато API е ново, го включваме магазин по магазин. Ако **Настройки > Интеграции > API** показва „Свържете се с поддръжката, за да включите API за този магазин“, пишете ни в чата на живо и ние ще го включим за вашия.

## Получаване на токен

Отидете на [**Supr Bundles & Subscriptions > Настройки > Интеграции > API**](https://admin.shopify.com/apps/super-subscriptions/app/settings/integrations/api). В картата **API токени**:

Дайте на токена **Име**, описващо какво ще го използва, така че изтекъл токен да може да бъде проследен, и изберете какво може да прави:

- **Четене на абонаменти**, за система, която само докладва.
- **Промяна на абонаменти**, за система, която поставя на пауза, отказва или пренасрочва.
- **Четене на крайни точки за уебхукове** и **Управление на крайни точки за уебхукове**, за настройване на известия за събития от вашия собствен код, а не от тази страница.

След това кликнете върху **Създаване на токен**.

Дайте на всяка система собствен токен, така че да можете да изключите една, без да засягате останалите.

**Токенът се показва само веднъж.** Копирайте го веднага. Ние не го съхраняваме, така че ако го загубите, ще трябва да създадете нов. **Отнемане** спира веднага всичко, което използва този токен.

## Извикване на API

Изпратете токена като bearer токен:

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

Можете да изброявате абонаменти, да извличате един, а след това да го поставяте на пауза, да го възобновявате, да го отказвате, да пропускате или връщате поръчка, да променяте следващата дата на таксуване или плана, и да добавяте, променяте или премахвате продуктите в него. Всяка промяна връща абонамента такъв, какъвто е сега, така че никога не се налага да питате отново веднага след това.

API е предназначено да се извиква от вашите собствени сървъри. Не слагайте токен в браузър, мобилно приложение или друго, което клиент може да види, защото всеки, който го намери, може да променя абонаментите ви.

### Безопасно повторение на заявки

Ако извикването изтече по време, не можете да разберете дали е станало. Изпратете заглавие `Idempotency-Key` със своя стойност при всичко, което променя абонамент, и ако повторите със същия ключ, ние връщаме първия отговор, вместо да го изпълним два пъти:

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

Ключовете важат един ден. Повторната употреба на ключ с друга заявка се отхвърля, вместо да се отговаря, така че не можете случайно да получите грешен отговор.

### Колко извиквания получавате

Всеки магазин започва със стандартния лимит, показан в списъка **Лимит на заявките**, когато създавате токен. Ако интеграцията ви има нужда от повече, поискайте от нас и ще го увеличим, а по-високите възможности ще се появят в този списък.

Всеки отговор носи `X-RateLimit-Limit`, `X-RateLimit-Remaining` и `X-RateLimit-Reset`. При превишаване получавате `429` с `Retry-After`, който показва колко секунди да изчакате.

Има и общ лимит за всички токени на магазина ви заедно, защото всяко извикване изразходва и лимита на вашия магазин в Shopify. Ако една интеграция се побърка, този лимит спира забавянето на администрацията и витрината ви.

## Известия за събития

Вместо да ни питате за промени, накарайте ни да ви казваме. В **Supr Bundles & Subscriptions > Настройки > Интеграции > API**, в картата **Известия за събития**, въведете **URL**, отметнете събитията, които искате, и кликнете върху **Добавяне на крайна точка**. Изпращаме POST към нея, когато се случи събитие, а тялото съдържа абонамента точно както би го върнало API.

Наличните събития включват създаване, пауза, възобновяване, отказване, подновяване или неуспех на абонамент, промяна на следващата му дата на таксуване, пропускане или връщане на поръчка, промяна на продуктите или плана му и актуализиране на начина на плащане или адреса за доставка.

URL адресът ви трябва да използва https и да е достъпен от интернет.

### Проверка, че известието наистина идва от нас

Когато добавите крайна точка, ви показваме таен ключ за подписване, веднъж. Всяко изпращане носи тези заглавия:

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

Подписът е base64 HMAC SHA256 на времевия печат, точка и точното тяло, което сме изпратили, с вашия таен ключ. Проверете го, преди да се доверите на каквото и да било:

```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` е целият низ, който ви показахме, започващ с `sss_whsec_`. Използвайте го както е, включително този префикс.

Използвайте суровото тяло точно както е пристигнало, а не прекодирана версия на разчетения JSON, иначе подписът няма да съвпадне.

Отхвърляйте и всичко, чийто времеви печат е по-стар от пет минути. Времевият печат е част от подписаното, така че именно това спира някой да повтори изпращане, което е прихванал по-рано.

Можете да смените тайния ключ на крайна точка по всяко време с **Нов таен ключ** на същата страница. Това променя само тази крайна точка. **Изключване** спира изпращанията към крайна точка, а **Премахване** я изтрива.

### Когато крайната ви точка не работи

Неуспешно изпращане се повтаря със засилващи се интервали около един ден, преди да се откажем. Ако крайна точка откаже 20 пъти поред, я изключваме и ви показваме защо, така че изведен от употреба URL да не се повтаря вечно. Кликването върху **Включване** изчиства това.

## Получаване на помощ

Ако нещо не се държи както трябва, всеки отговор носи `X-Request-Id`. Посочете го на поддръжката и ще намерим точно това извикване.

## Често задавани въпроси

- **Има ли API за абонаменти?**
  Да, това. Включва се магазин по магазин, докато е ново, затова се свържете с поддръжката, за да го включим.
- **Нужно ли ми е API, за да променя много абонаменти наведнъж, например да преместя датите им на подновяване?**
  Не за еднократна промяна. В **Абонаменти** филтрирайте списъка, отметнете абонаментите и използвайте груповото действие **Пренасрочване**. API е за промени, които вашите системи правят редовно.
- **Може ли друго приложение (например за партньори или ERP) да чете данните за абонаментите?**
  Shopify позволява само на приложението, създало абонамента, да го чете, затова други приложения не могат да виждат нашите абонаменти директно. Или свържете вашата система с това API, или оставете другото приложение да чете таговете на поръчките и клиентите, които приложението може да добави, вижте [Настройки на таговете](https://supr-bundles-and-subscriptions.crisp.help/bg/article/tag-settings-wc4onz/).
- **Загубих токена си.**
  Не можем да го покажем отново. **Отнемете** стария и създайте нов токен.
- **Мога ли да сложа токена в темата на витрината или в мобилно приложение?**
  Не. Всеки, който го види, би могъл да променя абонаментите ви. Извиквайте API само от собствения си сървър.