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

Свойства заказа

Справочник полей интернет-магазина: названия, типы, настройки и значения по умолчанию для оформления заказа. Значения, введённые покупателем в конкретном заказе, хранятся отдельно.

При создании выберите тип плательщика и группу из существующих свойств этого типа. Частичное изменение сохраняет неуказанные поля и настройки. Тип свойства, тип плательщика и группа задаются при создании и не изменяются через PATCH.

Битрикс24 API: sale.property.* Скоуп: sale

Операции

Ключевые поля

Поле Тип Описание
id number ID определения свойства. Список: GET /v1/order-properties
personTypeId number ID типа плательщика из GET /v1/person-types. Обязателен при создании
type string Тип: STRING, Y/N, NUMBER, ENUM, FILE, DATE, LOCATION, ADDRESS. Обязателен при создании
name string Название поля. Обязательно при создании
propsGroupId number ID группы свойств. Возьмите из свойства того же типа плательщика через GET /v1/order-properties. Обязателен при создании
settings object Настройки типа свойства. При изменении объединяются по ключам с сохранёнными настройками
defaultValue any Значение по умолчанию. Формат зависит от типа и множественности свойства

Полный список полей — GET /v1/order-properties/fields.

Что нужно знать перед работой

  1. Определение свойства и его значение — разные данные. Эти методы управляют полем заказа. Введённые значения, варианты списочного типа ENUM и группы свойств через эти маршруты не создаются.
  2. Группа должна относиться к выбранному типу плательщика. Найдите существующее свойство с нужным personTypeId через список или поиск и возьмите его propsGroupId. У нового типа плательщика может не быть свойств и групп. Отдельного маршрута для создания группы в этом разделе нет.
  3. Тип и принадлежность не изменяются. PATCH с id, type, personTypeId или propsGroupId возвращает 400 READONLY_FIELD. Для изменения типа создайте другое определение свойства.
  4. Частичное изменение сохраняет остальное. Перед записью свойство читается. Неуказанные поля, флаги, сортировка, значение по умолчанию и настройки сохраняются. settings объединяется по верхним ключам. Ошибка предварительного чтения останавливает запись. Одновременное внешнее изменение между чтением и записью может быть перезаписано.
  5. Настройки зависят от типа. Для STRING используются minlength, maxlength, multiline, pattern, для NUMBER — min, max, step, для DATE — time. Поля самого свойства передавайте на верхнем уровне тела. Вложенные relations и variants в settings изменять нельзя.
  6. Файловое значение требует явной замены. Если у свойства FILE уже есть файл в defaultValue, при изменении передайте новое defaultValue. Иначе запрос отклоняется с 400 INVALID_PARAMS. Формат загрузки — { "fileData": ["имя файла", "base64"] }.
  7. Флаги имеют тип boolean. active, required, multiple и другие флаги принимаются и возвращаются как true или false.

Типичный сценарий

  1. Выбрать тип плательщика: GET /v1/person-types.
  2. Найти свойство этого типа и получить его propsGroupId: GET /v1/order-properties.
  3. Создать определение поля: POST /v1/order-properties.
  4. Прочитать определение по полученному id: GET /v1/order-properties/:id.
  5. Изменить название, флаги или настройки: PATCH /v1/order-properties/:id.
  6. Когда определение больше не нужно, удалить его: DELETE /v1/order-properties/:id.

Лимиты

Лимит Значение
Записей на запрос списка или поиска limit до 5000, по умолчанию 50. Следующие записи запрашиваются через offset
Агрегация до 5 выражений, функции count, sum, avg, min, max. Для вычислений и группировки читается до 5000 записей
Группировка по personTypeId, type, required, active, до 5 измерений. groupLimit от 1 до 1000
Пакетная запись create, update, delete. До 500 команд в POST /v1/order-properties/batch, порциями до 50 команд в Битрикс24. ID изменяемого свойства должен быть известен заранее. Обновляйте каждое свойство не больше одного раза в пакете
Частота запросов общая для API Вайбкод — см. Лимиты и оптимизация

Для пакетной записи доступны POST /v1/batch и POST /v1/order-properties/batch. Они сохраняют неуказанные поля при обновлении по тем же правилам. Проверка повторных обновлений действует в пределах одного вызова batch Битрикс24, до 50 команд: дубль возвращает 400 INVALID_PARAMS. Дубли в разных порциях этой проверкой не отклоняются. Для последовательных изменений одного свойства используйте отдельные запросы. Ссылка на результат создания вместо ID изменяемого свойства не поддерживается. Формат пакета — Пакетные вызовы.

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