## Поля свойства заказа `GET /v1/order-properties/fields` Описывает поля свойства заказа для создания, изменения, выборки и фильтрации, а также доступные поля группировки. ## Параметры | Параметр | Тип | По умолч. | Описание | |----------|-----|-----------|---------| | `refresh` (query) | string | `false` | Передайте `true`, чтобы получить метаданные без кэша. Пример: `?refresh=true` | ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/order-properties/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl "https://vibecode.bitrix24.tech/v1/order-properties/fields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/order-properties/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { data } = await res.json() console.log('Поля свойства заказа:', Object.keys(data.fields)) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/order-properties/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data` | object | Метаданные свойства заказа. Поля самого свойства — в таблице «Поля свойства заказа» ниже | | `data.fields` | object | Описание полей. Ключ — имя поля, значение — его свойства | | `data.fields..type` | string | Тип значения: `number`, `string`, `any`, `object` или `boolean` | | `data.fields..readonly` | boolean | `true` — поле только для чтения | | `data.fields..createOnly` | boolean | Приходит со значением `true` у `personTypeId`, `type`, `propsGroupId`. Эти поля задаются при создании и не изменяются | | `data.fields..required` | boolean | Приходит со значением `true` у `personTypeId`, `type`, `name`, `propsGroupId`, обязательных при создании | | `data.fields..nullable` | boolean | Приходит со значением `true` у `code`, `description`, `xmlId`, допускающих `null` | | `data.fields..label` | string | Название поля | | `data.fields..description` | string | Описание поля | | `data.fields.type.enum` | array | Допустимые значения типа свойства. Элемент содержит `value` и `label` | | `data.fields.type.enum[].labelRu` | string | Русская подпись значения типа свойства | | `data.aggregatable` | array | Поля для `groupBy` в [агрегации свойств заказа](./aggregate.md): `personTypeId`, `type`, `required`, `active` | | `data.batch` | array | Операции пакетной записи: `create`, `update`, `delete` | ### Поля свойства заказа Полный набор полей из схемы. Колонка RO — поле только для чтения. | Поле | Тип | RO | Описание | |------|-----|:--:|---------| | `id` | number | да | ID свойства. Список: [`GET /v1/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`](./list.md). Обязателен только при создании, далее не изменяется | | `code` | string \| null | нет | Символьный код. `null`, если не задан | | `sort` | number | нет | Порядок сортировки | | `defaultValue` | any | нет | Значение по умолчанию. Формат зависит от типа свойства. Запись файлового значения описана в [создании](./create.md) и [изменении](./update.md) | | `description` | string \| null | нет | Описание поля. `null`, если не задано | | `settings` | object | нет | Настройки типа свойства. Формат и сохранение настроек — в [изменении свойства](./update.md) | | `xmlId` | string \| null | нет | Внешний идентификатор. `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 | нет | Поле почтового индекса | ## Пример ответа ```json { "success": true, "data": { "fields": { "id": { "type": "number", "readonly": true, "label": "ID", "description": "ID." }, "personTypeId": { "type": "number", "readonly": false, "createOnly": true, "required": true, "label": "ID типа плательщика", "description": "ID типа плательщика." }, "type": { "type": "string", "readonly": false, "createOnly": true, "required": true, "label": "Тип свойства", "description": "Тип свойства.", "enum": [ { "value": "STRING", "label": "STRING", "labelRu": "STRING" }, { "value": "Y/N", "label": "Y/N", "labelRu": "Y/N" }, { "value": "NUMBER", "label": "NUMBER", "labelRu": "NUMBER" }, { "value": "ENUM", "label": "ENUM", "labelRu": "ENUM" }, { "value": "FILE", "label": "FILE", "labelRu": "FILE" }, { "value": "DATE", "label": "DATE", "labelRu": "DATE" }, { "value": "LOCATION", "label": "LOCATION", "labelRu": "LOCATION" }, { "value": "ADDRESS", "label": "ADDRESS", "labelRu": "ADDRESS" } ] }, "name": { "type": "string", "readonly": false, "required": true, "label": "Название", "description": "Название." }, "propsGroupId": { "type": "number", "readonly": false, "createOnly": true, "required": true, "label": "ID группы свойств", "description": "ID группы свойств." }, "code": { "type": "string", "readonly": false, "nullable": true, "label": "Код", "description": "Код." }, "sort": { "type": "number", "readonly": false, "label": "Порядок сортировки", "description": "Порядок сортировки." }, "defaultValue": { "type": "any", "readonly": false, "label": "Значение по умолчанию (зависит от типа)", "description": "Скаляр или структура в зависимости от типа. Для FILE загрузка: {fileData:[имя,base64]}; при обновлении существующего FILE default требуется явная замена." }, "description": { "type": "string", "readonly": false, "nullable": true, "label": "Описание", "description": "Описание." }, "settings": { "type": "object", "readonly": false, "label": "Настройки по типу свойства", "description": "Настройки по типу свойства." }, "xmlId": { "type": "string", "readonly": false, "nullable": true, "label": "Внешний идентификатор", "description": "Внешний идентификатор." }, "inputFieldLocation": { "type": "number", "readonly": false, "label": "Расположение поля ввода", "description": "Расположение поля ввода." }, "active": { "type": "boolean", "readonly": false, "label": "Активно", "description": "Активно." }, "required": { "type": "boolean", "readonly": false, "label": "Обязательно", "description": "Обязательно." }, "multiple": { "type": "boolean", "readonly": false, "label": "Множественное", "description": "Множественное." }, "userProps": { "type": "boolean", "readonly": false, "label": "Сохранять в профиле", "description": "Сохранять в профиле." }, "util": { "type": "boolean", "readonly": false, "label": "Служебное свойство", "description": "Служебное свойство." }, "isAddress": { "type": "boolean", "readonly": false, "label": "Адрес", "description": "Адрес." }, "isAddressFrom": { "type": "boolean", "readonly": false, "label": "Адрес отправления", "description": "Адрес отправления." }, "isAddressTo": { "type": "boolean", "readonly": false, "label": "Адрес назначения", "description": "Адрес назначения." }, "isEmail": { "type": "boolean", "readonly": false, "label": "Email", "description": "Email." }, "isFiltered": { "type": "boolean", "readonly": false, "label": "Использовать в фильтре", "description": "Использовать в фильтре." }, "isLocation": { "type": "boolean", "readonly": false, "label": "Местоположение", "description": "Местоположение." }, "isLocation4tax": { "type": "boolean", "readonly": false, "label": "Местоположение для налогов", "description": "Местоположение для налогов." }, "isPayer": { "type": "boolean", "readonly": false, "label": "Имя плательщика", "description": "Имя плательщика." }, "isPhone": { "type": "boolean", "readonly": false, "label": "Телефон", "description": "Телефон." }, "isProfileName": { "type": "boolean", "readonly": false, "label": "Название профиля", "description": "Название профиля." }, "isZip": { "type": "boolean", "readonly": false, "label": "Почтовый индекс", "description": "Почтовый индекс." } }, "aggregatable": [ "personTypeId", "type", "required", "active" ], "batch": [ "create", "update", "delete" ] } } ``` ## Пример ответа при ошибке 401 — не передан API-ключ: ```json { "success": false, "error": { "code": "MISSING_API_KEY", "message": "API key required. Pass via X-Api-Key header." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | | 429 | `RATE_LIMITED` | Превышен лимит запросов. Точное значение — в заголовке `x-ratelimit-limit`. Повторите после срока из заголовка `Retry-After` | Полный список общих ошибок API — [Коды ошибок](/docs/errors). ## Смотрите также - [Список свойств заказа](./list.md) - [Получить свойство заказа](./get.md) - [Создать свойство заказа](./create.md) - [Обновить свойство заказа](./update.md) - [Агрегация свойств заказа](./aggregate.md) - [Свойства заказа](/docs/entities/order-properties) - [Batch](/docs/batch) - [Entity API](/docs/entity-api)