REST: sale.propertyvalue и свойства заказа

Свойства заказа в Битрикс24 — это то, что превращает набор товаров в готовую сделку: ФИО, телефон, адрес доставки, комментарий, ИНН. За их описание отвечает sale.property, а за конкретные значения в заказе — sale.propertyvalue. Разбираем модель данных и запросы.

Зачем нужны свойства заказа

В модели онлайн-магазина Битрикс24 заказ (sale.order) хранит состав корзины и суммы, но не содержит контактных и логистических данных покупателя напрямую. Всё это — свойства заказа. Они делятся на два уровня:

• Описание свойства — шаблон поля: имя, тип, обязательность, привязка к типу плательщика. Это методы группы sale.property.*.
• Значение свойства — то, что реально введено в конкретном заказе. Это sale.propertyvalue.*.

Такое разделение позволяет один раз описать поле «Телефон» и переиспользовать его во всех заказах. При создании заказа через sale.order.add значения свойств передаются в блоке propertyValues, а позднее их можно читать и менять точечно через sale.propertyvalue.

Модель данных: property и propertyvalue

Чтобы значение сохранилось корректно, оно должно ссылаться на существующее описание свойства. Связь идёт через поле orderPropsId в значении, которое указывает на id из sale.property.

Поле personTypeId (тип плательщика — физлицо, юрлицо) связывает свойство с определённой группой покупателей. Набор доступных типов возвращает sale.persontype.list.

Методы sale.propertyvalue

Группа реализует стандартный CRUD плюс служебные методы:

• sale.propertyvalue.add — добавить значение к заказу;
• sale.propertyvalue.get — получить по id;
• sale.propertyvalue.list — выборка с фильтром и сортировкой;
• sale.propertyvalue.update — обновить значение;
• sale.propertyvalue.delete — удалить значение;
• sale.propertyvalue.modify — пакетное приведение набора значений заказа к переданному состоянию (лишние удаляются, недостающие добавляются);
• sale.propertyvalue.getfields — описание полей и их атрибутов.

Примеры запросов

Добавление значения свойства «Телефон» к заказу 145:

POST https://portal.bitrix24.ru/rest/1/xxxxx/sale.propertyvalue.add.json

Ответ вернёт объект propertyValue с присвоенным id. Выборка всех значений заказа:

Обновление одного значения:

Массовое приведение свойств заказа к состоянию (метод modify):

Типы свойств и форматы значений

Формат поля value зависит от типа свойства, заданного в sale.property:

Для свойств типа ENUM нельзя передавать текст варианта — только его идентификатор. Список допустимых вариантов конкретного свойства даёт sale.propertyvariant.list с фильтром по orderPropsId.

Группы, варианты и привязки

Свойства объединяются в группы для отображения в форме оформления. Порядок и состав задаются вспомогательными методами:

• sale.propertygroup.* — группы полей внутри одного типа плательщика;
• sale.propertyvariant.* — варианты выбора для ENUM-свойств;
• sale.propertyrelation.* — привязка свойства к платёжным системам или службам доставки, чтобы поле показывалось только при их выборе.

Через sale.propertyrelation удобно, например, показывать поле «Номер офиса» только для доставки в пункт выдачи, а «ИНН» — только для типа плательщика «Юридическое лицо». Это уменьшает число обязательных полей и снижает отказы на оформлении.

Практические нюансы

Несколько моментов, которые экономят часы отладки:

1. orderPropsId, а не code. В значениях связь идёт по числовому идентификатору свойства. Поле code удобно для чтения, но полагаться при записи стоит на orderPropsId.
2. Права доступа. Для методов sale.* приложению или вебхуку нужны права sale (Онлайн-магазин). Без них сервер вернёт ошибку доступа.
3. Согласованность с order.add. При первичном создании заказа передавайте свойства сразу в propertyValues метода sale.order.add, а точечное редактирование делайте через sale.propertyvalue.
4. Пакетность. Массовые операции удобно оборачивать в batch, чтобы уложиться в лимиты и уменьшить количество round-trip.

Итог

Свойства заказа в Битрикс24 живут на двух уровнях: описание (sale.property) задаёт правила, а sale.propertyvalue хранит конкретные значения покупателя. Ключ к корректной записи — связь через orderPropsId и правильный формат value под тип свойства. Метод modify упрощает синхронизацию, а группы, варианты и привязки формируют логику формы оформления.

Когда заказы приходят из внешнего сайта, 1С или маркетплейса, важно, чтобы карта полей совпадала на обеих сторонах и обязательные свойства всегда заполнялись. Мы проектируем такие обмены и REST-интеграции с Битрикс24 под ключ — от карты соответствия полей до обработки ошибок и очередей.