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

Добавить товар в счёт

POST /v1/invoices/:id/products

Добавляет одну товарную позицию в счёт. В отличие от PUT /v1/invoices/:id/products, не заменяет существующие позиции.

Имена полей проверяются. Поле, которого нет среди записываемых, не отбрасывается молча: запрос отклоняется с 400 INVALID_PARAMS, и в тексте ошибки перечислены записываемые имена. Поля только для чтения, которые приходят в ответах товарных позиций — priceAccount, ownerId, storeId и другие, — принимаются и игнорируются, поэтому объект, прочитанный через GET, можно отправить обратно без чистки.

Параметры

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

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

Поле Тип Обяз. Описание
productId number нет ID товара из каталога. Если задан без productName, имя подставляется из каталога. Каталог: GET /v1/products
productName string нет Название товарной позиции — для произвольной строки без товара из каталога. Укажите хотя бы одно из productId и productName
price number нет Цена за единицу
quantity number нет Количество
discountTypeId number нет Как задана скидка: 1 — суммой в поле discount, 2 — процентом в поле discountRate. По умолчанию 2
discount number нет Сумма скидки. Учитывается только при discountTypeId равном 1
discountRate number нет Процент скидки. Учитывается только при discountTypeId равном 2
taxRate number нет Ставка налога (%)
taxIncluded boolean нет Налог включён в цену

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/invoices/58/products" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "productId": 1, "price": 25000, "quantity": 2 }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/invoices/58/products" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "productId": 1, "price": 25000, "quantity": 2 }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/invoices/58/products', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ productId: 1, price: 25000, quantity: 2 }),
})

const { success, data } = await res.json()
console.log('ID строки:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/invoices/58/products', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ productId: 1, price: 25000, quantity: 2 }),
})

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

Поля ответа

Поле Тип Описание
data object Созданная товарная строка целиком, HTTP-статус 201. Состав полей — Поля товаров

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

Показаны основные поля. Полный список — Поля товаров.

JSON 
{
  "success": true,
  "data": {
    "id": 1465,
    "productId": 1,
    "productName": "Серверное оборудование",
    "price": 25000,
    "quantity": 2,
    "discount": 0,
    "discountTypeId": 2,
    "taxIncluded": false
  }
}

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

404 — счёт не найден:

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

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Тело содержит имя, которого нет среди записываемых полей — см. Поля товаров
404 ENTITY_NOT_FOUND Счёт не найден
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Скидка суммой требует discountTypeId: 1. По умолчанию тип скидки равен 2, то есть процент, и в этом режиме поле discount не сохраняется: позиция создаётся с discount: 0, ошибки при этом нет. Задавая скидку суммой, передавайте discountTypeId: 1 вместе с discount, а процентом — discountRate при типе 2.

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