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

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

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

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

## Операции

- [Создать свойство заказа](/docs/entities/order-properties/create) — `POST /v1/order-properties`
- [Список свойств заказа](/docs/entities/order-properties/list) — `GET /v1/order-properties`
- [Получить свойство заказа](/docs/entities/order-properties/get) — `GET /v1/order-properties/:id`
- [Обновить свойство заказа](/docs/entities/order-properties/update) — `PATCH /v1/order-properties/:id`
- [Удалить свойство заказа](/docs/entities/order-properties/delete) — `DELETE /v1/order-properties/:id`
- [Поиск свойств заказа](/docs/entities/order-properties/search) — `POST /v1/order-properties/search`
- [Поля свойства заказа](/docs/entities/order-properties/fields) — `GET /v1/order-properties/fields`
- [Агрегация свойств заказа](/docs/entities/order-properties/aggregate) — `POST /v1/order-properties/aggregate`

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

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

Полный список полей — [`GET /v1/order-properties/fields`](./order-properties/fields.md).

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

1. **Определение свойства и его значение — разные данные.** Эти методы управляют полем заказа. Введённые значения, варианты списочного типа `ENUM` и группы свойств через эти маршруты не создаются.
2. **Группа должна относиться к выбранному типу плательщика.** Найдите существующее свойство с нужным `personTypeId` через [список](./order-properties/list.md) или [поиск](./order-properties/search.md) и возьмите его `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`](/docs/entities/person-types/list).
2. Найти свойство этого типа и получить его `propsGroupId`: [`GET /v1/order-properties`](./order-properties/list.md).
3. Создать определение поля: [`POST /v1/order-properties`](./order-properties/create.md).
4. Прочитать определение по полученному `id`: [`GET /v1/order-properties/:id`](./order-properties/get.md).
5. Изменить название, флаги или настройки: [`PATCH /v1/order-properties/:id`](./order-properties/update.md).
6. Когда определение больше не нужно, удалить его: [`DELETE /v1/order-properties/:id`](./order-properties/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Записей на запрос списка или поиска | `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 Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

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

- [Типы плательщиков](/docs/entities/person-types)
- [Заказы](/docs/entities/orders)
- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)