Как устроена Gigma

Gigma объединяет клиентские сценарии и внутреннее управление бизнесом в одной проектной модели. Разработчику важно сначала выбрать API-контур и только потом способ авторизации и конкретные endpoint.

Два API-контура

Контур	Кто обращается	Что делает	Основная авторизация
Сайты и приложения	сайт, мобильное приложение, BFF продукта	вход клиента, профиль, каталог, заказы, оплаты и подписки	App Token; Counterparty Bearer — после входа для персональных методов
Платформа	сотрудник, внутренний backend или агент	бизнесы, приложения, каталог, склады, клиенты, заказы, задачи и контент	Bearer пользователя проекта

Контуры работают с общими сущностями, но не заменяют друг друга. App Token не даёт прав сотрудника, Bearer сотрудника нельзя использовать как клиентскую авторизацию, а Counterparty Bearer не открывает административные методы.

Общая модель

Project

Project — верхняя граница данных и доступа одного владельца. Пользователи, бизнесы, приложения, клиенты, заказы и другие объекты должны обрабатываться внутри своего проекта.

Branch

Branch — бизнес, юридическое лицо, филиал или операционное направление внутри проекта. К нему могут относиться реквизиты, сотрудники, приложения, склады и магазины.

Application

Application — конкретный сайт, приложение или сервис. Оно выбирает настройки клиентского продукта: каталог, склады, способы оплаты, контент, меню и подписочные тарифы.

App Token передаётся в заголовке:

Token: <application_token>

App Token выбирает Application, но не идентифицирует клиента и не даёт административных прав. В прямой frontend-интеграции пользователь может увидеть его в сетевых запросах, поэтому App Token нельзя считать конфиденциальным доказательством личности, покупки или права доступа.

User

User — сотрудник, оператор, менеджер или агент. Он работает с платформенным API по Bearer и ограничен проектом, ролью и permissions.

Authorization: Bearer <user_access_token>

Counterparty

Counterparty — внешний клиент или компания, которые взаимодействуют с продуктом. В клиентском контуре Counterparty получает отдельный Bearer для профиля, избранного, заказов и подписок.

Authorization: Bearer <counterparty_access_token>

User и Counterparty — разные субъекты и разные guards. Их токены нельзя взаимозаменять.

Выберите сценарий

Создать клиентский продукт без собственного backend

Подходит, когда сайту или приложению достаточно готовых API Gigma.

Frontend
  │ App Token
  │ Counterparty Bearer после входа
  ▼
Gigma API

Подготовьте Application.
Получите публичный каталог или контент по App Token.
Подключите вход клиента.
Для персональных операций добавляйте Counterparty Bearer по правилам конкретного endpoint.
Не используйте frontend как единственное доказательство оплаты или права доступа.

Начните с обзора API для сайтов и приложений.

Подключить продукт через собственный backend

Используйте BFF или backend, если продукт хранит закрытые данные, собственные роли или платный функционал.

Frontend
  │ локальная HttpOnly-сессия
  ▼
Backend / BFF продукта
  │ App Token
  │ Counterparty Bearer для персональных методов
  ▼
Gigma API

Backend хранит Counterparty Bearer, связывает клиента с локальным пользователем и перед защищённым действием повторно проверяет актуальный заказ или подписку. Frontend показывает состояние, но не принимает окончательное решение о доступе.

Подробная схема находится в интеграции с backend.

Автоматизировать внутреннюю работу бизнеса

Этот сценарий использует платформенный API.

Сотрудник / внутренний сервис / агент
  │ Bearer пользователя проекта
  ▼
API управления бизнесом

Создайте отдельного пользователя интеграции или агента с минимальной ролью.
Выполните вход и получите Bearer.
Проверьте пользователя и permissions через GET /api/user.
Получайте ID только из ресурсов текущего проекта.
Для опасных операций используйте подтверждение, журналирование и сверку результата.

Начните с обзора платформы.

Как связаны клиентский и внутренний контуры

Типичный запуск продукта выглядит так:

Платформа
  ├─ бизнес и реквизиты
  ├─ Application
  ├─ каталог, склады и остатки
  ├─ оплата, скидки и контент
  ▼
Сайт или приложение
  ├─ вход клиента
  ├─ каталог
  ├─ заказ или подписка
  ▼
Backend продукта
  └─ проверка платного доступа и собственная бизнес-логика

Платформенный API настраивает и обслуживает бизнес. Клиентский API использует эти настройки в конкретном Application. Собственный backend добавляет закрытые данные и правила, которых нет в Gigma.

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

Отвечает Gigma	Отвечает интегратор
проектная область и проверка поддерживаемых токенов	безопасное хранение токенов и локальных сессий
каталог, приложения, заказы, оплаты и подписки в пределах их контрактов	собственные роли, закрытые данные и дополнительные бизнес-правила
права пользователя платформы и контекст клиента	подтверждение человека для рискованных автоматизаций
webhooks поддерживаемых событий	подпись, дедупликация, очередь и повторная сверка состояния
актуальное состояние ресурсов Gigma	обработка сетевой неопределённости и идемпотентность локальных операций

Как выбрать следующий раздел

Создаёте интерфейс для конечного клиента — Сайты и приложения.
Настраиваете бизнес, каталог, склады, сотрудников или операционные процессы — Платформа.
Нужны общие правила ошибок, повторов и токенов — Правила API.
Нужны допустимые ID и источники справочников — Справочники и значения.
Нужен машиночитаемый контракт — OpenAPI и Swagger UI.