## Поля заказа

`GET /v1/orders/fields`

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

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/orders/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/orders/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/orders/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/orders/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор заказа (только чтение) |
| `accountNumber` | string | Порядковый номер заказа на портале. Только чтение — присваивается автоматически, запись отклоняется с `400 READONLY_FIELD` |
| `lid` | string | Идентификатор сайта-источника (всегда `"s1"` для облачных порталов) |
| `personTypeId` | number | Идентификатор типа плательщика |
| `currency` | string | Валюта заказа. Список: [`GET /v1/currencies`](/docs/entities/currencies) |
| `price` | number | Общая сумма заказа. Принимается только при создании: на обновлении запись отклоняется с `400 READONLY_FIELD`, потому что Битрикс24 пересчитывает сумму из позиций корзины. В ответе `/fields` помечено `readonlyOnUpdate` |
| `discountValue` | number | Значение скидки |
| `taxValue` | number | Сумма налога |
| `statusId` | string | Текущий статус заказа. Источник: [`GET /v1/order-statuses?filter[type]=O`](../order-statuses/list.md) |
| `userId` | number | Идентификатор пользователя Битрикс24 — покупателя в интернет-магазине. Источник: [`GET /v1/users`](/docs/entities/users) |
| `responsibleId` | number | Ответственный сотрудник. Источник: [`GET /v1/users`](/docs/entities/users) |
| `payed` | boolean | Оплачен ли заказ полностью. Только чтение — управляется подсистемой оплат. Запись отклоняется с `400 READONLY_FIELD` |
| `canceled` | boolean | Отменён ли заказ |
| `marked` | boolean | Отмечен ли заказ как проблемный. Принимается только при создании: на обновлении запись отклоняется с `400 READONLY_FIELD`. В ответе `/fields` помечено `readonlyOnUpdate` |
| `deducted` | boolean | Списан ли товар со склада |
| `reasonCanceled` | string \| null | Причина отмены. `null`, если заказ не отменён |
| `reasonMarked` | string \| null | Причина пометки. `null`, если пометки нет. Принимается только при создании: на обновлении запись отклоняется с `400 READONLY_FIELD`. В ответе `/fields` помечено `readonlyOnUpdate` |
| `additionalInfo` | string \| null | Дополнительная информация. `null`, если не задана |
| `comments` | string \| null | Комментарий менеджера к заказу. `null`, если не задан |
| `userDescription` | string \| null | Комментарий покупателя к заказу. `null`, если не задан |
| `orderTopic` | string \| null | Тема заказа. `null`, если не задана |
| `xmlId` | string | Внешний идентификатор для синхронизации |
| `id1c` | string \| null | Идентификатор в 1С. `null`, если заказ не синхронизирован с 1С |
| `version1c` | string \| null | Версия в 1С. `null`, если заказ не синхронизирован с 1С |
| `updated1c` | boolean | Обновлён ли заказ через 1С |
| `externalOrder` | boolean | Создан ли заказ во внешней системе |
| `recountFlag` | boolean | Флаг автоматического пересчёта |
| `affiliateId` | number \| null | Идентификатор партнёра партнёрской программы. `null`, если не задан |
| `lockedBy` | number \| null | Идентификатор пользователя, заблокировавшего заказ (актуально для коробочных порталов). `null`, если заказ не заблокирован |
| `dateLock` | datetime \| null | Время блокировки. `null`, если заказ не заблокирован |
| `recurringId` | number \| null | Идентификатор подписки (если заказ создан из повторяющегося шаблона). `null`, если заказ не из подписки |
| `dateInsert` | datetime | Дата создания (только чтение) |
| `dateUpdate` | datetime | Дата последнего изменения (только чтение) |
| `dateCanceled` | datetime \| null | Дата отмены (только чтение). `null`, если заказ не отменён |
| `dateStatus` | datetime | Дата установки текущего статуса (только чтение) |
| `empCanceledId` | number \| null | Сотрудник, отменивший заказ (только чтение). `null`, если заказ не отменён |
| `empMarkedId` | number \| null | Сотрудник, поставивший пометку (только чтение). `null`, если пометки нет |
| `empStatusId` | number \| null | Сотрудник, последний раз менявший статус (только чтение). `null`, если статус не менялся |

### Дополнительные поля и вложенные массивы

Эти поля тоже входят в схему `GET /v1/orders/fields`. `companyId` доступен для чтения и записи и по нему можно фильтровать, остальные — только для чтения. Массивы `clients`, `payments`, `basketItems`, `propertyValues` возвращает только [`GET /v1/orders/:id`](./get.md) — в списочном ответе [`GET /v1/orders`](./list.md) их нет. Логические поля внутри вложенных объектов приходят как `true`/`false`, даты — в UTC формате `…Z`.

У массивов с известной формой элемента ответ `/fields` содержит `itemSchema`. Внутри схема рекурсивно использует `type`, `readonly`, `nullable`, `properties` и `itemSchema`, поэтому описывает и `basketItems[].properties[]`. Отдельный ключ `items` не является схемой элемента: он по-прежнему содержит сырой справочник значений Битрикс24 у полей-перечислений.

| Поле | Тип | Описание |
|------|-----|---------|
| `companyId` | number \| null | Идентификатор связанной CRM-компании. `null`, если компания не задана. Доступен для записи и фильтрации. Список: [`GET /v1/companies`](/docs/entities/companies) |
| `dateMarked` | datetime \| null | Дата последней пометки заказа (только чтение) |
| `personTypeXmlId` | string \| null | Внешний идентификатор типа плательщика (только чтение) |
| `statusXmlId` | string \| null | Внешний идентификатор статуса (только чтение) |
| `version` | number | Внутренний номер версии записи (только чтение) |
| `clients` | array | CRM-привязки заказа, только чтение. Каждый элемент: `{entityTypeId, entityId, isPrimary, roleId, sort}`, где `isPrimary` — `true`/`false`. `entityTypeId` равен `3` — контакт ([`GET /v1/contacts`](/docs/entities/contacts)), `4` — компания ([`GET /v1/companies`](/docs/entities/companies)) |
| `payments` | array \| null | Оплаты заказа, только чтение. Поля оплаты — [Оплаты](../payments.md). `null`, если оплат нет |
| `basketItems` | array | Позиции корзины, только чтение. Поля позиции — [Позиции корзины](../basket-items.md) |
| `propertyValues` | array | Значения свойств заказа — ФИО, e-mail, телефон, адрес доставки, только чтение. Набор зависит от настройки портала |
| `requisiteLink` | object | Связь с реквизитами получателя (requisiteId/bankDetailId/mcRequisiteId/mcBankDetailId); `[]` если не задана; только чтение |

## Пример ответа

Каждое поле, помимо `type` и `readonly`, содержит `label` (короткое название) и `description` (пояснение) на русском языке. Заголовками запроса язык не переключается. В примере ниже они опущены для краткости. Вложенные карты `itemSchema.properties` тоже сокращены до нескольких показательных полей; живой ответ содержит полный набор из схемы сущности.

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "accountNumber": { "type": "string", "readonly": true },
      "price": { "type": "number", "readonly": false },
      "currency": { "type": "string", "readonly": false },
      "statusId": { "type": "string", "readonly": false },
      "userId": { "type": "number", "readonly": false },
      "dateInsert": { "type": "datetime", "readonly": true },
      "dateUpdate": { "type": "datetime", "readonly": true },
      "payed": { "type": "boolean", "readonly": true },
      "canceled": { "type": "boolean", "readonly": false },
      "basketItems": {
        "type": "array",
        "readonly": true,
        "itemSchema": {
          "type": "object",
          "properties": {
            "id": { "type": "number" },
            "name": { "type": "string" },
            "properties": {
              "type": "array",
              "itemSchema": {
                "type": "object",
                "properties": {
                  "code": { "type": "string", "nullable": true },
                  "value": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    "aggregatable": ["price", "statusId", "payed", "canceled", "personTypeId", "responsibleId", "userId"],
    "batch": ["create", "update", "delete"]
  }
}
```

Показаны самые важные поля. Полный набор описан в таблице выше — этот же набор возвращается живым вызовом `GET /v1/orders/fields`.

## Пример ответа при ошибке

403 — нет скоупа:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'sale' scope"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- [Список заказов](./list.md)
- [Создать заказ](./create.md)
- [Агрегация заказов](./aggregate.md)
- [Entity API](/docs/entity-api)
- [Лимиты и оптимизация](/docs/optimization)