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

Поля товаров элемента

GET /v1/items/:entityTypeId/:id/products/fields

Возвращает описание полей товарных позиций элемента: названия, типы, доступность для чтения и записи.

Сумма скидки называется discount — как в данных и при записи. Прежнее имя discountSum осталось устаревшим псевдонимом: оно по-прежнему приходит в этом справочнике и принимается при записи, поэтому код, написанный по старому списку полей, продолжает работать. В самих товарных позициях приходит только discount — переходите на него.

Параметры

Параметр Тип Обяз. Описание
entityTypeId (path) number да ID типа смарт-процесса
id (path) number да ID элемента

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/items/156/741/products/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

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

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

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

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

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

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

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

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

Поля ответа

Поле Тип RO Обяз. Описание
id integer да ID позиции
productId integer да ID товара. Каталог: GET /v1/products
productName string Название товара
price double Цена
quantity double Количество
discount double Сумма скидки. Учитывается при discountTypeId равном 1
discountSum double Устаревший псевдоним discount — принимается при записи, в товарных позициях не приходит
discountRate double Процент скидки. Учитывается при discountTypeId равном 2
discountTypeId integer Как задана скидка: 1 — суммой в поле discount, 2 — процентом в поле discountRate. По умолчанию 2
taxRate double Налог (%)
taxIncluded char Налог включён в цену (Y/N)
priceExclusive double да Цена без налога со скидкой
priceNetto double да Цена нетто
priceBrutto double да Цена брутто
measureCode integer Код единицы измерения
measureName string да Единица измерения
customized char да Изменён (Y/N)
sort integer Сортировка
type integer да Тип
storeId integer да ID склада
ownerId integer да ID владельца (элемента)
ownerType string да Тип владельца
priceAccount double да Цена в валюте отчёта
xmlId string да Внешний код позиции

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

Показаны 6 полей из 24 (23 имени товарной позиции плюс устаревший псевдоним discountSum). Каждое поле описано ключами type, isRequired, isReadOnly, isImmutable, isMultiple, isDynamic, title. Полный список полей — в таблице выше.

JSON 
{
  "success": true,
  "data": {
    "id": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "ID", "description": "Row identity. Read-only as an attribute, and NOT a handle for editing: PUT /products does not preserve it — a row whose fields change comes back with a new id even if the previous one was sent. To edit a row and keep its id use PATCH /products/{rowId}." },
    "ownerId": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": true, "isMultiple": false, "isDynamic": false, "title": "ID владельца" },
    "ownerType": { "type": "string", "isRequired": false, "isReadOnly": true, "isImmutable": true, "isMultiple": false, "isDynamic": false, "title": "Тип владельца" },
    "productId": { "type": "integer", "isRequired": true, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Товар" },
    "price": { "type": "double", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Цена" },
    "priceExclusive": { "type": "double", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Цена без налога со скидкой" }
  }
}

Про id. Переданный id в элементах PUT /v1/items/:entityTypeId/:id/products не гарантирует прежний идентификатор позиции: неизменённая позиция получает прежний id и без этого поля, а изменённая приходит с новым. Для адресного редактирования используйте PATCH /v1/items/:entityTypeId/:id/products/:rowId.

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

404 — элемент не найден:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Элемент не найден"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_DYNAMIC_PARAM entityTypeId не является положительным целым или является зарезервированным (1, 2, 3, 4, 7, 31)
404 ENTITY_NOT_FOUND Элемент не найден
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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