Управление контентными блоками

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

Отправляйте запросы с вашего сервера и передавайте Bearer сотрудника. Чтобы получить готовый блок на сайте, используйте API получения блоков с App Token.

Для первого сценария создания контента откройте быстрый старт CMS.

Как устроен блок

Тип блока определяет, где хранится содержимое:

для текста используйте text;
для изображения используйте file_id;
для видео или ссылки используйте link.

Задайте identifier, если сайт должен получать блок по постоянному и понятному ключу. Например, для главного баннера можно использовать home-hero и запрашивать его методом GET /api/counterparty/blocks/id/{identifier}.

Gigma не проверяет уникальность identifier. Перед созданием получите блоки приложения и убедитесь, что ключ не занят. Если внутри одного Application есть несколько блоков с одинаковым identifier, API чтения вернёт первый найденный блок.

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

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

Подготовка

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

ID приложения;
Bearer сотрудника с правом edit-applications;
block_type_id из GET /api/block_types;
ID файлов, если блоку нужны изображение или аватар.

Файлы загружайте заранее через POST /api/files. Передавайте только ID файлов своего проекта: API проверяет существование avatar_id и file_id, но не проверяет их принадлежность проекту.

Что можно сделать

создать блок — POST /api/applications/{id}/blocks;
получить список блоков — GET /api/applications/{id}/blocks;
получить один блок вместе с родителем и дочерними элементами — GET /api/applications/{application_id}/blocks/{id};
обновить блок — PUT /api/applications/{application_id}/blocks/{id};
удалить блок — DELETE /api/applications/{application_id}/blocks/{id};
получить список для административного интерфейса — GET /api/tables/applications/{id}/blocks;
посмотреть историю — GET /api/applications/{application_id}/blocks/{id}/history.

Создать блок

Метод: POST
URL: https://api.gigma.ru/api/applications/{id}/blocks
Авторизация: Bearer сотрудника
Headers: Authorization: Bearer {token}, Content-Type: application/json
Успешный ответ: 200

Чтобы создать блок, передайте его тип, название и содержимое. Для каждого типа используйте только подходящее поле: text, file_id или link.

Если сайт будет получать блок по постоянному ключу, передайте identifier. До создания проверьте, что такого ключа ещё нет среди блоков приложения.

Параметры пути

id (integer, обязательный) — ID приложения.

Параметры запроса

block_type_id (integer, обязательный) — ID типа из GET /api/block_types.
name (string, обязательный) — название блока.
identifier (string, необязательный) — постоянный ключ для API чтения или null; уникальность API не проверяет.
link (string, необязательный) — URL; обязателен для видео и ссылки.
avatar_id (integer, необязательный) — ID файла аватара или null.
file_id (integer, необязательный) — ID файла; обязателен для типа «Картинка».
text (string, необязательный) — содержимое; обязательно для текстовых типов.
parent_id (integer, необязательный) — ID родительского блока или null; используйте родителя того же приложения.

Пример запроса

{
	"block_type_id": 3,
	"name": "Баннер на главной",
	"identifier": "home-hero",
	"link": null,
	"avatar_id": 2828,
	"file_id": 2827,
	"text": null,
	"parent_id": 8
}

Ответ

{
	"block": {
		"id": 10,
		"code": null,
		"identifier": "home-hero",
		"name": "Баннер на главной",
		"avatar": {
			"id": 2828,
			"name": "hero-avatar.png",
			"type": {
				"id": 1,
				"name": "Документ",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"path": "https://api.gigma.ru/storage/uploads/hero-avatar.png",
			"link": null,
			"created_at": "2024-04-14T20:04:32.000000Z",
			"updated_at": "2024-04-14T20:04:32.000000Z"
		},
		"block_type": {
			"id": 3,
			"name": "Картинка",
			"avatar": "https://api.gigma.ru/storage/uploads/image-profile-2.svg",
			"created_at": "2025-01-23T09:47:38.000000Z"
		},
		"link": null,
		"file": {
			"id": 2827,
			"name": "hero.png",
			"type": {
				"id": 1,
				"name": "Документ",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"path": "https://api.gigma.ru/storage/uploads/hero.png",
			"link": null,
			"created_at": "2025-01-27T14:17:14.000000Z",
			"updated_at": "2025-01-27T14:17:14.000000Z"
		},
		"text": null,
		"created_at": "2025-01-27T14:17:14.000000Z"
	}
}

В ответ вы получите созданный блок без полей parent и children. Сохраните block.id для обновления, удаления и отдельного получения блока со связями. Поле block.code после создания может быть null.

Ошибки

401 — Bearer отсутствует или недействителен.
403 — у сотрудника нет права edit-applications или приложение принадлежит другому проекту.
404 — приложение не найдено.
422 — обязательное поле отсутствует, тип, файл или родитель не найдены либо данные не прошли валидацию.

Получить список блоков

Метод: GET
URL: https://api.gigma.ru/api/applications/{id}/blocks
Авторизация: Bearer сотрудника
Headers: Authorization: Bearer {token}
Успешный ответ: 200

Чтобы получить все блоки приложения, отправьте запрос с его ID. Метод возвращает плоский массив без полей parent и children. Для получения связей вызовите метод одного блока.

Параметры пути

id (integer, обязательный) — ID приложения.

Параметры запроса

query (string, необязательный) — поиск по названию блока.

Ответ

[
	{
		"id": 8,
		"code": null,
		"identifier": "home",
		"name": "Главная",
		"avatar": null,
		"block_type": {
			"id": 1,
			"name": "Обычный текст",
			"avatar": "https://api.gigma.ru/storage/uploads/image-profile-1.svg",
			"created_at": "2025-01-23T09:47:38.000000Z"
		},
		"link": null,
		"file": null,
		"text": "Главная секция",
		"created_at": "2025-01-27T13:03:19.000000Z"
	}
]

Поля ответа

id — ID блока.
code — числовой код в строковом формате или null.
identifier — постоянный ключ или null.
name — название.
avatar — файл аватара или null.
block_type — тип блока.
link — URL или null.
file — прикреплённый файл или null.
text — текст или null.
created_at — дата создания в ISO 8601.

Ошибки

401 — Bearer отсутствует или недействителен.
403 — у сотрудника нет права просмотра приложений или приложение принадлежит другому проекту.
404 — приложение не найдено.

Получить блок

Метод: GET
URL: https://api.gigma.ru/api/applications/{application_id}/blocks/{id}
Авторизация: Bearer сотрудника
Headers: Authorization: Bearer {token}
Успешный ответ: 200

Чтобы получить один блок для просмотра или редактирования, передайте ID приложения и ID блока. В этом ответе Gigma добавит родителя и дочерние блоки.

Параметры пути

application_id (integer, обязательный) — ID приложения.
id (integer, обязательный) — ID блока.

Пример запроса

GET /api/applications/30/blocks/10 HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <employee_token>
Accept: application/json

Ответ

{
	"block": {
		"id": 10,
		"code": "10",
		"identifier": "home-hero",
		"name": "Баннер на главной",
		"avatar": {
			"id": 2828,
			"name": "hero-avatar.png",
			"type": {
				"id": 1,
				"name": "Документ",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"path": "https://api.gigma.ru/storage/uploads/hero-avatar.png",
			"link": null,
			"created_at": "2024-04-14T20:04:32.000000Z",
			"updated_at": "2024-04-14T20:04:32.000000Z"
		},
		"block_type": {
			"id": 3,
			"name": "Картинка",
			"avatar": "https://api.gigma.ru/storage/uploads/image-profile-2.svg",
			"created_at": "2025-01-23T09:47:38.000000Z"
		},
		"link": null,
		"file": {
			"id": 2827,
			"name": "hero.png",
			"type": {
				"id": 1,
				"name": "Документ",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"path": "https://api.gigma.ru/storage/uploads/hero.png",
			"link": null,
			"created_at": "2025-01-27T14:17:14.000000Z",
			"updated_at": "2025-01-27T14:17:14.000000Z"
		},
		"text": null,
		"parent": {
			"id": 8,
			"code": "1",
			"name": "Главная"
		},
		"children": [],
		"created_at": "2025-01-27T14:17:14.000000Z"
	}
}

Поля ответа

В ответе есть те же поля, что в списке, а также:

parent — родительский блок или null;
children — дочерние блоки; для каждого дочернего блока Gigma также возвращает его связи.

Ошибки

401 — Bearer отсутствует или недействителен.
403 — у сотрудника нет права просмотра приложений или приложение принадлежит другому проекту.
404 — приложение или блок не найдены либо блок относится к другому приложению.

Обновить блок

Метод: PUT
URL: https://api.gigma.ru/api/applications/{application_id}/blocks/{id}
Авторизация: Bearer сотрудника
Headers: Authorization: Bearer {token}, Content-Type: application/json
Успешный ответ: 200

Чтобы изменить блок, передайте ID приложения, ID блока и только те поля, которые нужно обновить. Если меняете тип блока, одновременно передайте подходящее содержимое: text, file_id или link.

Параметры пути

application_id (integer, обязательный) — ID приложения.
id (integer, обязательный) — ID блока.

Параметры запроса

block_type_id (integer, необязательный) — новый ID типа блока.
name (string, необязательный) — новое название.
code (integer, необязательный) — новый свободный числовой код. В ответе он вернётся строкой.
identifier (string, необязательный) — постоянный ключ для API чтения или null; уникальность API не проверяет.
link (string, необязательный) — URL; обязателен при переходе на тип видео или ссылки.
avatar_id (integer, необязательный) — ID файла аватара или null.
file_id (integer, необязательный) — ID файла; обязателен при переходе на тип «Картинка».
text (string, необязательный) — содержимое; обязательно при переходе на текстовый тип.
parent_id (integer, необязательный) — ID родительского блока или null; используйте родителя того же приложения.

Пример запроса

{
	"block_type_id": 3,
	"name": "Баннер на главной — лето",
	"code": 10,
	"identifier": "home-hero",
	"link": null,
	"avatar_id": 2828,
	"file_id": 2827,
	"text": null,
	"parent_id": 8
}

Ответ

{
	"block": {
		"id": 10,
		"code": "10",
		"identifier": "home-hero",
		"name": "Баннер на главной — лето",
		"avatar": {
			"id": 2828,
			"name": "hero-avatar.png",
			"type": {
				"id": 1,
				"name": "Документ",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"path": "https://api.gigma.ru/storage/uploads/hero-avatar.png",
			"link": null,
			"created_at": "2024-04-14T20:04:32.000000Z",
			"updated_at": "2024-04-14T20:04:32.000000Z"
		},
		"block_type": {
			"id": 3,
			"name": "Картинка",
			"avatar": "https://api.gigma.ru/storage/uploads/image-profile-2.svg",
			"created_at": "2025-01-23T09:47:38.000000Z"
		},
		"link": null,
		"file": {
			"id": 2827,
			"name": "hero.png",
			"type": {
				"id": 1,
				"name": "Документ",
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"path": "https://api.gigma.ru/storage/uploads/hero.png",
			"link": null,
			"created_at": "2025-01-27T14:17:14.000000Z",
			"updated_at": "2025-01-27T14:17:14.000000Z"
		},
		"text": null,
		"created_at": "2025-01-27T14:17:14.000000Z"
	}
}

В ответ вы получите блок с обновлёнными данными без полей parent и children. Чтобы перечитать связи, вызовите GET /api/applications/{application_id}/blocks/{id}.

Ошибки

401 — Bearer отсутствует или недействителен.
403 — у сотрудника нет права edit-applications или приложение принадлежит другому проекту.
404 — приложение или блок не найдены либо блок относится к другому приложению.
422 — code уже занят, тип, файл или родитель не найдены либо данные не прошли валидацию.

Удалить блок

Метод: DELETE
URL: https://api.gigma.ru/api/applications/{application_id}/blocks/{id}
Авторизация: Bearer сотрудника
Headers: Authorization: Bearer {token}
Успешный ответ: 200

Чтобы удалить блок, передайте ID приложения и ID блока. Сначала проверьте дочерние связи и убедитесь, что сайт больше не обращается к его identifier.

Параметры пути

application_id (integer, обязательный) — ID приложения.
id (integer, обязательный) — ID блока.

Ответ

{
	"message": "Block successfully deleted"
}

Ошибки

401 — Bearer отсутствует или недействителен.
403 — у сотрудника нет права edit-applications или приложение принадлежит другому проекту.
404 — приложение или блок не найдены либо блок относится к другому приложению.

Получить блоки для таблицы

Метод: GET
URL: https://api.gigma.ru/api/tables/applications/{id}/blocks
Авторизация: Bearer сотрудника
Headers: Authorization: Bearer {token}
Успешный ответ: 200

Этот метод пригодится для административного списка блоков. Gigma вернёт конфигурацию столбцов, строки и данные пагинации.

Параметры пути

id (integer, обязательный) — ID приложения.

Параметры запроса

query (string, необязательный) — поиск по названию блока.

Пример запроса

GET /api/tables/applications/30/blocks?query=баннер HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <employee_token>
Accept: application/json

Ответ

{
	"columns": [
		{
			"id": 151,
			"table_id": 19,
			"order": 2,
			"key": "name",
			"has_icon": 1,
			"text": "Название"
		}
	],
	"blocks": [
		{
			"id": {
				"icon": null,
				"value": 10,
				"url": ""
			},
			"date": "2025-01-27T14:17:14.000000Z",
			"name": {
				"icon": "https://api.gigma.ru/storage/uploads/default.svg",
				"value": "Баннер на главной"
			},
			"path": "> Главная > Баннер на главной",
			"block_type": {
				"icon": "https://api.gigma.ru/storage/uploads/image-profile-2.svg",
				"value": "Картинка"
			},
			"creator": {
				"icon": "https://api.gigma.ru/storage/uploads/user.png",
				"value": "Воронова София",
				"link": "/users/list-users/66"
			}
		}
	],
	"pagination": {
		"total": 1,
		"per_page": 10,
		"current_page": 1,
		"last_page": 1,
		"from": 1,
		"to": 1
	}
}

Ошибки

401 — Bearer отсутствует или недействителен.
403 — у сотрудника нет права просмотра приложений или приложение принадлежит другому проекту.
404 — приложение не найдено.

Получить историю блока

Метод: GET
URL: https://api.gigma.ru/api/applications/{application_id}/blocks/{id}/history
Авторизация: Bearer сотрудника
Headers: Authorization: Bearer {token}
Успешный ответ: 200

Чтобы получить журнал действий с блоком, передайте ID приложения и ID блока.

Параметры пути

application_id (integer, обязательный) — ID приложения.
id (integer, обязательный) — ID блока.

Ответ

{
	"histories": [
		{
			"id": 2174,
			"icon": "check",
			"color": "primary",
			"title": "Создание",
			"description": "Создание: Воронова София",
			"datetime": "23.01.2025 15:57"
		}
	],
	"historiesCount": 1
}

Ошибки

401 — Bearer отсутствует или недействителен.
404 — приложение или блок не найдены.