Поля товара

GET /v1/catalog-products/fields

Возвращает справочник полей товара с подписями, типами, признаками «только для чтения» и «допускает null», описаниями и словарями enum там, где набор значений фиксирован, список полей, доступных для агрегации, а также операции, доступные в пакетном запросе.

Примеры

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

curl "https://vibecode.bitrix24.tech/v1/catalog-products/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl "https://vibecode.bitrix24.tech/v1/catalog-products/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-products/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-products/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

data.fields — объект, ключ которого совпадает с именем поля, а значение содержит тип, признаки доступности на запись, подпись для отображения и — у полей с фиксированным набором значений — их словарь. Состав ключей разобран в таблице после списка полей. data.aggregatable — поля, по которым работает агрегация. data.batch — операции, доступные в пакетном запросе.

¹ iblockId доступен для записи только при создании (createOnly) — в справочнике приходит с readonly: false и createOnly: true.

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

{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Идентификатор товара"
      },
      "iblockId": {
        "type": "number",
        "readonly": false,
        "createOnly": true,
        "label": "ID каталога",
        "description": "Каталог, которому принадлежит товар. Список: GET /v1/catalogs. Задаётся только при создании — смена через PATCH отклоняется, товар нельзя перенести между каталогами."
      },
      "purchasingPrice": {
        "type": "number",
        "readonly": false,
        "nullable": true,
        "label": "Закупочная цена",
        "description": "Закупочная цена товара; null, если не задана."
      },
      "previewTextType": {
        "type": "string",
        "readonly": false,
        "label": "Формат текста анонса",
        "description": "Формат поля previewText.",
        "enum": [
          {
            "value": "text",
            "label": "Текст"
          },
          {
            "value": "html",
            "label": "HTML"
          }
        ]
      }
    },
    "aggregatable": [
      "purchasingPrice",
      "quantity",
      "iblockSectionId"
    ],
    "batch": [
      "create",
      "update",
      "delete"
    ]
  }
}

Пример сокращён до четырёх полей — по одному на каждый признак (readonly, createOnly, nullable) и одно с машиночитаемым словарём enum. В ответе приходят все сорок два.

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

403 — нет скоупа:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'catalog' scope"
  }
}

Ошибки

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

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

Запись зависит от управления складом. Поля quantity, purchasingPrice и purchasingCurrency помечены в справочнике как доступные для записи, но при включённом на портале управлении складом не применяются при создании и изменении товара — остатки и закупочные цены ведутся складскими документами.

Часть полей не приходит в списке по умолчанию. Символьный код code, габариты width, height, length, тексты previewText, detailText, сортировка sort и ещё ряд полей из справочника не возвращаются в ответе GET /v1/catalog-products без явного ?select=. Перечислите нужные имена в ?select=, чтобы получить их в списке — эти поля доступны и в фильтрации, и в сортировке. В ответе одного товара GET /v1/catalog-products/:id они возвращаются всегда.

Изображения и привязка к разделам не фильтруются. previewPicture и detailPicture задаются при создании и обновлении и возвращаются в ответах — в GET /v1/catalog-products/:id и в списке по явному ?select=, — но не поддерживают фильтрацию и сортировку. Поле iblockSection принимает массив ID разделов при создании и обновлении, но не возвращается в GET /v1/catalog-products/:id или списке. Для чтения, фильтрации и сортировки доступен скалярный iblockSectionId с ID основного раздела.

Ответ GET /:id содержит поля сверх справочника. Запрос одного товара дополнительно возвращает тип товара type и пользовательские свойства каталога вида propertyNNN. Они не входят в справочник полей GET /v1/catalog-products/fields и недоступны для фильтрации и сортировки.

Каталог товара (iblockId) неизменяем. Каталог выбирается при создании. Битрикс24 не переносит товар между каталогами через обновление. PATCH со сменой iblockId отклоняется с 400 READONLY_FIELD — раньше такой запрос возвращал 200, но товар оставался в прежнем каталоге (ложный успех).

Поля аудита защищены. createdBy и modifiedBy заполняются Битрикс24 и не принимаются при создании и обновлении — попытка передать их отклоняется с 400 READONLY_FIELD.

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

• Список товаров
• Создать товар
• Поиск товаров
• Цены каталога
• Справочник сущностей