Каталог тарифов

Каталог нужен, чтобы показать клиенту доступные подписки до входа в личный кабинет. Для запроса достаточно App Token: Bearer клиента не нужен.

Все методы читают один и тот же набор тарифов текущего Application. Они отличаются только формой ответа.

Какой метод выбрать

Метод	Когда использовать
`subscription-catalog/grouped`	основной вариант для новой витрины: структура всегда содержит `variants`
`subscription-catalog`	поддержка витрины, которая умеет разбирать и плоский, и сгруппированный ответ
`subscription-plans`	нужен короткий плоский список с `slug`, числовой суммой и периодом

Для новой интеграции используйте subscription-catalog/grouped. У обычного subscription-catalog форма ответа меняется, когда в каталоге появляется первый тариф с вариантами. Из-за этого ранее работающий плоский парсер может сломаться после изменения тарифов в платформе.

Подготовка

Создайте тариф с is_subscription: true, положительной ценой и периодом от одного месяца.
Назначьте тариф нужному приложению.
Передайте App Token этого приложения в заголовке Token.

У приложений с subscription_catalog_configured: true каталог содержит только активные назначенные тарифы. У новых приложений этот флаг включён сразу, поэтому до первого назначения ответ будет пустым.

Режим совместимости действует только для старых приложений с опущенным subscription_catalog_configured: они могут получить все подписочные позиции проекта, включая позиции без привязки к приложению.

Получение подписочного каталога

Метод: GET
URL: https://api.gigma.ru/api/counterparty/subscription-catalog
Авторизация: App Token
Headers: Token: {application_token}
Успешный ответ: 200

Метод возвращает плоский список, пока у тарифов нет вариантов. Если появляется хотя бы один вариант, весь ответ становится сгруппированным.

Ответ без вариантов

{
    "data": [
        {
            "id": 34780,
            "name": "Базовый",
            "description": "Доступ к сервису",
            "avatar_url": null,
            "price": "490.00",
            "currency": "RUB",
            "billing_period_months": 1
        }
    ]
}

Ответ с вариантами

{
    "data": [
        {
            "id": 34780,
            "name": "Базовый",
            "description": "Доступ к сервису",
            "avatar_url": null,
            "price": "490.00",
            "currency": "RUB",
            "billing_period_months": 1,
            "variants": [
                {
                    "id": 34780,
                    "label": "1 месяц",
                    "price": "490.00",
                    "currency": "RUB",
                    "billing_period_months": 1
                },
                {
                    "id": 34786,
                    "label": "3 месяца",
                    "price": "1290.00",
                    "currency": "RUB",
                    "billing_period_months": 3
                }
            ]
        }
    ]
}

Для оформления передайте id выбранного тарифа или варианта в POST /api/counterparty/subscriptions/checkout.

Ошибки

401 — App Token отсутствует или не распознан;
429 — превышен лимит 60 запросов в минуту.

Получение сгруппированного каталога

Метод: GET
URL: https://api.gigma.ru/api/counterparty/subscription-catalog/grouped
Авторизация: App Token
Headers: Token: {application_token}
Успешный ответ: 200

Метод всегда возвращает массив variants, даже если у тарифа только один вариант. Это стабильный контракт для карточек с выбором периода.

Ответ

{
    "data": [
        {
            "id": 34780,
            "name": "Базовый",
            "description": "Доступ к сервису",
            "avatar_url": null,
            "price": "490.00",
            "currency": "RUB",
            "billing_period_months": 1,
            "variants": [
                {
                    "id": 34780,
                    "label": "1 месяц",
                    "price": "490.00",
                    "currency": "RUB",
                    "billing_period_months": 1
                }
            ]
        }
    ]
}

Ошибки

401 — App Token отсутствует или не распознан;
429 — превышен лимит 60 запросов в минуту.

Получение плоских планов подписки

Метод: GET
URL: https://api.gigma.ru/api/counterparty/subscription-plans
Авторизация: App Token
Headers: Token: {application_token}
Успешный ответ: 200

Метод возвращает короткое представление каждого тарифа без группировки.

Ответ

{
    "data": [
        {
            "name": "Базовый",
            "slug": "nomenclature-34780",
            "amount": 490,
            "currency": "RUB",
            "period_months": 1
        }
    ]
}

В этом ответе amount — число. Поле slug имеет формат nomenclature-{id} и подходит для создания подписки с сохранённым способом оплаты.

Ошибки

401 — App Token отсутствует или не распознан;
429 — превышен лимит 60 запросов в минуту.

Следующий шаг

После выбора тарифа создайте checkout. Не берите цену и период из интерфейса клиента как источник истины: передавайте идентификатор тарифа, а Gigma сама использует его актуальные условия.