# API подписок: тарифы, доступ и лимиты для вашего SaaS

Как описать тарифы в кабинете и проверять доступ, пробные периоды и расход лимитов через /v2/subscriptions с ключом xsub_….

## Зачем нужны подписки в xpayment

Если у вас SaaS, приложение, клуб или школа и пользователи платят за доступ по тарифам, вам нужно хранить три вещи: **что входит в каждый тариф**, **до какого числа оплачено** и **сколько лимита уже израсходовано**. Раздел «Подписки» берёт это на себя. Вы описываете тарифы в кабинете, а ваш сервис через API спрашивает: «что доступно этому пользователю?».

xpayment ведёт:

- **каталог**: возможности (флаги доступа), лимиты (счётчики), планы, собранные из блоков, и дополнения;
- **аккаунты**: пользователей или компаний вашего продукта и их подписки;
- **сроки и пробные периоды**: статус считается по датам Казахстана;
- **оплату**: автосчёт Kaspi, «оплачено вне системы» или выдача без оплаты;
- **расход лимитов**: ваш сервис присылает инкременты, а xpayment не даёт превысить конечный лимит.

Это не то же самое, что платёж через API: платёж принимает деньги один раз, а подписка отвечает на вопрос «есть ли у пользователя доступ сейчас». Одно с другим связано: счёт за подписку — это обычный удалённый платёж Kaspi.

## Как это устроено

```text
Кабинет «Подписки»        Ваш сервис                       xpayment
 планы, лимиты    <--->   PUT  /v2/subscriptions/accounts/{id}   (создать пользователя)
 выдача, оплата           GET  .../{id}/check?capability=...     (есть ли доступ?)
                          POST .../{id}/usage                    (учесть расход)
```

Для этого API у вас **свой ключ**: `xsub_…`. Он выдаётся вместе с проектом подписок и работает только на `/v2/subscriptions`. Ключи платежей `xapi_…` и ключи подписок `xsub_…` не взаимозаменяемы: ключ одного вида на эндпоинтах другого даёт `401`.

> Подписки сейчас в бете. Условия и поля могут уточняться; актуальный справочник — в [документации](https://xpayment.kz/docs#section-v2).

## Настройка в кабинете

### 1. Проект и ключ

Откройте **«Подписки»** и создайте проект («Новый проект»). Вместе с ним создаётся ключ `xsub_…`: он показывается один раз, потом виден только префикс. Храните ключ на сервере, как и ключ `xapi_…`.

Ключ можно **ротировать**: новый ключ начинает работать сразу, а старый продолжает действовать ещё 24 часа, чтобы вы успели обновить сервис. Завершить старый ключ раньше срока можно в настройках проекта.

### 2. Каталог

На вкладках кабинета вы описываете, что продаёте:

| Что | Для чего | Пример |
|---|---|---|
| **Возможность** | Флаг доступа | `catalog` — «Каталог товаров» |
| **Лимит** | Счётчик с единицей и периодом сброса (нет, день, месяц) | `orders_m` — «Заказы» в месяц |
| **План** | Набор возможностей и лимитов, собирается из блоков (групп) | «Старт» в блоке «Каталог» |
| **Дополнение** | Что можно докупить к плану | `seat_extra` — «Дополнительный сотрудник» |

У каждой сущности есть **код**, по которому ваш сервис обращается к ней в API, поэтому выбирайте короткие и стабильные коды. План бывает в статусах «черновик», «активный» и «в архиве»; в состав подписки попадают только активные планы.

### 3. Аккаунты и выдача подписок

Аккаунт — это пользователь или компания вашего продукта. Подписку аккаунту можно:

- **выдать из кабинета** («Выдать подписку»): оплаченную вне системы, вручную или как пробную;
- **создать через API**: ваш сервис сам заводит аккаунт и, при необходимости, запускает пробный период;
- **изменить, отменить и возобновить**: отменённая подписка работает до конца оплаченного периода;
- **продлить вручную** или отметить **«Оплачено вне системы»**, если деньги пришли не через xpayment.

Вкладки кабинета показывают обзор, список подписок и аккаунтов, платежи, пробные периоды, расход лимитов и аналитику.

### 4. Касса и оплата

Подписки оплачиваются счётом Kaspi, который выставляется на телефон аккаунта с **кассы проекта**. Для этого у аккаунта должен быть указан телефон (иначе API ответит `409 PHONE_REQUIRED`), а в проекте выбрана касса: [Подключение кассы и ключ API v2](https://xpayment.kz/blog/device-setup).

Как работает автосчёт: за несколько дней до конца периода xpayment выставляет счёт Kaspi и повторяет попытки, пока он не оплачен; оплата продлевает период. Если касса сломана или не выбрана, счёт не уходит, пока вы не исправите её. Деньги идут напрямую на ваш счёт в Kaspi.

## API для вашего сервиса

База: `https://api.xpayment.kz/v2/subscriptions`. Заголовок: `Authorization: Bearer xsub_…`. Ответы приходят с заголовком `Cache-Control: no-store`. Тексты ошибок в этом API английские.

| Метод | Путь | Что делает |
|---|---|---|
| `PUT` | `/accounts/{externalID}` | Создать или обновить аккаунт |
| `GET` | `/accounts/{externalID}` | Права аккаунта (`entitlements`) |
| `GET` | `/accounts/{externalID}/check` | Проверить одну возможность или лимит |
| `POST` | `/accounts/{externalID}/trial` | Запустить пробный период |
| `POST` | `/accounts/{externalID}/usage` | Учесть расход лимита |

`externalID` — ваш идентификатор пользователя: 1–100 символов из `A–Z a–z 0–9 . _ : @ + -`. В адресе его нужно URL-кодировать (`user@mail.kz` → `user%40mail.kz`).

### Создать аккаунт

```bash
curl -X PUT "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kazmart.kz", "phone": "+7 701 200 10 30", "email": "admin@kazmart.kz"}'
```

Все поля необязательны: отсутствующее поле не меняется, `null` очищает его. Телефон приводится к виду `+7XXXXXXXXXX`. Ответ `201` (создан) или `200` (обновлён) содержит права аккаунта.

### Права аккаунта

`GET /accounts/{externalID}` возвращает:

```json
{
  "external_id": "shop_1040",
  "name": "Kazmart.kz",
  "status": "active",
  "access": true,
  "until": "2026-12-01",
  "access_ends_at": "2026-12-01T19:00:00Z",
  "period": "month",
  "plans": [{"code": "cat_start", "name": "Старт", "block": "Каталог"}],
  "capabilities": [
    {"code": "catalog", "name": "Каталог товаров",
     "source": {"type": "plan", "code": "cat_start", "name": "Старт", "block": "Каталог"}}
  ],
  "limits": [
    {"limit": "orders_m", "name": "Заказы", "limit_value": 300, "unlimited": false,
     "used": 121, "remaining": 179, "resets_at": "2026-11-30T19:00:00Z"}
  ]
}
```

`status`: `none` (нет подписки), `trial`, `active`, `canceling` (отменена, доступ до конца периода), `expired`. Поля `capabilities` и `limits` заполнены только при `access: true`. Ответ можно кэшировать **не дольше минуты**: изменения из кабинета видны со следующего запроса.

### Проверка доступа

Для одной проверки удобнее `check`: укажите ровно одно из `capability` или `limit`.

```bash
# есть ли возможность
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?capability=catalog" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ"

# хватит ли лимита на 5 единиц
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?limit=orders_m&need=5" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ"
```

Ответ всегда `200` (даже для неизвестного аккаунта): `{"allowed": true, "reason": null, "status": "active", ...}`. Если `allowed: false`, `reason` объясняет, почему:

| `reason` | Значение |
|---|---|
| `account_not_found` | Такого аккаунта нет |
| `no_subscription` | У аккаунта нет подписки |
| `expired` | Срок вышел |
| `not_in_plan` | Возможности нет в планах аккаунта |
| `limit_not_set` | В планах нет такого лимита |
| `limit_exhausted` | Остаток меньше `need` |

Неизвестный код возможности или лимита даёт `404 UNKNOWN_CODE`.

### Пробный период

```bash
curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/trial" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"plans": ["cat_start"], "addons": [], "period": "month"}'
```

Аккаунт должен существовать (сначала `PUT`) и не иметь доступа. Пробный период длится столько, сколько самый длинный пробный период выбранных планов, а `period` (`month` или `year`) задаёт период после него. Ответ `201` содержит права. Типичные ошибки: `404 ACCOUNT_NOT_FOUND`, `409 TRIAL_NOT_ALLOWED` (уже есть доступ), `409 TRIAL_ALREADY_USED`, `409 NO_TRIAL` (ни у одного плана нет пробного периода).

### Учёт расхода

```bash
curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/usage" \
  -H "Authorization: Bearer xsub_ВАШ_КЛЮЧ" \
  -H "X-Idempotency-Key: order-8812-created" \
  -H "Content-Type: application/json" \
  -d '{"limit": "orders_m", "delta": 1}'
```

Правила:

- **`X-Idempotency-Key` обязателен** (1–100 видимых ASCII-символов). Повтор с тем же ключом и телом вернёт сохранённый ответ и ничего не посчитает; тот же ключ с другим телом даёт `422 IDEMPOTENCY_KEY_REUSED`.
- `delta` — ненулевое целое в пределах ±10⁹. Отрицательное значение (например, пользователь удалил товар) уменьшает счётчик, но не ниже нуля, и принимается даже без доступа.
- Положительное значение требует доступа (`409 NO_ACCESS`). Если оно превысит **конечный** лимит, запрос отклоняется целиком: `409 LIMIT_EXCEEDED` с текущими значениями, ничего не засчитано.
- Успех: `200` с полями `limit`, `used`, `limit_value`, `unlimited`, `remaining`, `resets_at`.
- Сохраняются только ответы `200` и `409`; при `400`, `404`, `422`, `429` и `500` ключ не запоминается, и повтор выполнится заново.

Лимиты сбрасываются по календарю Казахстана: раз в день, раз в месяц или не сбрасываются.

### Общие ошибки и лимиты запросов

| HTTP | Код | Причина |
|---|---|---|
| 401 | `UNAUTHORIZED` | Нет заголовка, ключ неверный или отозван, либо это не `xsub_` |
| 429 | `RATE_LIMITED` | Слишком много запросов; смотрите заголовок `Retry-After` |
| 500 | `INTERNAL_ERROR` | Непредвиденная ошибка |

Исходящих вебхуков у подписок нет: ваш сервис сам опрашивает `GET /accounts/{id}` или `check` в нужный момент.

## Типичная схема внедрения

1. **Опишите тарифы** в кабинете: возможности, лимиты, планы и дополнения. Выберите короткие стабильные коды.
2. **Заведите аккаунт при регистрации пользователя**: `PUT /accounts/{id}` с именем, телефоном и email.
3. **Запустите пробный период**, если он есть: `POST …/trial` с кодами планов.
4. **Проверяйте доступ** там, где он важен: `check?capability=…` перед действием или `GET /accounts/{id}`, если нужны все права разом. Кэшируйте ответ не дольше минуты.
5. **Учитывайте расход**: `POST …/usage` с `X-Idempotency-Key`, например, `order-8812-created`. Так повтор из-за таймаута не посчитает расход дважды.
6. **Продлением занимается xpayment**: автосчёт Kaspi продлевает период после оплаты, а ваш сервис при следующей проверке увидит новый срок.

## Практические советы

- **Кэшируйте умеренно.** Права можно держать в памяти до минуты, а решение «можно ли выполнить действие, которое тратит лимит» принимайте по ответу `usage`: он атомарный и не даст превысить конечный лимит.
- **Не доверяйте только своей базе.** Источник истины по срокам и лимитам — xpayment: изменения из кабинета (выдача, отмена, продление) видны со следующего запроса.
- **Предусмотрите отказ.** `409 LIMIT_EXCEEDED` и `409 NO_ACCESS` — штатные ситуации, а не сбои; покажите пользователю предложение сменить тариф.
- **Подписки — отдельный ключ.** Не используйте ключ `xsub_…` для платежей и ключ `xapi_…` для подписок.

## Где что смотреть

- Платёжный API, которым оплачиваются счета: [Приём удалённых платежей](https://xpayment.kz/blog/direct-payment) и [Платёжные ссылки](https://xpayment.kz/blog/payment-link).
- Статусы платежей и возвраты: [Статусы платежей и возвраты](https://xpayment.kz/blog/payment-statuses-and-refunds).
- Полный справочник подписок с примерами: [xpayment.kz/docs](https://xpayment.kz/docs#section-v2).

## Читайте также
- [Виртуальный кассир xpayment](https://xpayment.kz/blog/xpayment-virtual-cashier-api)
- [Удалённые платежи](https://xpayment.kz/blog/direct-payment)
- [Webhooks xpayment](https://xpayment.kz/blog/webhooks)

---

Источник: https://xpayment.kz/blog/subscriptions-api
