REST: crm.deal.productrows (товары сделки)

Товарные позиции сделки — это строки с товарами и услугами, из которых складывается её сумма. Методы crm.deal.productrows.get и crm.deal.productrows.set читают и полностью перезаписывают этот список. Разберём структуру строки, скидки, налоги и пересчёт итога.

Как устроены товарные строки

Товарные строки — самостоятельная сущность, привязанная к сделке. У сделки нет отдельного «товара»: сумма OPPORTUNITY формируется из строк, если не включён ручной режим. Работают с ними два основных метода:

• crm.deal.productrows.get — вернуть все строки сделки;
• crm.deal.productrows.set — заменить весь набор строк новым.

Важно понимать: set работает по принципу полной замены. Нельзя добавить одну строку, не передав остальные, — метод удалит всё, чего нет в переданном массиве. Чтобы дописать позицию, сначала получите текущие строки через get, добавьте новую в массив и отправьте его целиком.

Поля строки товара

Каждая позиция описывается набором полей. Ниже — те, что нужны чаще всего.

Полный перечень возвращает crm.deal.productrows.fields. Единица измерения по умолчанию — штука (код 796 по ОКЕИ).

Запись строк: crm.deal.productrows.set

Перезапишем состав сделки двумя позициями — товаром из каталога и услугой:

POST /rest/1/xxxxxx/crm.deal.productrows.set.json

{
  "id": 145,
  "rows": [
    {
      "PRODUCT_ID": 51,
      "PRICE": 50000,
      "QUANTITY": 2,
      "DISCOUNT_TYPE_ID": 2,
      "DISCOUNT_RATE": 10,
      "TAX_RATE": 20,
      "TAX_INCLUDED": "Y"
    },
    {
      "PRODUCT_NAME": "Пусконаладка",
      "PRICE": 25000,
      "QUANTITY": 1
    }
  ]
}

Параметр называется id (ID сделки) и массив rows. После успешной записи сумма сделки пересчитается автоматически, если у неё не выставлен флаг IS_MANUAL_OPPORTUNITY = Y.

Чтение строк и логика скидок

Метод crm.deal.productrows.get принимает только id сделки и возвращает массив строк с рассчитанными значениями. Поле PRICE отдаётся уже с учётом скидки, а исходную цену смотрите в PRICE_EXCLUSIVE, PRICE_NETTO и PRICE_BRUTTO.

1. PRICE_NETTO — базовая цена без скидки и без налога;
2. применяется скидка → PRICE_EXCLUSIVE;
3. добавляется налог → PRICE_BRUTTO и итоговая PRICE.

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

Связь с каталогом и единицами измерения

Если PRODUCT_ID ссылается на товар каталога, он подтягивает название, единицу измерения и, при желании, цену. Товары каталога живут в отдельном модуле с методами catalog.product.* и старым crm.product.*.

• Свободная позиция (PRODUCT_ID = 0) требует явного PRODUCT_NAME;
• единицы измерения задаются кодом ОКЕИ в MEASURE_CODE: 796 — штука, 006 — метр, 166 — килограмм;
• для корректных отчётов по товарам лучше ссылаться на реальные PRODUCT_ID, а не плодить одноимённые свободные строки.

Итог

Товарные строки сделки читаются crm.deal.productrows.get и полностью перезаписываются crm.deal.productrows.set. Помните про принцип полной замены, различайте PRICE_NETTO, PRICE_EXCLUSIVE и PRICE_BRUTTO, задавайте скидки и налоги явно и следите за флагом ручной суммы.

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