Gigma

Приложения

Вложенные ресурсы приложения — пункты меню, категории, бренды и порядок складов — обрабатываются без проверки проекта: объект находится по переданному id, и Bearer вашего проекта не защищает от правки чужого объекта, если id угадан или перепутан. Само приложение, вебхуки, каналы уведомлений и подписочные номенклатуры авторизуются и отвечают 403.

Витрину приложения настраивают по шагам в управлении магазином, контент — в headless-управлении, подписочные тарифы — в управлении подписками. Здесь лежит контракт каждого метода.

Application — это витрина проекта: сайт, мобильное приложение, miniapp или сервис. Объект один и тот же, тип задаёт флаг is_website, поэтому отдельного раздела «сайты» в API нет.

Этими методами проект собирает витрину целиком: создаёт приложение и получает App Token, задаёт склады и ассортимент, назначает подписочные тарифы, включает уведомления клиентам и вебхуки для своего backend. Что такое приложение с точки зрения продукта и как довести его до первого запроса — на странице «Подготовка приложения». Для схемы с собственным сервером — «Интеграция с backend».

Из чего состоит приложение

БлокЧто решаетМетоды
Приложениефилиал, название, оптовый режим, возврат после оплаты, включённость App Tokenк методам
Складыкакие остатки видит витрина и какая платёжная интеграция сработает первойк методам
Категории и брендычто попадает в клиентский каталог и в каком порядкекатегории, бренды
Пункты менюнавигация, которую фронтенд получает готовым деревомк методам
Подписочные тарифычто клиент сможет оформить как подпискук методам
Уведомления клиентамSMS — о неудачном списании и напоминания о подписке; email — только напоминанияк методам
Вебхукиоповещение вашего backend об оплаченном заказек методам

Порядок настройки

  1. Создайте приложение — POST /api/applications. Ответ содержит App Token: отдельного метода перевыпуска нет, но текущее значение всегда видно в карточке приложения.
  2. Привяжите склады — обновление приложения, поле warehouse_id. Список синхронизируется целиком: передавайте весь набор. Без складов каталог пуст, а расчёт заказа и оплата подписки отвечают 422; чисто контентному приложению склады не нужны — страницы, блоки и меню отдаются и без них.
  3. Соберите ассортимент — добавьте категории и бренды. Клиентские справочники возвращают только добавленное в это приложение.
  4. Назначьте подписочные тарифы, если продаёте подписку — привязка тарифа. У приложения в режиме управляемого каталога без назначений клиент не увидит ни одного тарифа. У старых приложений с subscription_catalog_configured: false витрине пока доступны все подписочные позиции проекта, и первое же назначение включает управляемый режим — то есть скрывает всё, что вы не назначили явно.
  5. Включите уведомления клиентам, если Gigma должна сама писать о проблемах с оплатой — SMS и email. Оба канала выключены по умолчанию и доступны роли owner или admin.
  6. Добавьте вебхук, если оплата должна что-то запускать в вашей системе — создание вебхука. Тоже роль owner или admin.

Выключить витрину в любой момент можно флагом is_token_active в обновлении приложения: App Token перестаёт работать сразу, а настройки и история остаются.

Кто и что может настраивать

БлокТребуется
Просмотр приложенийview-applications, create-applications или edit-applications
Создание приложенияcreate-applications или edit-applications
Изменение и удаление приложенияedit-applications
Подписочные тарифы приложенияedit-applications (просмотр назначенных — любое из прав просмотра)
Уведомления клиентам и вебхукироль owner или admin

Приложение должно принадлежать проекту пользователя — это относится и к методам витрины: категории, бренды, пункты меню, блоки и приоритет складов требуют права просмотра приложений для чтения и edit-applications для изменений. Заголовки авторизации — в соглашениях.

Справочник методов

Дальше методы идут блоками в том же порядке, что и настройка. Общее для всех запросов: авторизация — Bearer пользователя платформы, а маршруты вида /api/tables/... предназначены для табличных экранов платформы и отдают объекты с готовыми колонками. Само приложение чужого проекта недоступно ни на чтение, ни на изменение — 403. А вот вложенные ресурсы — пункты меню, категории, бренды и порядок складов — принадлежность проекту не проверяют: объект находится по переданному id, поэтому сверяйте id на своей стороне, особенно в скриптах.

Приложение

Создание приложения выдаёт App Token: с этого момента витрина может обращаться к клиентскому API сайтов и приложений. Остальные настройки блока определяют, от какого филиала работает витрина и включён ли доступ.

Получение списка приложений

Метод
GET
URL
https://api.gigma.ru/api/applications
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • query (string, необязательный) — поиск по названию, не менее трёх символов.

Ответ

Возвращает приложения проекта в поле applications и их количество в applicationsCount.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.

Список приложений (табличное представление)

Метод
GET
URL
https://api.gigma.ru/api/tables/applications
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Тот же список, но с колонками для табличного экрана ERP. Параметр query работает так же.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.

Создание приложения

Метод
POST
URL
https://api.gigma.ru/api/applications
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • name (string, обязательный) — название приложения.
  • is_website (bool, обязательный) — true для сайта, false для другого типа клиента.
  • branch_id (int, обязательный) — ID филиала.
  • sales_strategy_id (int, обязательный) — ID стратегии продаж.
  • code (int, необязательный) — уникальный код в проекте. Если не передать, Gigma создаст его автоматически.
  • photo_id (int, необязательный) — ID файла-обложки.
  • wholesale (bool, необязательный) — оптовый режим: заказ принимается только кратно упаковке.
  • success_payment_url (string|null, необязательный) — URL возврата после успешной оплаты, до 2048 символов.

Пример запроса

{
    "name": "Интернет-магазин",
    "is_website": true,
    "branch_id": 5,
    "sales_strategy_id": 1,
    "success_payment_url": "https://myshop.ru/success"
}

Ответ

Возвращает HTTP код 200 и объект application. Поле token содержит App Token — его передают в заголовке Token при запросах к E-Commerce API. Отдельного метода перевыпуска токена нет.

Склады привязывайте отдельным запросом обновления приложения: без складов витрина остаётся пустой.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.
  • 422 — тело запроса не прошло валидацию.

Получение выбранного приложения

Метод
GET
URL
https://api.gigma.ru/api/applications/{id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

{
    "application": {
        "id": 1,
        "branch": { "id": 5, "name": "Главный филиал" },
        "is_website": false,
        "photo": null,
        "code": 123456,
        "name": "Интернет-магазин",
        "is_token_active": true,
        "subscription_catalog_configured": true,
        "wholesale": false,
        "token": "abc123token",
        "success_payment_url": "https://myshop.ru/success",
        "warehouses": [{ "id": 3, "name": "Склад №1" }],
        "sales_strategy": { "id": 1, "name": "Стандартная" }
    }
}
Описание полей
  • branch — филиал приложения (id, name). Задаёт бизнес, от имени которого работает витрина.
  • is_website (bool) — сайт или другой тип клиента.
  • photo — файл-обложка или null.
  • code — уникальный в проекте код приложения.
  • name — название приложения.
  • is_token_active (bool) — активен ли App Token. При false E-Commerce API отвечает 401 на любой запрос витрины.
  • subscription_catalog_configured — собран ли каталог подписок: при true витрина отдаёт только назначенные тарифы, при false — все подписочные позиции проекта
  • wholesale (bool) — оптовый режим.
  • token (string|null) — App Token.
  • success_payment_url (string|null) — URL возврата после оплаты.
  • warehouses — склады приложения. Определяют доступные остатки и выбор платёжной интеграции.
  • sales_strategy (object|null) — стратегия продаж. Обязательна при создании; сейчас возвращается в ответах ERP, но не меняет цены и состав каталога витрины.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.

Обновление приложения

Метод
PUT
URL
https://api.gigma.ru/api/applications/{id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Все поля необязательные — передавайте только изменяемые. Тот же набор полей принимает частичное обновление через PATCH.

Параметры запроса

  • name (string, опционально) — название приложения.
  • is_website (bool, опционально) — сайт или другой тип клиента.
  • branch_id (int, опционально) — ID филиала.
  • sales_strategy_id (int, опционально) — ID стратегии продаж.
  • code (int, опционально) — уникальный код в проекте или null.
  • photo_id (int, опционально) — ID файла-обложки.
  • warehouse_id (array of int, опционально) — полный список складов приложения. Передавайте весь набор: склады синхронизируются, а не добавляются.
  • wholesale (bool, опционально) — оптовый режим.
  • success_payment_url (string, опционально) — URL возврата после оплаты, до 2048 символов, или null.
  • is_token_active (bool, опционально) — включение и выключение App Token. Это штатный способ мгновенно закрыть витрине доступ к API.

Пример запроса

{
    "name": "Интернет-магазин",
    "is_website": true,
    "branch_id": 5,
    "sales_strategy_id": 1,
    "code": 123456,
    "photo_id": 42,
    "warehouse_id": [3, 7],
    "wholesale": false,
    "success_payment_url": "https://myshop.ru/success",
    "is_token_active": false
}

Ответ

HTTP 200 с обновлённым объектом application.

Склады влияют на три вещи сразу: каталог (GET /api/counterparty/products показывает только товары этих складов), расчёт заказа (422, если инвентарь не найден) и оплату подписок (422 «Для этого ЭПС не настроен платёжный склад», если складов нет).

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.
  • 422 — тело запроса не прошло валидацию.

Частичное обновление приложения

Метод
PATCH
URL
https://api.gigma.ru/api/applications/{id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

Те же поля и те же правила, что у обновления через PUT: передавайте только изменяемые.

  • name (string, опционально) — название приложения.
  • is_website (bool, опционально) — сайт или другой тип клиента.
  • branch_id (int, опционально) — ID филиала.
  • sales_strategy_id (int, опционально) — ID стратегии продаж.
  • code (int, опционально) — уникальный код в проекте или null.
  • photo_id (int, опционально) — ID файла-обложки.
  • warehouse_id (array of int, опционально) — полный список складов приложения. Передавайте весь набор: склады синхронизируются, а не добавляются.
  • wholesale (bool, опционально) — оптовый режим.
  • success_payment_url (string, опционально) — URL возврата после оплаты, до 2048 символов, или null.
  • is_token_active (bool, опционально) — включение и выключение App Token. Это штатный способ мгновенно закрыть витрине доступ к API.

Пример запроса

{
    "name": "Интернет-магазин",
    "is_website": true,
    "branch_id": 5,
    "sales_strategy_id": 1,
    "code": 123456,
    "photo_id": 42,
    "warehouse_id": [3, 7],
    "wholesale": false,
    "success_payment_url": "https://myshop.ru/success",
    "is_token_active": false
}

Ответ

HTTP 200 с обновлённым объектом application.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.
  • 422 — тело запроса не прошло валидацию.

Удаление приложения

Метод
DELETE
URL
https://api.gigma.ru/api/applications/{id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с сообщением Application deleted.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.
  • 409 — у приложения есть история подписок: «Нельзя удалить ЭПС с историей подписок». В этом случае выключите токен через обновление приложения.

История изменений приложения

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/history
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Возвращает записи об изменениях приложения. Формат истории — как в ERP / Контрагенты.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — приложения с таким идентификатором нет.

Склады приложения

Склады определяют, какие остатки видит витрина и какая платёжная интеграция используется первой: при оплате склады перебираются по возрастанию priority.

Список складов приложения (табличное)

Метод
GET
URL
https://api.gigma.ru/api/tables/applications/{application}/automations
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • query (string, необязательный) — поиск по названию склада.

Ответ

Список складов приложения с их приоритетом в поле automations. Сам состав складов меняется через обновление приложения.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Увеличение priority склада

Метод
POST
URL
https://api.gigma.ru/api/applications/{application}/warehouses/{warehouse}/up
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Увеличивает priority склада на 1. Так как платёжные интеграции перебираются по возрастанию priority, склад после этого проверяется позже.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Уменьшение priority склада

Метод
POST
URL
https://api.gigma.ru/api/applications/{application}/warehouses/{warehouse}/down
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Уменьшает priority склада на 1 — склад проверяется раньше. При priority: 0 метод возвращает сообщение Priority cannot be decreased below zero.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Категории приложения

Клиентский метод GET /api/counterparty/categories возвращает только категории, добавленные в приложение, и сортирует их по убыванию priority. Пока категории не добавлены, дерево каталога у витрины пустое.

Получение списка категорий приложения (табличное)

Метод
GET
URL
https://api.gigma.ru/api/tables/applications/{id}/categories
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • query (string, необязательный) — поиск по названию категории.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Получение списка категорий приложения

Метод
GET
URL
https://api.gigma.ru/api/applications/{id}/categories
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Категории приложения в порядке показа — по убыванию priority.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Добавление категории в приложение

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/categories
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • category_id (int, обязательный) — ID категории.

Ответ

HTTP 200 с добавленной категорией. Новая категория получает наибольший priority, то есть встаёт в начало списка. Повторное добавление той же категории не создаёт дубль.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Получение категории приложения

Метод
GET
URL
https://api.gigma.ru/api/applications/{id}/categories/{category_id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с категорией и её позицией в этом приложении.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Удаление категории из приложения

Метод
DELETE
URL
https://api.gigma.ru/api/applications/{id}/categories/{category_id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Категория отвязывается от приложения; сама категория проекта не удаляется.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Уменьшение priority категории

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/categories/{category_id}/up
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Уменьшает priority категории на 1, не опускаясь ниже 1. Список сортируется по убыванию priority, поэтому категория смещается к концу списка.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Увеличение priority категории

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/categories/{category_id}/down
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Увеличивает priority категории на 1, но не выше текущего максимума в приложении — категория смещается к началу списка.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Бренды приложения

GET /api/counterparty/brands отдаёт бренды приложения, отфильтрованные по его филиалу и отсортированные по убыванию priority.

Получение списка брендов приложения (табличное)

Метод
GET
URL
https://api.gigma.ru/api/tables/applications/{id}/brands
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • query (string, необязательный) — поиск по названию бренда.

Ответ

HTTP 200 с колонками для табличного экрана ERP.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Получение списка брендов приложения

Метод
GET
URL
https://api.gigma.ru/api/applications/{id}/brands
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

Бренды приложения в порядке показа — по убыванию priority.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Добавление бренда в приложение

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/brands
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • brand_id (int, обязательный) — ID бренда.

Ответ

HTTP 200 с добавленным брендом. Новый бренд получает priority: 0, то есть оказывается в конце списка.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Получение бренда приложения

Метод
GET
URL
https://api.gigma.ru/api/applications/{id}/brands/{brand_id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с брендом и его позицией в этом приложении.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Удаление бренда из приложения

Метод
DELETE
URL
https://api.gigma.ru/api/applications/{id}/brands/{brand_id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с сообщением подтверждения. Бренд отвязывается от приложения; сам бренд проекта не удаляется.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Увеличение priority бренда

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/brands/{brand_id}/up
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Увеличивает priority бренда на 1 — бренд смещается к началу списка. Обратите внимание: у категорий метод up работает наоборот.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Уменьшение priority бренда

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/brands/{brand_id}/down
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Уменьшает priority бренда на 1. При priority: 0 возвращается сообщение Priority cannot be decreased below zero.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Пункты меню

Пункты меню — это данные навигации для вашего фронтенда. Витрина получает их через GET /api/counterparty/menus/{slug?} (Навигационная панель). Порядок задаётся полем order по возрастанию, вложенность — полем parent_id.

Получение списка пунктов меню (табличное)

Метод
GET
URL
https://api.gigma.ru/api/tables/applications/{id}/menu_items
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • query (string, необязательный) — поиск по названию пункта.

Ответ

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

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Получение списка пунктов меню

Метод
GET
URL
https://api.gigma.ru/api/applications/{id}/menu_items
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

Все пункты меню приложения без группировки по уровням — дерево собирайте по parent_id.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Создание пункта меню

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/menu_items
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • name (string, обязательный) — название пункта меню.
  • slug (string, необязательный) — slug пункта.
  • code (int, необязательный) — уникальный в проекте код пункта.
  • parent_id (int, необязательный) — ID родительского пункта.
  • order (int, необязательный, от 1) — позиция в списке.
  • avatar_id (int, необязательный) — ID файла аватара.
  • preview_id (int, необязательный) — ID файла превью.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Получение пункта меню

Метод
GET
URL
https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с пунктом меню и его связями.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Обновление пункта меню

Метод
PUT
URL
https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Те же параметры, что и при создании; все необязательные.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Удаление пункта меню

Метод
DELETE
URL
https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с сообщением подтверждения. Вложенные пункты удаляются вместе с родителем — если они нужны, сначала перенесите их на другой parent_id.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.

Перемещение пункта меню вверх

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}/up
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Уменьшает order на 1, не опускаясь ниже 1. Список сортируется по возрастанию order, поэтому пункт поднимается. Возвращает обновлённый пункт меню.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Перемещение пункта меню вниз

Метод
POST
URL
https://api.gigma.ru/api/applications/{id}/menu_items/{menu_item_id}/down
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Увеличивает order на 1 — пункт опускается, но не ниже последнего пункта того же уровня. Возвращает обновлённый пункт меню.

Возможные ошибки

  • 404 — объекта с таким id не существует. Принадлежность приложения вашему проекту этот маршрут не проверяет: чужой существующий id отработает как свой.
  • 422 — тело запроса не прошло валидацию.

Подписочные тарифы приложения

Приложение продаёт только те подписочные тарифы, которые ему назначены и активны: клиентский каталог подписок собирается из этих привязок. Пока ни один тариф не назначен, клиент не сможет оформить подписку. Общая номенклатура проекта при этом не меняется — назначение лишь определяет витрину конкретного приложения.

Каталог настройки и любые изменения требуют права edit-applications; список уже назначенных тарифов доступен с любым правом просмотра приложений. Во всех случаях приложение должно принадлежать проекту пользователя.

Каталог тарифов для настройки приложения

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures/catalog
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

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

{
    "data": [
        {
            "nomenclature": {
                "id": 34786,
                "name": "Uhoster — 1 месяц",
                "parent_nomenclature_id": 34780,
                "variant_label": "1 месяц",
                "variant_sort_order": 10,
                "price": "490.00",
                "billing_period_months": 1
            },
            "assignment": {
                "id": 42,
                "is_active": true,
                "sort_order": 0
            }
        }
    ],
    "meta": {
        "application_id": 275,
        "subscription_catalog_configured": true
    }
}
Описание полей
  • nomenclature — тариф из общего справочника проекта.
  • price (string) — цена тарифа. Строковый формат сохраняет точность денежных значений.
  • parent_nomenclature_id — ID родительского тарифа для варианта или null.
  • assignment — привязка тарифа к этому приложению. null означает, что тариф ещё не добавлен; объект с is_active: false означает, что он добавлен, но выключен.
  • sort_order — порядок показа активных тарифов в клиентском каталоге.
  • subscription_catalog_configured — режим управляемого каталога. У приложений, созданных через API, он включён: продаются только назначенные активные тарифы. У старых приложений с false витрине доступны все подписочные позиции проекта.

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

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.

Список назначенных тарифов

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Только привязки этого приложения, по возрастанию sort_order. Метод доступен с любым правом просмотра приложений — в отличие от каталога настройки, который требует edit-applications.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.

Назначить подписочный тариф приложению

Метод
POST
URL
https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • nomenclature_id (integer, обязательно) — ID подписочного тарифа текущего проекта. Обычный товар назначить нельзя.
  • is_active (boolean, опционально, по умолчанию true) — доступен ли тариф клиентам.
  • sort_order (integer, опционально, по умолчанию 0) — порядок в каталоге.

Пример запроса

{
    "nomenclature_id": 34786,
    "is_active": true,
    "sort_order": 0
}

Ответ

HTTP 200 с созданной или обновлённой привязкой. Повторный POST того же тарифа не создаёт дубль, а обновляет существующую привязку. Первое назначение также включает у приложения режим управляемого каталога.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 404 — номенклатура не найдена в проекте приложения или не является подписочным тарифом.

Изменить привязку подписочного тарифа

Метод
PATCH
URL
https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures/{assignment}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Пример запроса

{
    "is_active": false,
    "sort_order": 10
}

Можно передать is_active, sort_order или оба поля. assignment — ID объекта assignment из management-каталога, а не ID номенклатуры.

Выключение тарифа убирает его из клиентского каталога, но не отменяет уже оформленные подписки.

Ответ

HTTP 200 с обновлённой привязкой.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.
  • 422 — тело запроса не прошло валидацию.

Удалить привязку подписочного тарифа

Метод
DELETE
URL
https://api.gigma.ru/api/applications/{application}/subscription-nomenclatures/{assignment}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200:

{
    "message": "Subscription nomenclature assignment deleted"
}

Не используйте массовую замену списка: каждая привязка создаётся, включается, сортируется или удаляется отдельным запросом.

Возможные ошибки

  • 403 — у пользователя нет нужного права либо приложение принадлежит другому проекту.

Уведомления клиентам

Каналы уведомлений отвечают за сообщения о подписке, которые Gigma отправляет клиенту сама: не удалось списать оплату, пора возобновить подписку, нужно привязать карту. Настройка отдельная для каждого приложения, доступна роли owner или admin того же проекта.

Оба канала выключены по умолчанию. GET возвращает текущие настройки, а для ненастроенного канала — значения по умолчанию с is_active: false.

Общие правила:

  • В шаблонах допустимы только перечисленные плейсхолдеры; неизвестный {placeholder} — ошибка 422.
  • Секреты в ответах не раскрываются: канал SMS возвращает только флаги has_smsc_login, has_smsc_password, has_smsc_api_key.
  • Ссылки в шаблонах должны начинаться с https://.

Настройки SMS-канала

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/notification-channels/sms
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

{
    "notification_channel": {
        "id": 12,
        "application_id": 275,
        "channel": "sms",
        "provider": "smsc",
        "is_active": true,
        "settings": {
            "sender": "GIGMA",
            "max_sms_parts": 2,
            "events": {
                "subscription_charge_failed": {
                    "is_active": true,
                    "template": "Не удалось списать {amount} ₽ за подписку {plan}. Проверьте карту: {action_url}",
                    "action_url": null
                }
            }
        },
        "has_smsc_login": true,
        "has_smsc_password": true,
        "has_smsc_api_key": false
    }
}
События канала
  • subscription_charge_failed — не удалось списать оплату. Плейсхолдеры: {amount}, {plan}, {reason}, {action_url}.
  • subscription_renewal_required — нужно возобновить подписку.
  • subscription_repurchase_required — нужно оформить подписку заново.
  • subscription_payment_method_required — нужно привязать карту.

В трёх последних событиях в шаблоне допустим только {action_url}, и он обязателен.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.

Изменение SMS-канала

Метод
PUT
URL
https://api.gigma.ru/api/applications/{application}/notification-channels/sms
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • is_active (bool) — включение канала.
  • provider (string) — сейчас поддерживается только smsc.
  • smsc_login, smsc_password, smsc_api_key (string|null) — доступы провайдера. Передавайте либо API-ключ, либо пару логин и пароль.
  • settings.sender (string|null) — имя отправителя: до 11 символов из латиницы, цифр и пробелов либо до 15 цифр.
  • settings.max_sms_parts (int, 1–5) — предел длины сообщения о неудачном списании.
  • settings.events.{event}.is_active (bool), settings.events.{event}.template (string), settings.events.{event}.action_url (string) — настройки конкретного события.

Пример запроса

{
    "is_active": true,
    "smsc_api_key": "…",
    "settings": {
        "sender": "GIGMA",
        "events": {
            "subscription_payment_method_required": {
                "is_active": true,
                "template": "Привяжите карту: {action_url}",
                "action_url": "https://myshop.ru/subscription"
            }
        }
    }
}

Ответ

HTTP 200 с настройками канала. Передаются только изменяемые поля — остальные сохраняются.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.
  • 422 — включение канала без доступов SMSC: SMSC credentials are required for active SMS channel.;
  • 422 — шаблон длиннее выбранного лимита частей SMS (для событий-напоминаний лимит — одна часть);
  • 422 — неизвестный плейсхолдер в шаблоне.

Настройки email-канала

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/notification-channels/email
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

Структура как у SMS-канала, но provider — laravel_mail, а у каждого события есть subject, template, action_label и action_url. Событий три: subscription_renewal_required, subscription_repurchase_required, subscription_payment_method_required.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.

Изменение email-канала

Метод
PUT
URL
https://api.gigma.ru/api/applications/{application}/notification-channels/email
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • is_active (bool) — включение канала.
  • provider (string) — сейчас поддерживается только laravel_mail.
  • settings.events.{event}.is_active (bool) — включение события.
  • settings.events.{event}.subject (string, до 255) — тема письма.
  • settings.events.{event}.template (string, до 5000) — текст письма.
  • settings.events.{event}.action_label (string, до 255) — подпись кнопки.
  • settings.events.{event}.action_url (string, https://) — ссылка кнопки.

В теме и подписи кнопки плейсхолдеры не допускаются, в тексте письма допустим {action_url}.

Пример запроса

{
    "is_active": true,
    "provider": "laravel_mail",
    "settings": {
        "events": {
            "subscription_renewal_required": {
                "is_active": true,
                "subject": "Возобновите подписку",
                "template": "Чтобы продолжить пользоваться сервисом, возобновите подписку.",
                "action_label": "Возобновить подписку",
                "action_url": "https://myshop.ru/subscription"
            },
            "subscription_repurchase_required": {
                "is_active": false,
                "subject": "Оформите подписку снова",
                "template": "Чтобы снова пользоваться сервисом, оформите подписку.",
                "action_label": "Оформить подписку",
                "action_url": "https://myshop.ru/subscription"
            },
            "subscription_payment_method_required": {
                "is_active": true,
                "subject": "Привяжите карту для подписки",
                "template": "Привяжите карту, чтобы продлить подписку.",
                "action_label": "Привязать карту",
                "action_url": "https://myshop.ru/subscription"
            }
        }
    }
}

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.
  • 422 — неизвестный плейсхолдер в теме, тексте или подписи кнопки, либо ссылка не на https://.

Вебхуки приложения

Webhook нужен, когда оплата в Gigma должна что-то запустить в вашей системе: выдать доступ, создать учётную запись, отметить оплату в CRM. Сейчас поддерживается одно событие — order.paid после подтверждённой оплаты заказа.

Это дополнительная возможность, а не обязательная часть подключения через собственный backend. Настройка доступна ERP-пользователю роли owner или admin из того же проекта. На одно событие можно держать до 10 активных вебхуков.

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

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/webhooks
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с вебхуками приложения, новые — первыми.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.

Создание вебхука

Метод
POST
URL
https://api.gigma.ru/api/applications/{application}/webhooks
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
201

Параметры запроса

  • event (string, обязательно) — сейчас поддерживается только order.paid.
  • url (string, обязательно, до 2048 символов) — публичный HTTPS URL receiver. Приватные IP, небезопасные redirects и локальные адреса отклоняются.
  • secret (string, обязательно, от 16 до 512 символов) — общий секрет для HMAC-подписи. В ответах значение не раскрывается.
  • headers (object|null, опционально, до 10 заголовков) — дополнительные разрешённые заголовки доставки.
  • is_active (boolean, опционально, по умолчанию true) — включить доставку.

Пример запроса

{
    "event": "order.paid",
    "url": "https://service.example.com/api/webhooks/gigma",
    "secret": "replace-with-a-long-random-secret",
    "headers": {
        "X-Service": "billing"
    },
    "is_active": true
}

Ответ

HTTP 201 с созданным webhook. Поле secret не возвращается; has_secret: true подтверждает, что секрет сохранён.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.
  • 422 — недопустимый URL или заголовок, превышен лимит в 10 активных вебхуков на событие, либо приложение архивировано.

Получение выбранного вебхука

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Ответ

HTTP 200 с объектом вебхука. Секрет не возвращается, его наличие показывает has_secret.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.

Обновление вебхука

Метод
PATCH
URL
https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Параметры запроса

  • url (string, опционально) — новый публичный HTTPS URL.
  • headers (object|null, опционально) — заменить дополнительные заголовки.
  • is_active (boolean, опционально) — включить или выключить доставку.

event после создания не меняется. secret нельзя передавать в PATCH — используйте ротацию секрета.

Пример запроса

{
    "is_active": false
}

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.
  • 422 — тело запроса не прошло валидацию.

Удаление вебхука

Метод
DELETE
URL
https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Webhook архивируется и выключается; журнал доставок сохраняется.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.

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

Метод
GET
URL
https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}/deliveries
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

История доставок по 50 записей на страницу, новые — первыми. По ней видно, дошло ли событие и почему упало.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.

Повторная доставка вебхука

Метод
POST
URL
https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}/deliveries/{delivery}/resend
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Вручную повторить можно только доставку в статусе failed.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.
  • 422 — доставка не в статусе failed или уже обрабатывается.

Ротация секрета вебхука

Метод
POST
URL
https://api.gigma.ru/api/applications/{application}/webhooks/{webhook}/rotate-secret
Авторизация
Bearer token
Headers
Authorization: Bearer {token}
Успешный ответ
200

Генерирует новый 64-символьный секрет для следующих доставок и возвращает его в ответе — сохраните значение сразу.

Возможные ошибки

  • 403 — у пользователя роль ниже admin.
  • 404 — приложение или объект относится к другому проекту либо к другому приложению.
  • 429 — ротация запрошена чаще одного раза в 60 секунд.

Контракт доставки order.paid

Gigma отправляет POST на настроенный URL с JSON body и заголовками:

Content-Type: application/json
X-Webhook-Event: order.paid
X-Webhook-Event-Id: order.paid:<order_id>:<opaque_payment_part>
X-Webhook-Delivery-Id: <delivery_id>
X-Webhook-Timestamp: <unix_timestamp>
X-Signature: sha256=<hex_hmac>

Подпись рассчитывается по исходному телу запроса:

expected = "sha256=" + HMAC_SHA256(secret, timestamp + "." + raw_body)

Перед обработкой проверьте полный X-Signature по raw_body. Gigma считает доставку успешной при любом ответе 2xx. При ином ответе или транспортной ошибке она повторяет ту же delivery через 1, 5, 30, 120 и 720 минут.

event_id — непрозрачный ключ идемпотентности: сохраните его и не обрабатывайте одно событие дважды. event_id и X-Webhook-Delivery-Id не меняются между попытками, а timestamp и HMAC вычисляются заново. Возвращайте 2xx только после того, как событие принято вашим бэкендом.

Пример payload:

{
	"event": "order.paid",
	"event_id": "order.paid:456:2f8d...",
	"occurred_at": "2026-07-18T10:00:00+00:00",
	"order": {
		"id": 456,
		"final_price": "990.00",
		"paid_at": "2026-07-18T10:00:00+00:00",
		"products": [
			{
				"id": 34786,
				"name": "AI assistant monthly",
				"quantity": 1
			}
		]
	},
	"counterparty": {
		"id": 123,
		"phone_1": "79999999990",
		"email": null
	},
	"shop": {
		"id": 10
	}
}

Webhook сообщает об оплате, но не заменяет проверку актуального состояния. Для выдачи доступа используйте правило на странице списка подписок.

© 2026 Gigma