Подготовка приложения

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

Пока приложение не создано и не настроено, клиентские методы отвечать нечем: каталог будет пустым, а заказ и подписка не пройдут. На этой странице — из чего состоит приложение и как за семь шагов дойти до первого успешного запроса.

Понятия

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

Чего приложение не делает:

• не создаёт интерфейс — верстку, маршруты и экраны пишет ваша команда;
• не заводит отдельную базу — номенклатура, клиенты и заказы принадлежат проекту, а приложение задаёт срез: какие товары показать и с каких складов их считать;
• не идентифицирует клиента — App Token выбирает витрину, а не человека за экраном.

Как это работает

Платформа
  └─ сотрудник создаёт Application, склады, каталог, оплату и контент
        │ App Token в заголовке Token
        ▼
Сайт, приложение или сервис
  └─ получает каталог, страницы и меню, оформляет заказ
        │ Counterparty Bearer после входа
        ▼
Клиент
  └─ видит свой профиль, заказы и подписки

Один запрос витрины несёт до двух токенов сразу: App Token говорит, какое приложение спрашивает, Counterparty Bearer — от чьего имени. Они не заменяют друг друга: без App Token непонятен контекст, без Counterparty Bearer недоступны избранное, обычные заказы и подписки.

Исключение одно — упрощённый гостевой заказ: контактная форма создаёт клиента и заказ по одному App Token, без входа.

Прежде чем начать

Нужен доступ сотрудника к нужному Project, право create-applications или edit-applications (склады и подписочные тарифы требуют именно edit-applications), а для уведомлений и вебхуков — роль owner или admin. Ещё понадобится филиал, от которого работает витрина.

Остальное зависит от того, что вы запускаете: контентный сайт, витрину, магазин с оплатой или подписочный сервис. Сводка по сценариям — в конце страницы.

Подключение по шагам

Шаг 1. Создайте приложение

Создайте Application через создание приложения. В запросе обязательны название, флаг is_website, филиал и стратегия продаж.

Ответ вернёт поле token — это App Token. Сохраните его сразу: отдельного метода перевыпуска нет, повторно получить то же значение можно только через карточку приложения.

Шаг 2. Привяжите склады

Передайте список складов в обновлении приложения полем warehouse_id. Список синхронизируется целиком, поэтому отправляйте весь набор, а не только новый склад.

Склады решают три вещи сразу: какие остатки попадут в каталог, пройдёт ли расчёт заказа и какая платёжная интеграция сработает при оплате. Приложение без складов выглядит рабочим, но не продаёт ничего. Для подписки склад нужен ради платёжной интеграции — остатки на нём не требуются. Чисто контентный сайт этот шаг пропускает: страницы, блоки и меню отдаются без складов.

Шаг 3. Подключите то, ради чего запускаете продукт

Дальше набор зависит от задачи, и каждая описана в своём разделе:

• продажи товаров — интернет-магазин: категории и бренды приложения, доставка и оплата;
• регулярные платежи за доступ — сервис управления подписками: назначенные тарифы и склад с платёжной интеграцией;
• тексты, баннеры и навигация — CMS для сайтов: страницы, блоки и меню.

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

Шаг 4. Проверьте App Token

Передавайте App Token в заголовке Token:

GET /api/counterparty/settings HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json

Успешный ответ подтверждает, что токен распознан и контекст приложения выбран:

{
    "wholesale": false
}

Дальше проверьте то, ради чего собирали приложение: контентный сайт — что приходят те виды контента, которые вы настроили (страницы, блоки или меню — они независимы и нужны не все сразу); витрина и магазин — что каталог не пуст; подписочный сервис — что в подписочном каталоге есть тарифы. Для контентного сайта пустой товарный каталог — нормальный результат, а не признак недонастройки.

Что настроить под ваш сценарий

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

Безопасность App Token

App Token выдаётся один раз при создании приложения, и метода перевыпуска нет. Если токен скомпрометирован, выключите его флагом is_token_active через обновление приложения — доступ витрины к API закрывается сразу — и заведите новое приложение.

В прямой интеграции с браузером App Token виден в сетевых запросах, поэтому он не является доказательством личности, покупки или права доступа. Не смешивайте его с ERP Bearer и Counterparty Bearer: это три разных токена с разными задачами. Правила заголовков собраны в соглашениях об авторизации.

Граница ответственности

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

Не считайте кнопку «Оплачено» на фронтенде доказательством покупки: право доступа должно подтверждаться актуальным состоянием заказа или подписки на вашем backend. Как это устроено — в backend-интеграции.