Создать раздел

POST /v1/lists/:iblockId/sections

Создаёт новый раздел в списке. Символьный код раздела передаётся полем sectionCode на верхнем уровне тела, вне обёртки fields, а поля раздела идут внутри fields в форме Битрикс24.

Параметры

Параметр Тип Обяз. Описание
iblockId (path) string да Числовой IBLOCK_ID или символьный код списка

Поля запроса (body)

Поле Тип Обяз. Описание
sectionCode string да Символьный код нового раздела. Передаётся на верхнем уровне тела, вне обёртки fields
fields object да Поля раздела в форме Битрикс24. Ключи внутри — в верхнем регистре с подчёркиванием
fields.NAME string да Название раздела
fields.SORT number нет Индекс сортировки в перечне разделов
fields.DESCRIPTION string нет Описание раздела
iblockSectionId number нет ID родительского раздела для вложенности. Значение 0 или отсутствие поля — раздел создаётся в корне списка. Список разделов: GET /v1/lists/:iblockId/sections
iblockTypeId string нет Тип инфоблока. Значения:
lists — обычные списки, по умолчанию
lists_socnet — списки рабочих групп
bitrix_processes — служебные бизнес-процессы

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/lists/23/sections \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sectionCode": "region_north",
    "fields": {
      "NAME": "Северный регион",
      "SORT": 100,
      "DESCRIPTION": "Заявки по северному региону"
    }
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/lists/23/sections \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sectionCode": "region_north",
    "fields": {
      "NAME": "Северный регион",
      "SORT": 100,
      "DESCRIPTION": "Заявки по северному региону"
    }
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/lists/23/sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sectionCode: 'region_north',
    fields: {
      NAME: 'Северный регион',
      SORT: 100,
      DESCRIPTION: 'Заявки по северному региону',
    },
  }),
})

const { data } = await res.json()
console.log('ID раздела:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/lists/23/sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sectionCode: 'region_north',
    fields: {
      NAME: 'Северный регион',
      SORT: 100,
      DESCRIPTION: 'Заявки по северному региону',
    },
  }),
})

const { data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.id number Идентификатор созданного раздела

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

JSON 
{
  "success": true,
  "data": {
    "id": 215
  }
}

Пример ответа при ошибке

400 — не передан обязательный параметр:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "`sectionCode` is required (the symbolic code of the new section)."
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_FIELDS Не передан sectionCode или объект fields
400 INVALID_IBLOCK_TYPE iblockTypeId не входит в набор lists, lists_socnet, bitrix_processes
403 BITRIX_ACCESS_DENIED Список не существует или у ключа нет прав на него
409 LISTS_MODULE_NOT_ENABLED На портале Битрикс24 не подключён модуль «Списки»
403 WRITE_BLOCKED_READONLY_KEY Ключ работает в режиме только чтения
403 SCOPE_DENIED Ключу не хватает скоупа lists
401 TOKEN_MISSING У ключа не настроены токены доступа

Полный список общих ошибок API — Ошибки.

Известные особенности

Вложенность через iblockSectionId. Раздел размещается внутри другого раздела, когда в iblockSectionId передан ID родителя. Без этого поля или при значении 0 раздел создаётся на верхнем уровне списка.

Смотрите также