Быстрый старт CMS

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

Такой сценарий подходит для переноса старого сайта, синхронизации с внешней системой и собственной редакторской панели.

Все запросы управления отправляйте с вашего сервера. Для них нужен Bearer сотрудника, полученный после входа сотрудника. Не передавайте этот токен в браузер или мобильное приложение.

Подготовка

Если Application ещё нет, создайте приложение. Сохраните из ответа application.id и application.token. Для страниц, блоков и меню склад не требуется.

Чтобы пройти все шаги, используйте Bearer сотрудника с правом edit-applications. Без него запросы управления блоками и меню вернут 403 Forbidden. Для создания страницы отдельное право edit-applications не требуется.

Перед началом подготовьте:

ID приложения (application.id);
Bearer этого сотрудника — с ним вы отправите запросы управления;
App Token (application.token) — с ним вы проверите результат;
постоянные ключи: slug страницы, identifier блока и slug корневого меню.

С Bearer сотрудника получите актуальные типы страницы и блока:

GET /api/page_types
GET /api/block_types

Если странице или блоку требуется изображение, сначала вызовите GET /api/file_types, затем загрузите файл через POST /api/files. file_type_id в примере условный: передайте значение из ответа справочника и не копируйте ID из примера загрузки файла.

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

В шаблоне маршрута /api/applications/{application_id}/blocks параметр {application_id} — это значение application.id.

Шаг 1. Создайте страницу

Страница подходит для статьи, новости, оферты или справочного материала.

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

{
	"application_id": 12,
	"page_type_id": 1,
	"is_page": true,
	"slug": "gigma-shop-legal-offer",
	"title": "Публичная оферта",
	"content": "<p>Текст оферты</p>"
}

В ответе сохраните page.id. Он понадобится для GET, PUT и DELETE /api/pages/{id}.

slug страницы уникален по всей базе, а не только внутри приложения. Добавляйте к нему префикс проекта или сайта: например, gigma-shop-about вместо about.

Полный контракт: создание и изменение страниц.

Шаг 2. Создайте контентный блок

Блок подходит для части интерфейса, которую нужно менять независимо от страницы: объявления, баннера, заголовка или изображения.

В примере используется текстовый тип. Получите его настоящий ID через GET /api/block_types.

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

{
	"block_type_id": 1,
	"name": "Объявление на главной",
	"identifier": "home-announcement",
	"link": null,
	"avatar_id": null,
	"file_id": null,
	"text": "Доставка заказов работает ежедневно",
	"parent_id": null
}

Сохраните block.id. Поле identifier задаёте вы: используйте его как постоянный ключ в коде сайта.

После создания block.code может быть null: этот метод не принимает и не генерирует код. Для нового сайта он не нужен. Если существующая интеграция читает блоки по code, назначьте свободный числовой код отдельным PUT.

Gigma не проверяет уникальность identifier. Перед созданием получите GET /api/applications/{application_id}/blocks и убедитесь, что выбранный ключ не занят внутри этого Application. Если совпадений несколько, API чтения вернёт первый найденный блок.

Для составной секции сначала создайте родительский блок, затем передайте его ID в parent_id дочерних блоков. Передавайте parent_id только блока того же Application: API проверяет, что ID существует, но не проверяет принадлежность родителя приложению.

Полный контракт: управление контентными блоками.

Шаг 3. Создайте меню

Сначала создайте корневой пункт. Его slug станет именем дерева меню.

Gigma не проверяет уникальность slug. Используйте отдельный slug для каждого корневого меню внутри Application и не назначайте это значение дочерним пунктам: API чтения возвращает первый найденный пункт с таким slug.

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

{
	"name": "Главное меню",
	"slug": "navpanel"
}

Сохраните ID корневого пункта из ответа и передайте его в parent_id дочернего пункта:

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

{
	"name": "Каталог",
	"slug": "/catalog",
	"parent_id": 501
}

В примере 501 — ID корневого пункта из предыдущего ответа. Не переносите это значение в свою конфигурацию. Передавайте parent_id только пункта того же Application: API проверяет существование ID, но не принадлежность родителя приложению.

Если order не передан, Gigma добавит новый пункт в конец текущего уровня.

Полный контракт: управление меню.

Шаг 4. Получите страницу

Отправьте запрос с App Token. Такой же запрос будет использовать ваш сайт.

GET /api/counterparty/pages/gigma-shop-legal-offer HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json

В ответ вы получите объект page с заголовком и HTML-содержимым.

Сравните page.slug с запрошенным значением. При неизвестном slug метод может вернуть резервную страницу вместо 404, поэтому не показывайте ответ пользователю, если значения не совпадают.

Полный контракт: получение страниц.

Шаг 5. Получите блок

Запрашивайте блок по постоянному identifier, а не по внутреннему ID или code, который после создания может быть null.

GET /api/counterparty/blocks/id/home-announcement HTTP/1.1
Host: api.gigma.ru
Token: <application_token>
Accept: application/json

Полный шаблон маршрута: GET /api/counterparty/blocks/id/{identifier}.

Полезное содержимое находится в text, file или link — в зависимости от типа блока. Дочерние элементы составной секции находятся в children.

Перед показом сравните block.identifier с запрошенным ключом. Если блок не найден, покажите резервный вариант секции.

Полный контракт: получение контентных блоков.

Шаг 6. Получите меню

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

В menuItems Gigma вернёт корневой пункт и дерево children. Проверяйте каждый url перед переходом и разрешайте только ожидаемые маршруты.

Если меню не найдено или API временно недоступен, покажите базовую навигацию, встроенную в ваш продукт.

Полный контракт: получение меню.

Готово

Вы создали страницу, изменяемую секцию и навигацию, а затем проверили все три объекта запросами с App Token.

Теперь сайт может получать контент из Gigma при открытии страницы или из собственного кэша.

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

Добавьте изображения и документы через POST /api/files — Файлы и медиа.
Подключите рекламный слайдер — Рекламные слайды.

Полные контракты управления и чтения указаны после соответствующих шагов.

Что учесть при синхронизации

Храните соответствие ID объекта в вашей системе и ID Gigma.

Если записывающий запрос завершился сетевой ошибкой, сначала проверьте результат:

страницу — запросом GET /api/counterparty/pages/{slug} и сравнением page.slug;
блок — запросом GET /api/counterparty/blocks/id/{identifier} и сравнением block.identifier;
корневой пункт меню — запросом GET /api/applications/{application_id}/menu_items с Bearer сотрудника: найдите объект в menuItems[] по уникальному slug и сохраните его id;
дочерний пункт меню — найдите внутри children нужного корневого пункта объект по slug и сохраните его id.

Ответ списка пунктов меню не содержит parent_id, поэтому не используйте это поле для восстановления ID. В обоих маршрутах {application_id} — значение application.id.

Если объект уже существует, сохраните его ID и не повторяйте POST. Для изменения существующей страницы, блока или пункта меню используйте соответствующий PUT. Повторяйте создание только после того, как убедились, что объект не появился.

CMS не отправляет отдельный вебхук об изменении контента. Событие order.paid относится к заказам и не подходит для обновления кэша CMS. После своего запроса на изменение сбрасывайте кэш сразу; если контент меняют сотрудники в интерфейсе Gigma, обновляйте его по расписанию.

Разделяйте кэш по Application или App Token. Не используйте ответ одного приложения при обслуживании другого.

Поле content страницы содержит HTML. Очищайте его перед выводом. Для блоков и меню проверяйте ссылки и показывайте резервный вариант, если объект не найден.

У методов страниц нет отдельной проверки принадлежности объекта вашему проекту. Храните ID страницы, полученный из ответа своего проекта, и не подставляйте чужие значения. При чтении и изменении существующего блока или пункта меню API проверяет его связь с Application из адреса. При создании и обновлении передавайте только собственные parent_id, avatar_id, file_id и preview_id: для этих полей API проверяет существование ID, но не все связи с проектом и приложением. Bearer сотрудника выдавайте только серверному коду, которому доверяете.