REST: crm.productrow.set

crm.productrow.set — универсальный метод для установки товарных позиций у любой сущности CRM: сделки, счёта нового поколения, предложения или элемента смарт-процесса. Он заменяет весь набор строк владельца целиком и пришёл на смену узкоспециализированному crm.deal.productrows.set.

Зачем нужен универсальный метод

Раньше товары каждой сущности задавались своим методом: crm.deal.productrows.set, crm.lead.productrows.set и так далее. С появлением смарт-процессов и счетов нового поколения потребовался единый интерфейс, который работает с любым владельцем через указание его типа.

• crm.productrow.set — заменить весь набор строк владельца;
• crm.productrow.get — получить строки владельца;
• crm.productrow.list — выборка строк по фильтру;
• crm.productrow.add / delete — операции с отдельной строкой;
• crm.productrow.fields — описание полей позиции.

Идентификация владельца

Владелец задаётся двумя параметрами: ownerType — символьный код типа сущности, и ownerId — её идентификатор.

Именно поддержка смарт-процессов делает crm.productrow.set предпочтительным: узкие методы вроде deal.productrows не умеют работать с товарами динамических сущностей.

Установка позиций: пример запроса

Зададим две товарные позиции для сделки 340:

POST /rest/1/xxxxxxxx/crm.productrow.set.json
{
  "ownerType": "D",
  "ownerId": 340,
  "productRows": [
    {
      "productId": 27,
      "productName": "Насос центробежный",
      "price": 15000,
      "quantity": 2,
      "taxRate": 20,
      "taxIncluded": "Y"
    },
    {
      "productName": "Доставка",
      "price": 2000,
      "quantity": 1,
      "taxRate": 20,
      "taxIncluded": "Y"
    }
  ]
}

Поле productId ссылается на товар каталога; для произвольной строки его можно опустить, оставив только productName и цену. Полный перечень полей — в crm.productrow.fields.

Поля товарной позиции

Строка описывается набором ценовых и налоговых полей. Самые важные из них:

• productId — ID товара каталога;
• price — цена за единицу с учётом настроек налога;
• quantity — количество;
• discountRate / discountSum — скидка в процентах или сумме;
• taxRate — ставка налога, taxIncluded — включён ли налог в цену (Y/N);
• measureCode / measureName — единица измерения.

Пересчёт суммы сделки

После установки товаров сумма владельца пересчитывается автоматически, если поле суммы не зафиксировано вручную. У сделки за это отвечает флаг IS_MANUAL_OPPORTUNITY.

1. Если IS_MANUAL_OPPORTUNITY = N — сумма OPPORTUNITY будет рассчитана из товарных строк;
2. Если = Y — сумма зафиксирована и не изменится при обновлении товаров;
3. Чтобы товары «управляли» суммой, при обновлении сделки установите флаг в N.

POST /rest/1/xxxxxxxx/crm.deal.update.json
{ "id": 340, "fields": { "IS_MANUAL_OPPORTUNITY": "N" } }

Типичный сценарий интеграции с 1С: сначала установить товары через crm.productrow.set, затем убедиться, что сумма сделки не заморожена вручную.

Стоит понимать разницу между суммой и валютой. Сумма считается в валюте владельца (CURRENCY_ID сделки), поэтому если товар в каталоге хранится в другой валюте, цену нужно передавать уже приведённой к валюте сделки — автоматической конвертации по курсу в момент установки строк не происходит. Отдельно проверяйте налоговую модель портала: поле taxIncluded имеет смысл только когда в настройках CRM включён учёт налога, иначе значение игнорируется. Эти детали особенно важны при выгрузке заказов из внешней учётной системы, где цены и налоги уже рассчитаны и их нельзя искажать.

Практика и подводные камни

Для массовой загрузки заказов оборачивайте установку товаров в batch, но помните про лимит на размер запроса: очень длинные спецификации разбивайте на части и используйте отдельную сущность-владельца на каждый заказ.

Ещё одна деталь касается связи товарной строки с каталогом. Если вы указали productId, но затем в каталоге товар был удалён, строка сохранит своё название и цену, однако перестанет корректно учитываться в товарной аналитике. Поэтому при обмене с внешней системой полезно хранить у себя соответствие «внешний артикул → productId каталога» и поддерживать его в актуальном состоянии через crm.product.list. Так вы гарантируете, что позиции сделок всегда ссылаются на действительные товары, а отчёты по продажам остаются достоверными.

Итог

crm.productrow.set — правильный выбор для установки товаров в современных сценариях, потому что работает единообразно со сделками, счетами и смарт-процессами. Помните два правила: метод перезаписывает весь набор строк, а автоматический пересчёт суммы зависит от флага IS_MANUAL_OPPORTUNITY. Согласованность цены, скидки и налога — залог корректной итоговой суммы.

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