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

Поля заказа

GET /v1/orders/fields

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

Примеры

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

Terminal

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

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

Terminal

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`
`price`	number	Общая сумма заказа. Принимается только при создании: на обновлении запись отклоняется с `400 READONLY_FIELD`, потому что Битрикс24 пересчитывает сумму из позиций корзины. В ответе `/fields` помечено `readonlyOnUpdate`
`discountValue`	number	Значение скидки
`taxValue`	number	Сумма налога
`statusId`	string	Текущий статус заказа. Источник: `GET /v1/order-statuses?filter[type]=O`
`userId`	number	Идентификатор пользователя Битрикс24 — покупателя в интернет-магазине. Источник: `GET /v1/users`
`responsibleId`	number	Ответственный сотрудник. Источник: `GET /v1/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 /v1/orders их нет. Логические поля внутри вложенных объектов приходят как true/false, даты — в UTC формате …Z.

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

Поле	Тип	Описание
`companyId`	number \| null	Идентификатор связанной CRM-компании. `null`, если компания не задана. Доступен для записи и фильтрации. Список: `GET /v1/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`), `4` — компания (`GET /v1/companies`)
`payments`	array \| null	Оплаты заказа, только чтение. Поля оплаты — Оплаты. `null`, если оплат нет
`basketItems`	array	Позиции корзины, только чтение. Поля позиции — Позиции корзины
`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 — нет скоупа: