API: Списки, поля, элементы, вложения

API: Списки, поля, элементы, вложения

Требуется авторизация. Права наследуются от узла-родителя (nodeId).

Списки — /api/v1/lists

Метод	Путь	Право на узел	Описание
GET	/lists?nodeId={uuid}	view	Списки узла
POST	/lists	edit	Создать список
GET	/lists/{id}	view	Список с полями
PATCH	/lists/{id}	edit	Обновить
DELETE	/lists/{id}	delete	Удалить

Тело создания:

{
  "nodeId": "uuid",
  "title": "Задачи",
  "slug": "tasks",
  "description": ""
}

Поля — /api/v1/lists/{listId}/fields

Метод	Путь	Право	Описание
GET	/lists/{listId}/fields	view	Поля списка
POST	/lists/{listId}/fields	edit	Добавить поле
PATCH	/lists/{listId}/fields/{fieldId}	edit	Обновить
DELETE	/lists/{listId}/fields/{fieldId}	edit	Удалить

Типы полей: text, multiline_text, html_text, choice, number, date, datetime, boolean, lookup, person, link.

Тип	settings	Значение в fieldValues
text	—	строка
multiline_text	—	строка
html_text	—	HTML (санитизация на сервере)
choice	{ choices: ["A","B"] }	одна из choices
number	—	число
date	—	YYYY-MM-DD
datetime	—	ISO 8601
boolean	—	true / false
lookup	{ lookupNodeId?, lookupListId, lookupFieldId? }	{ itemId, display }
person	{ allowUsers?, allowGroups?, allowMultiple? }	{ principalType, id, display } или массив таких объектов
link	—	{ url, description? }

Для choice укажите settings.choices — массив строк.

Для lookup укажите settings.lookupListId (обязательно), опционально settings.lookupNodeId (узел списка-источника, для UI настроек) и settings.lookupFieldId — поле отображения в целевом списке.

Для person (principalType: user или group):

• allowUsers / allowGroups — ограничить типы субъектов (по умолчанию оба true);
• allowMultiple — множественный выбор (true → массив значений, иначе один объект).

Поиск для person

GET /lists/{listId}/person-options?fieldId={uuid}&q=текст&excludeIds=id1,id2

Поиск пользователей по ФИО (display_name), логину и email. Группы — по имени и описанию.
excludeIds — уже выбранные субъекты (для множественного выбора).

Возвращает до 15 субъектов: [{ principalType, id, display, subtitle?, email? }].

Поиск для lookup

GET /lists/{listId}/lookup-options?targetListId={uuid}&q=текст&lookupFieldId={uuid}

Возвращает объект:

{
  "options": [{ "itemId": "uuid", "display": "Текст" }],
  "accessDenied": false,
  "message": null
}

При отсутствии доступа к целевому списку HTTP 200, accessDenied: true, options: [] и понятное message (без 403/500).

Элементы — /api/v1/lists/{listId}/items

Метод	Путь	Право	Описание
GET	/lists/{listId}/items	view	Элементы (пагинация)
POST	/lists/{listId}/items	add	Создать
GET	/lists/{listId}/items/{itemId}	view	Один элемент
PATCH	/lists/{listId}/items/{itemId}	edit	Обновить (merge: только переданные поля)
DELETE	/lists/{listId}/items/{itemId}	delete	Удалить
POST	/lists/{listId}/items/quick-edit	edit/add	Пакетное быстрое редактирование

PATCH merge

PATCH принимает частичный объект fieldValues: сервер объединяет переданные ключи с существующими field_values элемента, затем валидирует полный набор по схеме списка. Непереданные поля не обнуляются.

Quick Edit batch

POST /lists/{listId}/items/quick-edit — сохранение изменений из режима быстрого редактирования UI.

Тело запроса:

{
  "updates": [
    { "id": "uuid", "fieldValues": { "field-uuid": "новое значение" } }
  ],
  "creates": [
    { "clientRowId": "tmp-1", "fieldValues": { "title-field-uuid": "Новая задача" } }
  ]
}

Ответ:

{
  "updated": [{ "id": "...", "field_values": {} }],
  "created": [{ "clientRowId": "tmp-1", "id": "...", "field_values": {} }],
  "errors": [{ "itemId": "...", "clientRowId": "...", "fieldId": "...", "message": "..." }]
}

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

Значения полей — объект fieldValues, ключи — UUID полей:

{
  "fieldValues": {
    "field-uuid-1": "Текст",
    "field-uuid-2": 42
  }
}

Вложения

Метод	Путь	Право	Описание
GET	/lists/{listId}/items/{itemId}/attachments	view	Список файлов
POST	/lists/{listId}/items/{itemId}/attachments	add	Загрузить (multipart, поле file)
GET	/attachments/{id}/download	view	Скачать файл
DELETE	/lists/{listId}/items/{itemId}/attachments/{id}	delete	Удалить

Файлы хранятся в SeaweedFS (S3), клиент получает их только через API.

События и Event Receivers

При создании/изменении/удалении элементов диспетчер отправляет:

• listItem.created
• listItem.updated
• listItem.deleted

Обработчики для конкретного списка настраиваются на вкладке Обработчики в UI списка (требуется portal_admin + право edit на список) или через API с config.listId.

Подробнее: Event Receivers.