## Создать свойство заказа `POST /v1/order-properties` Создаёт определение поля интернет-магазина для ввода дополнительных данных при оформлении заказа. Поля передаются плоско в корне JSON, без обёртки `fields`. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|------|------|------| | `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`](./list.md), поле `propsGroupId` | | `code` | string \| null | нет | Символьный код | | `sort` | number | нет | Порядок сортировки | | `defaultValue` | any | нет | Значение по умолчанию. Скаляр или структура в зависимости от типа и `multiple`. Для `FILE` загрузка — `{ "fileData": ["имя файла", "base64"] }` | | `description` | string \| null | нет | Описание поля | | `settings` | object | нет | Настройки типа свойства. JSON-объект. Поля самого свойства передавайте на верхнем уровне тела | | `xmlId` | string \| null | нет | Внешний идентификатор | | `inputFieldLocation` | number | нет | Устаревшее поле. Битрикс24 его не использует | | `active` | boolean | нет | Свойство активно | | `required` | boolean | нет | Значение обязательно при оформлении заказа | | `multiple` | boolean | нет | Свойство содержит несколько значений | | `userProps` | boolean | нет | Сохранять значение в профиле покупателя | | `util` | boolean | нет | Служебное свойство | | `isAddress` | boolean | нет | Свойство содержит адрес | | `isAddressFrom` | boolean | нет | Адрес отправления | | `isAddressTo` | boolean | нет | Адрес назначения | | `isEmail` | boolean | нет | Свойство содержит электронную почту | | `isFiltered` | boolean | нет | Использовать свойство в фильтре | | `isLocation` | boolean | нет | Свойство содержит местоположение | | `isLocation4tax` | boolean | нет | Местоположение для расчёта налогов | | `isPayer` | boolean | нет | Имя плательщика | | `isPhone` | boolean | нет | Телефон | | `isProfileName` | boolean | нет | Название профиля покупателя | | `isZip` | boolean | нет | Почтовый индекс | `id` задаётся сервером. ## Примеры ### curl — личный ключ ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/order-properties" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "personTypeId": 5, "type": "STRING", "name": "Комментарий курьеру", "propsGroupId": 9, "code": "DELIVERY_COMMENT", "sort": 500, "active": false, "required": false, "defaultValue": "Позвонить перед доставкой", "settings": { "maxlength": 200 } }' ``` ### curl — OAuth-приложение ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/order-properties" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "personTypeId": 5, "type": "STRING", "name": "Комментарий курьеру", "propsGroupId": 9, "code": "DELIVERY_COMMENT", "sort": 500, "active": false, "required": false, "defaultValue": "Позвонить перед доставкой", "settings": { "maxlength": 200 } }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/order-properties', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ "personTypeId": 5, "type": "STRING", "name": "Комментарий курьеру", "propsGroupId": 9, "code": "DELIVERY_COMMENT", "sort": 500, "active": false, "required": false, "defaultValue": "Позвонить перед доставкой", "settings": { "maxlength": 200 } }), }) const { success, data } = await res.json() ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/order-properties', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ "personTypeId": 5, "type": "STRING", "name": "Комментарий курьеру", "propsGroupId": 9, "code": "DELIVERY_COMMENT", "sort": 500, "active": false, "required": false, "defaultValue": "Позвонить перед доставкой", "settings": { "maxlength": 200 } }), }) const { success, data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|------|------| | `success` | boolean | `true` при успехе. HTTP-статус — `201` | | `data` | object | Созданное свойство заказа. Полный список полей: [Поля свойства заказа](./fields.md) | ## Пример ответа Показаны основные поля. Полный список: [Поля свойства заказа](./fields.md). ```json { "success": true, "data": { "id": 125, "personTypeId": 5, "type": "STRING", "name": "Комментарий курьеру", "propsGroupId": 9, "code": "DELIVERY_COMMENT", "active": false, "defaultValue": "Позвонить перед доставкой", "settings": { "maxlength": 200, "multiline": "N" } } } ``` ## Пример ответа при ошибке 400 — в `settings` передано `null`: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "Order property settings must be an object." } } ``` ## Ошибки | HTTP | Код | Описание | |------|------|------| | 400 | `MISSING_REQUIRED_FIELDS` | Нет поля `personTypeId`, `type`, `name` или `propsGroupId`; `personTypeId`, `name` или `propsGroupId` равны `null`; либо `name` — пустая строка | | 400 | `INVALID_PARAMS` | `type` не из списка допустимых типов, равен `null` или пустой строке. Текст — `Invalid order property type.` | | 400 | `READONLY_FIELD` | Передано поле `id`, `relations` или `variants`, в том числе внутри `settings` | | 400 | `INVALID_PARAMS` | В скалярное поле передан объект или массив | | 400 | `INVALID_PARAMS` | В числовое поле передана нечисловая строка, пустая строка или boolean | | 400 | `INVALID_PARAMS` | Флаг не равен boolean `true`/`false` или одной из строк `"Y"`/`"N"`, `"yes"`/`"no"`, `"1"`/`"0"`, `"true"`/`"false"` (без учёта регистра и пробелов по краям) | | 400 | `INVALID_PARAMS` | `settings` не является JSON-объектом | | 422 | `BITRIX_ERROR` | Битрикс24 отклонил операцию. Текст причины — в `message` | | 422 | `BITRIX_ERROR` | У пользователя ключа нет прав в Битрикс24. Код Битрикс24 — в `error.b24Code`: `200040300020` | | 403 | `BITRIX_ACCESS_DENIED` | У учётных данных портала нет скоупа `sale` (`insufficient_scope`) | | 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только для чтения | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | Полный список общих ошибок API — [Коды ошибок](/docs/errors). ## Смотрите также - [Свойства заказа](/docs/entities/order-properties) - [Получить свойство заказа](./get.md) - [Обновить свойство заказа](./update.md) - [Удалить свойство заказа](./delete.md) - [Поля свойства заказа](./fields.md)