REST: товарные позиции сделки

Товарные позиции превращают сделку в полноценный заказ: перечень товаров, цены, количество, скидки и налоги. За них отвечает под-семейство crm.deal.productrows.* и более новый универсальный метод crm.item.productrow.*.

Модель товарных позиций

Товарные позиции — это дочерние строки, привязанные к сделке (или счёту, смет-процессу). Каждая строка описывает один товар с ценой и количеством. Сумма сделки в режиме расчёта по товарам собирается именно из этих строк.

Есть два поколения API:

• crm.deal.productrows.get / set — классическое под-семейство сделки;
• crm.item.productrow.* (add, get, list, set, delete) — универсальный набор для любых CRM-сущностей.

Для интеграции с сайтом и 1С обычно достаточно классического под-семейства сделки. Универсальный набор crm.item.productrow нужен, когда товары ведутся у смарт-процессов или когда важна работа с отдельными строками (добавить/удалить одну позицию, а не переустанавливать весь набор). Выбор поколения API стоит зафиксировать в начале проекта, чтобы не смешивать логику.

Чтение и запись: get и set

Получить строки сделки: crm.deal.productrows.get с параметром id — идентификатором сделки.

Записать весь набор строк разом: crm.deal.productrows.set. Метод полностью заменяет прежний состав, поэтому передавайте актуальный список целиком.

{ "id": 1024, "rows": [ { "PRODUCT_ID": 77, "PRICE": 1500, "QUANTITY": 3, "DISCOUNT_TYPE_ID": 2, "DISCOUNT_RATE": 10, "TAX_RATE": 20, "TAX_INCLUDED": "Y" }, { "PRODUCT_NAME": "Доставка", "PRICE": 500, "QUANTITY": 1 } ] }

Строки в ответе get приходят с уже рассчитанными полями — суммой позиции, разложенной ценой без налога и величиной скидки. При обратной записи большинство расчётных полей передавать не нужно: система пересчитает их из PRICE, QUANTITY, скидки и налога. Это упрощает синхронизацию — вы храните у себя минимум данных о каждой позиции.

Состав полей строки

Налоги и скидки

Логика цены важна: поле PRICE — это итоговая цена за единицу после скидки. Если задаёте процентную скидку, Битрикс24 ожидает согласованность между базовой ценой и PRICE.

• PRICE_EXCLUSIVE — цена со скидкой, но без налога;
• PRICE_NETTO — базовая цена без скидки и налога;
• PRICE_BRUTTO — базовая цена с налогом.

Связь с каталогом товаров

Если позиция ссылается на товар каталога (PRODUCT_ID > 0), сам товар живёт в другом семействе методов. Управление каталогом — это crm.product.* (устаревшее) и модуль товаров catalog.* / catalog.product.* для торгового каталога.

• crm.product.list — найти товар по названию или разделу;
• crm.productsection.list — разделы каталога;
• вариации/SKU — через catalog.* с торговым каталогом.

При интеграции с 1С товары обычно матчатся по внешнему коду (XML_ID), а PRODUCT_ID подставляется после поиска. Если товара в каталоге ещё нет, его можно создать на лету или оставить произвольной строкой с PRODUCT_ID: 0 и заполненным PRODUCT_NAME.

Каждая позиция может ссылаться и на конкретную цену из каталога через PRICE_ID, но для внешних интеграций надёжнее передавать цену явно — так вы не зависите от настроек типов цен на портале и всегда получаете предсказуемый результат.

Типичные ошибки и пересчёт суммы

Частые проблемы при работе с товарными позициями через REST:

1. Пропажа позиций — вызвали set без прежних строк.
2. Сумма сделки не меняется — сделка в режиме ручной суммы; включите режим расчёта по товарам или обновляйте OPPORTUNITY отдельно.
3. Двойной налог — задали и TAX_INCLUDED: "N", и уже включённую в PRICE ставку.

Ещё одна распространённая ловушка — дробные количества и единицы измерения. Если товар в каталоге настроен на штуки, а из внешней системы приходит вес или объём, значения QUANTITY и MEASURE_CODE нужно согласовать, иначе суммы будут расходиться. При интеграции с 1С полезно фиксировать сопоставление единиц измерения в отдельном справочнике на стороне обмена и подставлять корректный MEASURE_CODE при формировании строк.

Итог

Товарные позиции через crm.deal.productrows.* и crm.item.productrow.* превращают сделку в заказ с корректными ценами, скидками и налогами. Ключевые правила — помнить о полной замене набора при set, согласовывать налоговые поля и матчить товары каталога по внешнему коду.

Мы в B2Bsite настраиваем выгрузку состава заказа между сайтом, Битрикс24 и 1С так, чтобы цены, скидки и НДС сходились до копейки. Если товары сделки должны корректно ездить между системами — поможем выстроить обмен.