Gigma

Настройка приложения

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

Запросы на этой странице отправляйте с вашего сервера. Для создания и настройки приложения нужен Bearer сотрудника. Для подключения вебхука у сотрудника должна быть роль owner или admin.

Подготовка

Подготовьте:

  • Bearer сотрудника; для шага с вебхуком — сотрудника с ролью owner или admin;
  • branch_id филиала;
  • sales_strategy_id из списка стратегий продаж;
  • склад с настроенной платёжной интеграцией, доступный в интерфейсе Gigma;
  • URL, на который нужно вернуть клиента после оплаты;
  • публичный HTTPS URL для вебхука и случайный секрет длиной не менее 16 символов.

Полные параметры и все административные методы находятся в API-справочнике приложений.

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

POST /api/applications HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <employee_token>
Content-Type: application/json
Accept: application/json

{
	"name": "Интернет-магазин",
	"is_website": true,
	"branch_id": 5,
	"sales_strategy_id": 1,
	"success_payment_url": "https://shop.example.com/payment-result"
}

В ответе вы получите объект application. Сохраните:

  • application.id — понадобится для следующих настроек;
  • application.token — это App Token для запросов каталога, корзины и справочников.

Отдельного метода перевыпуска App Token сейчас нет. Если токен нужно отключить, измените is_token_active.

Полный контракт: создание приложения.

Шаг 2. Подключите склад в интерфейсе Gigma

Откройте созданное приложение в Gigma, выберите подготовленный склад и сохраните настройки. Если складов несколько, проверьте их состав и порядок перед сохранением.

Пока не автоматизируйте привязку склада через PATCH или PUT. Методы привязки находят склады по переданным ID без надёжной проверки принадлежности проекту. Ошибочный ID может подключить склад другого проекта и открыть его остатки в каталоге приложения.

Для автоматической настройки сначала дождитесь подтверждённого исправления ограничения на стороне Gigma. До этого выполняйте привязку через интерфейс Gigma или передавайте задачу ответственному менеджеру.

Без склада товарный каталог будет пуст, расчёт заказа вернёт 422, а онлайн-оплата не сможет выбрать платёжную интеграцию.

Шаг 3. Добавьте категории и бренды

Чтобы категория появилась в фильтрах магазина, привяжите её к приложению:

POST /api/applications/17/categories HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <employee_token>
Content-Type: application/json
Accept: application/json

{
	"category_id": 5
}

Бренд добавляется аналогичным методом /api/applications/{id}/brands.

Используйте только ID объектов своего проекта. Вложенные методы приложения находят объект по переданному ID и не всегда дополнительно проверяют принадлежность проекту.

Полные контракты: категории и бренды.

## Шаг 4. Подключите вебхук

Создайте вебхук для события order.paid:

POST /api/applications/17/webhooks HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <employee_token>
Content-Type: application/json
Accept: application/json

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

Gigma сохранит секрет, но не вернёт его в последующих ответах. Храните значение у себя и не передавайте во фронтенд.

Когда Gigma отправит событие:

  1. прочитайте исходное тело запроса без повторной сериализации;
  2. возьмите timestamp из X-Webhook-Timestamp;
  3. проверьте, что timestamp присутствует, имеет допустимый формат и попадает в выбранное короткое временное окно; отклоните запрос с timestamp из будущего или старше этого окна;
  4. вычислите sha256=HMAC_SHA256(secret, timestamp + "." + raw_body);
  5. сравните результат с X-Signature безопасным сравнением;
  6. сохраните X-Webhook-Event-Id (event_id) и не обрабатывайте одно событие повторно;
  7. получите заказ через API и проверьте его сумму, приложение и статус;
  8. верните ответ 2xx только после того, как событие надёжно принято.

Используйте одинаковое допустимое временное окно на всех экземплярах обработчика. Короткое окно, например пять минут, ограничивает повторное воспроизведение перехваченного подписанного запроса.

Gigma повторяет неуспешную доставку, поэтому обработчик должен быть идемпотентным. Возврат клиента с платёжной страницы не подтверждает оплату.

Полный контракт доставки, повторные попытки и ротация секрета описаны в API-справочнике вебхуков.

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

Отправьте минимальный клиентский запрос:

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

Если токен активен, Gigma вернёт настройки приложения:

{
	"wholesale": false
}

После этого получите каталог и убедитесь, что в нём есть нужные товары.

Готово

Приложение создано, склад подключён через интерфейс Gigma, App Token работает, а сервер проверяет и принимает событие об оплате.

Дальнейшие шаги