Интеграция с backend

Используйте собственный backend или BFF, когда покупка в Gigma должна открыть закрытые данные или функции вашего продукта. Frontend показывает интерфейс, Gigma хранит состояние профиля, заказа, оплаты и подписки, а ваш backend принимает окончательное решение о доступе.

Разделение ответственности

Браузер
  │ HttpOnly cookie вашей сессии
  ▼
Backend / BFF продукта
  │ App Token + Counterparty Bearer
  ▼
Gigma API

Рекомендуемый поток входа

1. Backend инициирует выбранный способ входа клиента.
2. После успешного входа он получает Counterparty Bearer и связывает его с локальным пользователем.
3. Bearer хранится на сервере; браузер получает только cookie локальной сессии.
4. Перед обращением к Gigma backend добавляет нужный App Token и Bearer клиента.
5. При выходе backend отзывает токен в Gigma и удаляет локальную сессию.

Для cookie используйте HttpOnly, Secure и подходящий вашему доменному сценарию SameSite. Counterparty Bearer не должен попадать в URL, browser storage, аналитику или обычные application-логи.

Как открывать доступ после покупки

Доступ по обычному заказу

1. Получите заказ через GET /api/counterparty/orders/{id}.
2. Убедитесь, что заказ принадлежит текущему клиенту и текущему Application — backend Gigma дополнительно проверяет это сам.
3. Разрешайте действие только для вашего явно заданного оплаченного статуса.
4. Не доверяйте payment_link, query-параметрам возврата или данным, присланным frontend.

Доступ по подписке

Получите GET /api/counterparty/subscriptions и найдите нужный тариф. Минимальное правило действующего доступа:

subscription.status == "active"
AND subscription.current_period_end > now

charging, past_due и canceled не дают закрытый доступ. Проверяйте состояние перед защищённым действием, а не только при входе пользователя.

Webhook и повторная проверка

Webhook order.paid помогает быстро обновить локальное состояние, но не должен быть единственным доказательством доступа. Обработчик должен:

1. проверить подпись и идентификатор Application;
2. обработать событие идемпотентно;
3. повторно получить заказ или подписку из Gigma;
4. только после этого обновить локальное право доступа.

Настройка webhooks описана в Платформа / Приложения.

Когда нужен introspect

Обычный BFF уже получает Bearer от Gigma и может использовать его напрямую. Introspect нужен, когда Bearer передаётся вашему backend другой доверенной системой и требуется серверная проверка токена отдельными client credentials.

Heartbeat не является проверкой доступа

Heartbeat учитывает активное время клиентской сессии. Он не подтверждает оплату, подписку или право на функцию.

Ошибки и повторы

• 401 — очистите локальную сессию или повторите вход; не зацикливайте refresh.
• 403 — клиент опознан, но действие запрещено вашим правилом доступа.
• 409 — операция конфликтует с уже выполняемой; сначала получите текущее состояние.
• 422 — исправьте данные или бизнес-условия, автоматический повтор не поможет.
• 429 — соблюдайте Retry-After.
• 5xx и сетевой сбой — результат операции может быть неизвестен; сначала выполните безопасное чтение состояния.

Общие форматы ответов и правила повторов находятся в соглашениях API.

Карта интеграции