library.book.add

Scope: library

Кто может вызывать: Сотрудник. isActive=true — только модератор.

Создание книги. Не-модератор создаёт с active: false.

HTTP: POST

Побочные эффекты: Создаёт элемент iblock; HTML в annotation санитизируется.

Параметры метода

Параметр Тип Обяз. Описание
name string да Название книги
code string нет Символьный код (на add генерируется из name, если не передан)
sort int нет Индекс сортировки
annotation string нет Аннотация / описание (HTML санитизируется). Алиасы: description
categoryIds int[] нет ID разделов каталога. Алиасы: categories, categoryId
authorIds int[] нет ID авторов из library.enum.author.list (numeric id). Алиасы: authors
newAuthors string[] нет Имена новых авторов для создания
paperVersion bool нет Доступна бумажная версия. Алиасы: isPaperVersion
availableCopies int нет Количество бумажных экземпляров. Алиасы: paperVersionCount
showInCategoryRecommendations bool нет Показывать в рекомендациях категории. Алиасы: recommendedInCategories, recommendationsTop
electronicVersion bool нет Доступна электронная версия
electronicLinks object нет Ссылки на файлы: { pdf, epub, doc, zip }. Алиасы: electronicLinkPdf, …
electronicFileIds int[] нет ID файлов электронной книги (должны принадлежать пользователю или быть привязаны к книге). Алиасы: electronicVersionFileIds
audioVersion bool нет Доступна аудиоверсия
audioLinks object нет Ссылки: { mp3, mp4, m4b, mobi, ogg }. Алиасы: audioLinkMp3, …
audioFileIds int[] нет ID аудиофайлов. Алиасы: audioVersionFileIds
publishYear string нет Год издания
link string нет Внешняя ссылка на покупку
price string нет Цена
previewPictureId int нет ID файла обложки. Алиасы: image
isActive bool нет Опубликовать сразу (только модератор)

Допустимые расширения файлов

Поля *FileIds и previewPictureId — ID файлов из Bitrix (b_file), загруженных на портал заранее. Проверяются расширение, размер и доступ (файл создан вызывающим или уже привязан к книге при update).

Поле Расширения
electronicFileIds pdf, epub, mobi
audioFileIds mp3, mp4, m4b, ogg, mobi
previewPictureId jpg, jpeg, png, gif, webp

Объекты electronicLinks / audioLinks — внешние URL (не b_file); ключи объекта задают тип ссылки:

Объект Ключи
electronicLinks pdf, epub, doc, zip
audioLinks mp3, mp4, m4b, mobi, ogg

Неверное расширение или недоступный fileId → VALIDATION_ERROR (details.field).

Возвращаемые данные

Объект книги в result.result (для list — массив таких объектов; также total, next на уровне Bitrix result):

Поле Тип Описание
id int ID элемента каталога
name string Название
code string Символьный код
sort int Сортировка
active bool Опубликована
categoryIds int[] ID категорий
createdBy int ID создавшего пользователя
dateCreate string Дата создания (формат портала)
authors string[] Имена авторов (не enum id)
paperVersion bool Бумажная версия
paperVersionCount int Заданное число экземпляров
showInCategoryRecommendations bool В рекомендациях категории
electronicVersion bool Электронная версия
electronicFileIds int[] ID файлов e-book
audioVersion bool Аудиоверсия
audioFileIds int[] ID аудиофайлов
publishYear string Год издания
annotation string Описание
link string Внешняя ссылка
price string Цена
previewPictureId int ID обложки
rating float Средний рейтинг
voteCount int Число голосов
reviewsCount int Число отзывов
availableCopies int Доступно экземпляров сейчас
isTakenByUser bool Взята текущим пользователем

Ответ в конверте модуля: result.result, result.error.

Обработка ошибок

Справочник кодов: error-codes.md.

Код Описание
UNAUTHORIZED Пользователь не авторизован
ACCESS_DENIED Нет доступа к разделу «Библиотека»
VALIDATION_ERROR Пустой name, недоступный fileId, невалидный URL и т.п. (details.field, details.operation)
INTERNAL_ERROR Внутренняя ошибка при сохранении

Пример запроса (POST)

curl -X POST "https://76590.dev.wehive.digital/rest/1/{webhook_code}/library.book.add.json"
          -H "Content-Type: application/json"
          -H "Accept: application/json"
          --data '{
          "name": "REST docs full 20260827-105030",
          "code": "rest_docs_full_20260827_105030",
          "sort": 500,
          "annotation": "Полное описание книги для документации REST",
          "categoryIds": [
            83,
            84
          ],
          "authorIds": [
            571
          ],
          "newAuthors": [
            "REST Doc Author"
          ],
          "paperVersion": true,
          "availableCopies": 2,
          "showInCategoryRecommendations": true,
          "electronicVersion": true,
          "electronicLinks": {
            "pdf": "https://example.com/book.pdf",
            "epub": "https://example.com/book.epub"
          },
          "audioVersion": true,
          "audioLinks": {
            "mp3": "https://example.com/book.mp3"
          },
          "publishYear": "2026",
          "link": "https://example.com/buy",
          "price": "1500"
        }'

Пример ответа

{
          "result": {
            "result": {
              "id": 1591,
              "name": "REST docs full 20260827-105030",
              "code": "rest_docs_full_20260827_105030",
              "sort": 500,
              "active": false,
              "categoryIds": [
                83,
                84
              ],
              "createdBy": 1,
              "dateCreate": "27.08.2026 10:50:31",
              "authors": [
                "Harvard Business Review",
                "REST Doc Author"
              ],
              "paperVersion": true,
              "paperVersionCount": 2,
              "showInCategoryRecommendations": true,
              "electronicVersion": true,
              "electronicFileIds": [],
              "audioVersion": true,
              "audioFileIds": [],
              "publishYear": "2026",
              "annotation": "Полное описание книги для документации REST",
              "link": "https://example.com/buy",
              "price": "1500",
              "previewPictureId": 0,
              "rating": 0,
              "voteCount": 0,
              "reviewsCount": 0,
              "availableCopies": 2,
              "isTakenByUser": false
            },
            "error": null
          }
        }

Пример ошибки

{
          "result": {
            "result": null,
            "error": {
              "code": "VALIDATION_ERROR",
              "message": "Обязательный параметр name не указан или указан неверно.",
              "details": {
                "field": "name"
              }
            }
          }
        }

См. также

Предыдущая
library.book.get
Следующая
library.book.update