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

Поля товаров счёта

GET /v1/invoices/:id/products/fields

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

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

Параметры

Параметр Тип Обяз. Описание
id (path) number да ID счёта

Примеры

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

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

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/invoices/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/invoices/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/invoices/741/products/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Справочник полей товарной позиции. Ключ — имя поля, значение — его описание
data.<поле>.type string Тип значения: integer, double, string, char
data.<поле>.isReadOnly boolean Поле только для чтения, записать его нельзя
data.<поле>.isRequired boolean Отметка обязательности. У всех полей товарной позиции false: запись принимает позицию, в которой есть хотя бы одно записываемое поле
data.<поле>.isImmutable boolean true у ownerId и ownerType: владельца позиции задаёт адрес запроса. У priceAccount и xmlId ключа нет
data.<поле>.isMultiple boolean У полей товарной позиции false. У priceAccount и xmlId ключа нет
data.<поле>.isDynamic boolean У полей товарной позиции false. У priceAccount и xmlId ключа нет
data.<поле>.title string Подпись поля. У priceAccount и xmlId отсутствует
data.<поле>.description string Пояснение к полю. Приходит у id и discountSum
meta.warnings array Приходит, только если Битрикс24 описал не все поля. Элемент с кодом fields_partial перечисляет поля, описание которых собрано без подписей

Поля товарной позиции, которые описывает data:

Поле Тип RO Обяз. Описание
id integer да ID позиции
productId integer ID товара. Каталог: GET /v1/products. Позиция без productId создаётся с productId равным 0 и названием из productName — см. Добавить товар
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 да Тип товара — то же значение, что поле type товара в GET /v1/catalog-products/:id: 1 — простой товар, 3 — головной товар с вариациями, 7 — услуга
storeId integer да ID склада
taxName string да Название налога. Есть только в справочнике, в товарных позициях не приходит. В теле запроса на запись отклоняется с 400 INVALID_PARAMS
ownerId integer да ID владельца (счёта)
ownerType string да Тип владельца
priceAccount double да Цена в валюте отчёта
xmlId string да Внешний код позиции

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

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": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Товар" },
    "productName": { "type": "string", "isRequired": false, "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": "Цена без налога со скидкой" },
    "priceNetto": { "type": "double", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "PRICE_NETTO" },
    "priceBrutto": { "type": "double", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "PRICE_BRUTTO" },
    "quantity": { "type": "double", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Количество" },
    "discountTypeId": { "type": "integer", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Тип скидки" },
    "discountRate": { "type": "double", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Величина скидки" },
    "discount": { "type": "double", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Сумма скидки" },
    "taxRate": { "type": "double", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Налог" },
    "taxIncluded": { "type": "char", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Налог включен в цену" },
    "customized": { "type": "char", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Изменен" },
    "measureCode": { "type": "integer", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Код единицы измерения" },
    "measureName": { "type": "string", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Единица измерения" },
    "sort": { "type": "integer", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Сортировка" },
    "type": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "TYPE" },
    "storeId": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "STORE_ID" },
    "taxName": { "type": "string", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "TAX_NAME" },
    "priceAccount": { "type": "double", "isReadOnly": true, "isRequired": false },
    "xmlId": { "type": "string", "isReadOnly": true, "isRequired": false },
    "discountSum": { "type": "double", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Сумма скидки", "description": "Deprecated alias of `discount`; kept so clients written against the previous field list keep working. Accepted on write, never present in row data — migrate to `discount`." }
  }
}

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

Схема одинакова для всех счетов. Ответ не зависит от id в адресе: значение несуществующего счёта отдаёт ту же схему и тот же 200, а не отказ. Проверять существование счёта этим вызовом нельзя — для этого есть GET /v1/invoices/:id.

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

403 — у ключа нет нужного скоупа:

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

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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