Для AI-агентов: markdown этой страницы — /docs-content/entities/catalog-skus.md индекс документации — /llms.txt

Головные товары (SKU)

Головной товар — общая карточка товара с вариациями: название, описание и раздел каталога у него одни, а размеры, цвета и другие варианты хранятся в вариациях товара. Раздел создаёт, читает, изменяет и удаляет головные товары.

Битрикс24 API: catalog.product.sku.* Скоуп: catalog

Создать головной товар

POST /v1/catalog-skus

Создаёт головной товар в товарном каталоге — общую карточку, к которой затем привязываются вариации. Поля передаются плоско в корне JSON.

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

Поле Тип Обяз. Описание
name string да Название головного товара
iblockId number да ID товарного каталога. Список: GET /v1/catalogs. Каталог вариаций — тот, у которого заполнен productIblockId, — не подходит
active boolean нет Активен ли товар. По умолчанию true
iblockSectionId number нет ID основного раздела каталога. Список: GET /v1/catalog-sections
iblockSection number[] нет Массив ID всех разделов, к которым привязан товар. Список: GET /v1/catalog-sections
code string нет Символьный код товара
xmlId string нет Внешний код. Без него Битрикс24 записывает в поле id товара строкой
sort number нет Порядок сортировки. По умолчанию 500
dateActiveFrom datetime нет Дата начала активности
dateActiveTo datetime нет Дата окончания активности
previewText string нет Текст анонса
previewTextType string нет Формат текста анонса: text или html. По умолчанию text
detailText string нет Подробное описание
detailTextType string нет Формат подробного описания: text или html. По умолчанию text
previewPicture object нет Картинка анонса: { "fileData": ["имя.png", "<base64>"] }
detailPicture object нет Детальная картинка, тот же формат
propertyNNN string нет Значение свойства каталога, где NNN — id свойства из GET /v1/catalog-product-properties: "property301": "хлопок"

Поля type, available и bundle вычисляет Битрикс24 — в теле запроса они отклоняются с 400 READONLY_FIELD.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-skus" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Футболка базовая",
    "iblockId": 25,
    "active": true
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-skus" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Футболка базовая",
    "iblockId": 25,
    "active": true
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-skus', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Футболка базовая',
    iblockId: 25,
    active: true,
  }),
})

const { success, data } = await res.json()
console.log('ID головного товара:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-skus', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Футболка базовая',
    iblockId: 25,
    active: true,
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Полный объект созданного головного товара. Набор полей — как у GET /v1/catalog-skus/:id

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

Показаны основные поля, свойства propertyNNN опущены. У только что созданного головного товара type равен 6.

JSON 
{
  "success": true,
  "data": {
    "id": 7203,
    "iblockId": 25,
    "iblockSectionId": null,
    "iblockSection": null,
    "name": "Футболка базовая",
    "type": 6,
    "active": true,
    "available": false,
    "bundle": false,
    "code": null,
    "xmlId": "7203",
    "sort": 500,
    "previewText": null,
    "previewTextType": "text",
    "detailText": null,
    "detailTextType": "text",
    "createdBy": 1295,
    "modifiedBy": 1295,
    "dateCreate": "2026-10-08T18:45:34.000Z",
    "timestampX": "2026-10-08T18:45:34.000Z"
  }
}

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"name\" is required to create catalogSku."
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_FIELDS Не передано обязательное поле name или iblockId — сообщение называет его. Запрос отклоняется до обращения к Битрикс24
400 READONLY_FIELD В теле передано поле только для чтения: type, available, bundle
422 BITRIX_ERROR iblockId указывает на каталог вариаций (productType is not allowed for this catalog)
422 BITRIX_ERROR iblockId не является каталогом (iblock is not catalog)
403 SCOPE_DENIED Ключу не хватает скоупа catalog
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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

Тип меняется после привязки вариации. Новый головной товар приходит с type: 6. Когда к нему привязана первая вариация — POST /v1/catalog-offers с parentId, — тип становится 3. Отдельно менять тип не нужно, передать его нельзя.

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