[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-entities\u002Forders":3,"docs-tabs-entities\u002Forders":6},{"content":4,"lastmod":5},"# Заказы\n\nУправление заказами интернет-магазина: создание, получение, обновление, удаление, поиск, агрегация. Заказ — корневая сущность интернет-магазина: с него начинается путь покупателя, к нему привязываются позиции корзины, оплаты, отгрузки и статусы.\n\nБитрикс24 API: `sale.order.*`\nСкоуп: `sale`\n\n## Операции\n\n- [Создать заказ](.\u002Forders\u002Fcreate.md) — `POST \u002Fv1\u002Forders`\n- [Список заказов](.\u002Forders\u002Flist.md) — `GET \u002Fv1\u002Forders`\n- [Получить заказ](.\u002Forders\u002Fget.md) — `GET \u002Fv1\u002Forders\u002F:id`\n- [Обновить заказ](.\u002Forders\u002Fupdate.md) — `PATCH \u002Fv1\u002Forders\u002F:id`\n- [Удалить заказ](.\u002Forders\u002Fdelete.md) — `DELETE \u002Fv1\u002Forders\u002F:id`\n- [Поиск заказов](.\u002Forders\u002Fsearch.md) — `POST \u002Fv1\u002Forders\u002Fsearch`\n- [Поля заказа](.\u002Forders\u002Ffields.md) — `GET \u002Fv1\u002Forders\u002Ffields`\n- [Агрегация заказов](.\u002Forders\u002Faggregate.md) — `POST \u002Fv1\u002Forders\u002Faggregate`\n\n## Ключевые поля\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | Идентификатор заказа (только чтение) |\n| `accountNumber` | string | Номер счёта для покупателя — порядковый номер заказа на портале |\n| `lid` | string | Идентификатор сайта-источника, всегда `\"s1\"` для облачных порталов |\n| `personTypeId` | number | Идентификатор типа плательщика (юр. лицо, физ. лицо и т. п.). На каждом портале свой набор типов. Узнать ID можно по существующим заказам: `GET \u002Fv1\u002Forders` или `POST \u002Fv1\u002Forders\u002Faggregate` с `groupBy: \"personTypeId\"` |\n| `currency` | string | Валюта заказа. Список: [`GET \u002Fv1\u002Fcurrencies`](\u002Fdocs\u002Fentities\u002Fcurrencies) |\n| `price` | number | Общая сумма заказа |\n| `statusId` | string | Текущий статус заказа. Источник: [`GET \u002Fv1\u002Forder-statuses?filter[type]=O`](.\u002Forder-statuses\u002Flist.md) |\n| `userId` | number | Идентификатор пользователя Битрикс24 — покупателя в интернет-магазине. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `payed` | boolean | Оплачен ли заказ полностью |\n| `canceled` | boolean | Отменён ли заказ |\n| `responsibleId` | number | Ответственный сотрудник. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `dateInsert` | datetime | Дата создания (только чтение) |\n| `dateUpdate` | datetime | Дата последнего изменения (только чтение) |\n\nПолный список полей — [`GET \u002Fv1\u002Forders\u002Ffields`](.\u002Forders\u002Ffields.md).\n\n## Что нужно знать перед работой\n\n1. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{\"lid\": \"s1\", \"personTypeId\": 5, ...}`. Обёртка `fields` не нужна.\n2. **Для создания обязательны три поля:** `lid` (всегда `\"s1\"` для облачных порталов), `personTypeId` (тип плательщика — на каждом портале свой набор), `currency`. Без них `POST \u002Fv1\u002Forders` вернёт `BITRIX_ERROR` с перечислением отсутствующих полей.\n3. **Заказ возвращает связанные сущности вложенно.** `GET \u002Fv1\u002Forders\u002F:id` отдаёт массивы `basketItems[]` (позиции корзины), `payments[]` (оплаты), `propertyValues[]` (свойства заказа), `clients[]` (CRM-привязки) внутри одного объекта. Отдельные эндпоинты [`\u002Fv1\u002Fbasket-items`](.\u002Fbasket-items.md) и [`\u002Fv1\u002Fpayments`](.\u002Fpayments.md) используются для создания и обновления — но для чтения содержимого одного заказа отдельные вызовы не нужны.\n4. **Автоматическая пагинация** включается при `limit > 50`. Общее количество приходит в `meta.total`.\n\n## Связанные сущности\n\nПолноценный жизненный цикл заказа использует семейство сущностей `sale.*`:\n\n| Сущность | Эндпоинт | Назначение |\n|----------|----------|-----------|\n| Позиции корзины | [`GET \u002Fv1\u002Fbasket-items?filter[orderId]=:id`](.\u002Fbasket-items.md) | Товарные позиции заказа — что купил покупатель, по какой цене, с какой скидкой. |\n| Оплаты | [`GET \u002Fv1\u002Fpayments?filter[orderId]=:id`](.\u002Fpayments.md) | Оплаты заказа — сумма, платёжная система, статус «оплачено \u002F возврат». |\n| Статусы заказов | [`GET \u002Fv1\u002Forder-statuses?filter[type]=O`](.\u002Forder-statuses.md) | Каталог статусов для заполнения `statusId`. Тип `O` — статусы заказа, `D` — статусы доставки. |\n\n## Типичный сценарий\n\nОбработка нового заказа из внешней системы (CMS, маркетплейс):\n\n1. Получить список статусов заказов: [`GET \u002Fv1\u002Forder-statuses?filter[type]=O`](.\u002Forder-statuses\u002Flist.md) — найти ID нужного статуса (например, `N` — «Принят»).\n2. Создать заказ: [`POST \u002Fv1\u002Forders`](.\u002Forders\u002Fcreate.md) с минимумом полей (`lid`, `personTypeId`, `currency`, `price`, `statusId`, `userId`).\n3. Добавить позиции корзины: [`POST \u002Fv1\u002Fbasket-items`](.\u002Fbasket-items\u002Fcreate.md) — по одной позиции на товар (`orderId`, `productId`, `quantity`, `price`).\n4. Зарегистрировать оплату: [`POST \u002Fv1\u002Fpayments`](.\u002Fpayments\u002Fcreate.md) — указав `orderId`, `paySystemId`, `sum`.\n5. По мере выполнения — обновить статус: [`PATCH \u002Fv1\u002Forders\u002F:id`](.\u002Forders\u002Fupdate.md) с новым `statusId`.\n\n## Лимиты\n\n| Лимит | Значение |\n|-------|----------|\n| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |\n| Автоматическая пагинация | включается при `limit > 50` |\n| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |\n| Batch-запросы | до 50 операций в [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch) |\n| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) |\n\n## Смотрите также\n\n- [Позиции корзины](.\u002Fbasket-items.md)\n- [Оплаты](.\u002Fpayments.md)\n- [Статусы заказов](.\u002Forder-statuses.md)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Справочник сущностей](\u002Fdocs\u002Fentities-index)\n","2026-06-29",{"orders\u002Fcreate.md":7,"orders\u002Flist.md":8,"orders\u002Fget.md":9,"orders\u002Fupdate.md":10,"orders\u002Fdelete.md":11,"orders\u002Fsearch.md":12,"orders\u002Ffields.md":13,"orders\u002Faggregate.md":14},"\n## Создать заказ\n\n`POST \u002Fv1\u002Forders`\n\nСоздаёт новый заказ интернет-магазина. Тело запроса плоское — без обёртки `fields`.\n\n## Поля запроса (body)\n\n| Поле | Тип | Обяз. | Описание |\n|------|-----|:-----:|---------|\n| `lid` | string | да | Идентификатор сайта-источника. Для облачных порталов всегда `\"s1\"` |\n| `personTypeId` | number | да | Идентификатор типа плательщика. На каждом портале свой набор типов (юр. лицо, физ. лицо и т. п.). ID можно увидеть в существующих заказах через [`GET \u002Fv1\u002Forders`](.\u002Flist.md) или [`POST \u002Fv1\u002Forders\u002Faggregate`](.\u002Faggregate.md) с `groupBy: \"personTypeId\"` |\n| `currency` | string | да | Валюта заказа. Список: [`GET \u002Fv1\u002Fcurrencies`](\u002Fdocs\u002Fentities\u002Fcurrencies) |\n| `price` | number | нет | Общая сумма заказа |\n| `statusId` | string | нет | Статус заказа. По умолчанию — `\"N\"` (новый). Список: [`GET \u002Fv1\u002Forder-statuses?filter[type]=O`](..\u002Forder-statuses\u002Flist.md) |\n| `userId` | number | нет | Идентификатор пользователя Битрикс24 — покупателя в интернет-магазине. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers). Если не передать — Битрикс24 проставит пользователя по умолчанию |\n| `companyId` | number | нет | Идентификатор CRM-компании, связанной с заказом. Источник: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies) |\n| `responsibleId` | number | нет | Ответственный сотрудник. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `comments` | string | нет | Комментарий менеджера к заказу |\n| `userDescription` | string | нет | Комментарий покупателя к заказу |\n| `xmlId` | string | нет | Внешний идентификатор для синхронизации с внешними системами |\n| `canceled` | boolean | нет | Отменён ли заказ |\n| `reasonCanceled` | string | нет | Причина отмены |\n| `discountValue` | number | нет | Значение скидки |\n\nПолный список полей — [`GET \u002Fv1\u002Forders\u002Ffields`](.\u002Ffields.md).\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"lid\": \"s1\",\n    \"personTypeId\": 5,\n    \"currency\": \"RUB\",\n    \"price\": 12500,\n    \"statusId\": \"N\",\n    \"userId\": 1,\n    \"comments\": \"Заказ из мобильного приложения\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"lid\": \"s1\",\n    \"personTypeId\": 5,\n    \"currency\": \"RUB\",\n    \"price\": 12500,\n    \"statusId\": \"N\",\n    \"userId\": 1,\n    \"comments\": \"Заказ из мобильного приложения\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    lid: 's1',\n    personTypeId: 5,\n    currency: 'RUB',\n    price: 12500,\n    statusId: 'N',\n    userId: 1,\n    comments: 'Заказ из мобильного приложения',\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Order ID:', data.id)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    lid: 's1',\n    personTypeId: 5,\n    currency: 'RUB',\n    price: 12500,\n    statusId: 'N',\n    userId: 1,\n    comments: 'Заказ из мобильного приложения',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\nВозвращается полный объект созданного заказа со всеми полями.\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | Идентификатор созданного заказа |\n| `accountNumber` | string | Порядковый номер заказа на портале (генерируется автоматически) |\n| `dateInsert` | datetime | Дата создания |\n| `dateStatus` | datetime | Дата установки текущего статуса |\n\nОстальные поля — см. [Поля заказа](.\u002Ffields.md).\n\nURL заказа в Битрикс24 строится из `id`:\n\n```\nhttps:\u002F\u002F\u003Cportal>.bitrix24.ru\u002Fshop\u002Forders\u002Fdetails\u002F\u003Cid>\u002F\n```\n\n`\u003Cportal>` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 859,\n    \"accountNumber\": \"450\",\n    \"lid\": \"s1\",\n    \"personTypeId\": 5,\n    \"currency\": \"RUB\",\n    \"price\": 12500,\n    \"discountValue\": 0,\n    \"taxValue\": 0,\n    \"statusId\": \"N\",\n    \"dateInsert\": \"2026-05-13T11:42:18.000Z\",\n    \"dateUpdate\": \"2026-05-13T11:42:18.000Z\",\n    \"dateStatus\": \"2026-05-13T11:42:18.000Z\",\n    \"payed\": false,\n    \"canceled\": false,\n    \"marked\": false,\n    \"responsibleId\": 1,\n    \"userId\": 1,\n    \"companyId\": null,\n    \"clients\": [\n      { \"entityTypeId\": 3, \"entityId\": 2471, \"isPrimary\": true, \"roleId\": 0, \"sort\": 0 }\n    ],\n    \"comments\": \"Заказ из мобильного приложения\",\n    \"xmlId\": \"\",\n    \"externalOrder\": false\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — не переданы обязательные поля:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Required fields: personTypeId, currency, lid\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Не переданы обязательные поля — сообщение содержит их список (`Required fields: ...`) |\n| 400 | `READONLY_FIELD` | Передано поле только для чтения — `accountNumber`, `payed`, даты оплаты и статуса и другие |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Ссылки на справочники не проверяются.** Существование `statusId`, `userId`, `personTypeId`, `companyId` при создании не проверяется — несуществующие значения принимаются без ошибки. Заказ создаётся с переданными значениями, целостность ссылок остаётся на стороне приложения.\n\n**`statusId` усекается до 2 символов.** Значение длиннее двух символов сохраняется обрезанным без ошибки: `statusId: \"ZZZ\"` сохранится как `\"ZZ\"`. Используйте только реальные двухсимвольные коды статусов из [`GET \u002Fv1\u002Forder-statuses`](..\u002Forder-statuses\u002Flist.md).\n\n**Поля только для создания.** `price`, `marked` и `reasonMarked` применяются при создании заказа, но на обновлении [`PATCH \u002Fv1\u002Forders\u002F:id`](.\u002Fupdate.md) игнорируются. Чтобы изменить сумму после создания, меняйте позиции корзины через [`\u002Fv1\u002Fbasket-items`](..\u002Fbasket-items.md).\n\n**`payed` нельзя установить.** Поле «оплачен» управляется подсистемой оплат — при создании и обновлении оно игнорируется и возвращает `false`. Попытка передать `payed` отклоняется с `400 READONLY_FIELD`. Оплату регистрируйте через [`POST \u002Fv1\u002Fpayments`](..\u002Fpayments\u002Fcreate.md).\n\n**Номер счёта генерируется автоматически.** Поле `accountNumber` присваивается при создании. Передавать его в запросе нельзя — попытка отклоняется с `400 READONLY_FIELD`.\n\n**Позиции корзины и оплаты добавляются отдельно.** Заказ — это контейнер. После `POST \u002Fv1\u002Forders` для добавления товаров вызовите [`POST \u002Fv1\u002Fbasket-items`](..\u002Fbasket-items\u002Fcreate.md) с `orderId`, для регистрации оплаты — [`POST \u002Fv1\u002Fpayments`](..\u002Fpayments\u002Fcreate.md).\n\n## Смотрите также\n\n- [Список заказов](.\u002Flist.md)\n- [Получить заказ](.\u002Fget.md)\n- [Обновить заказ](.\u002Fupdate.md)\n- [Добавить позицию корзины](..\u002Fbasket-items\u002Fcreate.md)\n- [Создать оплату](..\u002Fpayments\u002Fcreate.md)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Список заказов\n\n`GET \u002Fv1\u002Forders`\n\nВозвращает список заказов интернет-магазина с поддержкой фильтрации и автоматической пагинации.\n\n## Параметры\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|---------|\n| `limit` | number | `50` | Количество записей (до 5000). При `limit > 50` Вайбкод автоматически запрашивает несколько страниц у Битрикс24 |\n| `offset` | number | `0` | Пропустить N записей. Округляется вниз до кратного 50 — заказы отдаются страницами по 50, поэтому `offset` меньше 50 равнозначен `0`. При `offset ≥ 2500` рекомендуется `limit ≤ 500` |\n| `select` | string | — | Выборка полей: `?select=id,price,currency,statusId` |\n| `order` | object | — | Сортировка: `?order[id]=desc` |\n| `filter` | object | — | Фильтрация по полям `GET \u002Fv1\u002Forders\u002Ffields`.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering). Пример: `?filter[statusId]=N` |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders?limit=10&filter[statusId]=N&order[id]=desc\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders?limit=10&filter[statusId]=N&order[id]=desc\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders?limit=10&filter[statusId]=N&order[id]=desc', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Найдено ${meta.total} заказов`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders?limit=10&filter[statusId]=N&order[id]=desc', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив заказов (каждый содержит все поля — см. [Поля заказа](.\u002Ffields.md)) |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n\nURL любого заказа из массива `data` — его `id`:\n\n```\nhttps:\u002F\u002F\u003Cportal>.bitrix24.ru\u002Fshop\u002Forders\u002Fdetails\u002F\u003Cid>\u002F\n```\n\n`\u003Cportal>` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 845,\n      \"accountNumber\": \"443\",\n      \"price\": 100,\n      \"currency\": \"RUB\",\n      \"statusId\": \"N\",\n      \"userId\": 1,\n      \"personTypeId\": 5,\n      \"lid\": \"s1\",\n      \"payed\": false,\n      \"canceled\": false,\n      \"responsibleId\": 1,\n      \"dateInsert\": \"2026-04-21T06:48:16.000Z\",\n      \"dateUpdate\": \"2026-04-21T06:48:16.000Z\"\n    },\n    {\n      \"id\": 841,\n      \"accountNumber\": \"441\",\n      \"price\": 100.5,\n      \"currency\": \"RUB\",\n      \"statusId\": \"N\",\n      \"userId\": 9,\n      \"personTypeId\": 5,\n      \"lid\": \"s1\",\n      \"payed\": false,\n      \"canceled\": false,\n      \"responsibleId\": 1,\n      \"dateInsert\": \"2026-04-04T20:02:28.000Z\",\n      \"dateUpdate\": \"2026-04-04T20:02:28.000Z\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 194,\n    \"hasMore\": true\n  }\n}\n```\n\nПоказаны основные поля. Полный список — [Поля заказа](.\u002Ffields.md).\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'sale' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | Фильтр по полю, которого нет в схеме. Список полей: [`GET \u002Fv1\u002Forders\u002Ffields`](.\u002Ffields.md) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Автоматическая пагинация:** при `limit > 50` Вайбкод автоматически запрашивает несколько страниц у Битрикс24 и возвращает все записи в одном ответе. `meta.total` отражает общее количество записей, удовлетворяющих фильтру.\n\n**Когда использовать `search` вместо `list`:** [`POST \u002Fv1\u002Forders\u002Fsearch`](.\u002Fsearch.md) передаёт параметры в теле запроса, а не в строке запроса — подходит для сложных фильтров с множеством условий.\n\n## Смотрите также\n\n- [Поиск заказов](.\u002Fsearch.md)\n- [Получить заказ](.\u002Fget.md)\n- [Создать заказ](.\u002Fcreate.md)\n- [Поля заказа](.\u002Ffields.md)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Получить заказ\n\n`GET \u002Fv1\u002Forders\u002F:id`\n\nВозвращает один заказ по идентификатору со всеми полями.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | Идентификатор заказа |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Заказ:', data.accountNumber, '—', data.price, data.currency)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\nОбъект заказа со всеми полями — см. [Поля заказа](.\u002Ffields.md). Дополнительно ответ содержит вложенные массивы:\n\n| Поле | Описание |\n|------|---------|\n| `basketItems[]` | Полные объекты [позиций корзины](..\u002Fbasket-items.md) этого заказа |\n| `payments[]` | Полные объекты [оплат](..\u002Fpayments.md) этого заказа |\n| `propertyValues[]` | Значения свойств заказа: ФИО, e-mail, телефон, адрес доставки и другие. Набор зависит от настройки портала |\n| `clients[]` | CRM-привязки к контактам и компаниям. Каждый элемент: `{entityTypeId, entityId, isPrimary, roleId, sort}` |\n| `requisiteLink` | Связь с реквизитами получателя |\n| `tradeBindings[]` | Привязки к внешним торговым площадкам |\n\nМассивы `clients`, `payments`, `basketItems`, `propertyValues` возвращает только `GET \u002Fv1\u002Forders\u002F:id` — в списке [`GET \u002Fv1\u002Forders`](.\u002Flist.md) их нет. Все четыре только для чтения. Логические поля внутри вложенных объектов приходят как `true`\u002F`false` — `clients[].isPrimary`, `payments[].paid`, `basketItems[].vatIncluded` и другие, даты — в UTC формате `…Z`.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 845,\n    \"accountNumber\": \"443\",\n    \"lid\": \"s1\",\n    \"personTypeId\": 5,\n    \"currency\": \"RUB\",\n    \"price\": 100,\n    \"discountValue\": 0,\n    \"taxValue\": 0,\n    \"statusId\": \"N\",\n    \"dateInsert\": \"2026-04-21T06:48:16.000Z\",\n    \"dateUpdate\": \"2026-04-21T06:48:16.000Z\",\n    \"dateStatus\": \"2026-04-21T06:48:16.000Z\",\n    \"payed\": false,\n    \"canceled\": false,\n    \"marked\": false,\n    \"deducted\": false,\n    \"responsibleId\": 1,\n    \"userId\": 1,\n    \"companyId\": 15,\n    \"clients\": [\n      { \"entityTypeId\": 3, \"entityId\": 2471, \"isPrimary\": true, \"roleId\": 0, \"sort\": 0 },\n      { \"entityTypeId\": 4, \"entityId\": 15, \"isPrimary\": true, \"roleId\": 0, \"sort\": 0 }\n    ],\n    \"basketItems\": [\n      {\n        \"id\": 187,\n        \"productId\": 1119,\n        \"name\": \"Спортивный Костюм Розовый Вихрь\",\n        \"price\": 12,\n        \"currency\": \"RUB\",\n        \"quantity\": 1,\n        \"vatRate\": 0,\n        \"vatIncluded\": true\n      }\n    ],\n    \"payments\": [\n      {\n        \"id\": 117,\n        \"paySystemId\": 11,\n        \"paySystemName\": \"Наличные\",\n        \"sum\": 100,\n        \"currency\": \"RUB\",\n        \"paid\": true,\n        \"datePaid\": \"2026-04-21T06:48:16.000Z\"\n      }\n    ],\n    \"propertyValues\": [\n      { \"id\": 9311, \"orderPropsId\": 41, \"code\": \"EMAIL\", \"name\": \"E-Mail\", \"value\": \"buyer@example.com\" }\n    ],\n    \"comments\": \"\",\n    \"xmlId\": \"\",\n    \"externalOrder\": false\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — заказ не найден:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"order is not exists\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Заказ с таким ID не найден |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Поля заказа](.\u002Ffields.md)\n- [Обновить заказ](.\u002Fupdate.md)\n- [Удалить заказ](.\u002Fdelete.md)\n- [Список заказов](.\u002Flist.md)\n- [Позиции корзины заказа](..\u002Fbasket-items.md)\n- [Оплаты заказа](..\u002Fpayments.md)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Обновить заказ\n\n`PATCH \u002Fv1\u002Forders\u002F:id`\n\nОбновляет поля существующего заказа. Передавайте только изменяемые поля плоско в корне JSON — без обёртки `fields`.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | Идентификатор заказа |\n\n## Поля запроса (body)\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `statusId` | string | Новый статус заказа. Список: [`GET \u002Fv1\u002Forder-statuses?filter[type]=O`](..\u002Forder-statuses\u002Flist.md). Усекается до 2 символов без ошибки |\n| `discountValue` | number | Значение скидки |\n| `canceled` | boolean | Отменён ли заказ |\n| `reasonCanceled` | string | Причина отмены |\n| `comments` | string | Комментарий менеджера |\n| `userDescription` | string | Комментарий покупателя |\n| `responsibleId` | number | Ответственный сотрудник |\n| `userId` | number | Пользователь Битрикс24 — покупатель. Существование не проверяется |\n| `companyId` | number | Идентификатор CRM-компании заказа. Источник: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies). Приходит `null`, если компания не задана |\n| `xmlId` | string | Внешний идентификатор |\n\nПолный список редактируемых полей — [`GET \u002Fv1\u002Forders\u002Ffields`](.\u002Ffields.md) (поля без флага `readonly`).\n\n**`price`, `marked` и `reasonMarked` на обновлении игнорируются.** Запрос вернёт `200`, но эти поля не сохранятся — они применяются только при [создании](.\u002Fcreate.md). `price` пересчитывается из позиций корзины: переданная вручную сумма игнорируется, при пустой корзине становится `0`. Чтобы изменить сумму, меняйте [позиции корзины](..\u002Fbasket-items\u002Fcreate.md). `payed` доступен только для чтения — управляется подсистемой оплат, попытка передать его вернёт `400 READONLY_FIELD`.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"statusId\": \"F\",\n    \"comments\": \"Закрыт после полной оплаты\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"statusId\": \"F\",\n    \"comments\": \"Закрыт после полной оплаты\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    statusId: 'F',\n    comments: 'Закрыт после полной оплаты',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F845', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    statusId: 'F',\n    comments: 'Закрыт после полной оплаты',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `data` | object | Обновлённый объект заказа со всеми полями (см. [Поля заказа](.\u002Ffields.md)) |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 845,\n    \"accountNumber\": \"443\",\n    \"statusId\": \"F\",\n    \"price\": 100,\n    \"currency\": \"RUB\",\n    \"payed\": true,\n    \"canceled\": false,\n    \"comments\": \"Закрыт после полной оплаты\",\n    \"dateInsert\": \"2026-04-21T06:48:16.000Z\",\n    \"dateUpdate\": \"2026-05-13T11:45:32.000Z\",\n    \"dateStatus\": \"2026-05-13T11:45:32.000Z\",\n    \"userId\": 1,\n    \"companyId\": 15,\n    \"clients\": [\n      { \"entityTypeId\": 3, \"entityId\": 2471, \"isPrimary\": true, \"roleId\": 0, \"sort\": 0 },\n      { \"entityTypeId\": 4, \"entityId\": 15, \"isPrimary\": true, \"roleId\": 0, \"sort\": 0 }\n    ],\n    \"responsibleId\": 1\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — заказ не найден:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"order is not exists\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Заказ с таким ID не найден |\n| 400 | `BITRIX_ERROR` | Некорректное значение поля — например, неизвестный `statusId` |\n| 400 | `READONLY_FIELD` | Передано поле только для чтения — например `accountNumber`. Номер заказа присваивается автоматически |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Дата `dateStatus` обновляется автоматически.** При изменении `statusId` поле `dateStatus` получает текущее время — не передавайте его в запросе.\n\n**Поля `accountNumber`, `dateInsert`, `personTypeXmlId`, `statusXmlId` и другие системные — только для чтения.** Попытка передать их на обновлении отклоняется с `400 READONLY_FIELD`.\n\n## Смотрите также\n\n- [Получить заказ](.\u002Fget.md)\n- [Список заказов](.\u002Flist.md)\n- [Удалить заказ](.\u002Fdelete.md)\n- [Поля заказа](.\u002Ffields.md)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Удалить заказ\n\n`DELETE \u002Fv1\u002Forders\u002F:id`\n\nУдаляет заказ по идентификатору вместе со связанными позициями корзины и оплатами. Восстановить удалённый заказ через API нельзя — создавайте новый при необходимости.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | Идентификатор заказа |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F859\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F859\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F859', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Заказ удалён')\n}\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002F859', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Заказ удалён')\n}\n```\n\n## Ответ\n\nПри успешном удалении возвращается HTTP-статус `204 No Content` с пустым телом — успех проверяется по статусу.\n\n## Пример ответа\n\n```http\nHTTP\u002F1.1 204 No Content\n```\n\n## Пример ответа при ошибке\n\n422 — заказ не найден:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"order is not exists\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Заказ с таким ID не найден или уже удалён |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Каскадное удаление.** Удаление заказа автоматически удаляет связанные позиции корзины и оплаты — отдельно вызывать `DELETE \u002Fv1\u002Fbasket-items\u002F:id` или `DELETE \u002Fv1\u002Fpayments\u002F:id` не нужно.\n\n**Альтернатива — отмена вместо удаления.** Чтобы сохранить историю и связи, лучше отменить заказ через [`PATCH \u002Fv1\u002Forders\u002F:id`](.\u002Fupdate.md) с `{\"canceled\": true, \"reasonCanceled\": \"...\"}` — заказ останется в выборках с `filter[canceled]=true`.\n\n## Смотрите также\n\n- [Обновить заказ](.\u002Fupdate.md)\n- [Список заказов](.\u002Flist.md)\n- [Получить заказ](.\u002Fget.md)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Поиск заказов\n\n`POST \u002Fv1\u002Forders\u002Fsearch`\n\nПоиск заказов с фильтрацией, сортировкой и автоматической пагинацией. Аналогичен [`GET \u002Fv1\u002Forders`](.\u002Flist.md), но параметры передаются в теле POST-запроса — подходит для сложных запросов с большим количеством условий.\n\n## Поля запроса (body)\n\n| Поле | Тип | По умолч. | Описание |\n|------|-----|-----------|---------|\n| `filter` | object | — | Фильтрация по полям `GET \u002Fv1\u002Forders\u002Ffields`.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering) |\n| `limit` | number | `50` | Количество записей (до 5000) |\n| `select` | string[] | — | Выборка полей: `[\"id\", \"price\", \"currency\", \"statusId\"]` |\n| `order` | object | — | Сортировка: `{ \"id\": \"desc\" }` |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"statusId\": \"N\", \"payed\": false },\n    \"limit\": 10,\n    \"select\": [\"id\", \"price\", \"currency\", \"statusId\", \"dateInsert\"]\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"statusId\": \"N\", \"payed\": false },\n    \"limit\": 10,\n    \"select\": [\"id\", \"price\", \"currency\", \"statusId\", \"dateInsert\"]\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { statusId: 'N', payed: false },\n    limit: 10,\n    select: ['id', 'price', 'currency', 'statusId', 'dateInsert'],\n  }),\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log('Найдено:', meta.total)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { statusId: 'N', payed: false },\n    limit: 10,\n    select: ['id', 'price', 'currency', 'statusId', 'dateInsert'],\n  }),\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив заказов (поля — см. [Поля заказа](.\u002Ffields.md)) |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n\nURL любого заказа из массива `data` — его `id`:\n\n```\nhttps:\u002F\u002F\u003Cportal>.bitrix24.ru\u002Fshop\u002Forders\u002Fdetails\u002F\u003Cid>\u002F\n```\n\n`\u003Cportal>` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 845,\n      \"price\": 100,\n      \"currency\": \"RUB\",\n      \"statusId\": \"N\",\n      \"dateInsert\": \"2026-04-21T06:48:16.000Z\"\n    },\n    {\n      \"id\": 841,\n      \"price\": 100.5,\n      \"currency\": \"RUB\",\n      \"statusId\": \"N\",\n      \"dateInsert\": \"2026-04-04T20:02:28.000Z\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 181,\n    \"hasMore\": true\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n400 — фильтр по несуществующему полю:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"UNKNOWN_FILTER_FIELD\",\n    \"message\": \"Unknown filter field 'foo' for entity 'orders'. Available: id, accountNumber, price, currency, statusId, userId, ...\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `UNKNOWN_FILTER_FIELD` | Фильтр по полю, которого нет в схеме. Список полей: [`GET \u002Fv1\u002Forders\u002Ffields`](.\u002Ffields.md) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**`select` ограничивает поля в ответе.** Если передан `select`, в каждом элементе `data[]` будут только перечисленные поля. Без `select` возвращаются все поля заказа.\n\n## Смотрите также\n\n- [Список заказов](.\u002Flist.md)\n- [Получить заказ](.\u002Fget.md)\n- [Поля заказа](.\u002Ffields.md)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Поля заказа\n\n`GET \u002Fv1\u002Forders\u002Ffields`\n\nВозвращает схему полей заказа: типы, флаги только-для-чтения, список агрегируемых полей.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { data } = await res.json()\nconsole.log('Поля заказа:', Object.keys(data.fields))\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | Идентификатор заказа (только чтение) |\n| `accountNumber` | string | Порядковый номер заказа на портале. Только чтение — присваивается автоматически, запись отклоняется с `400 READONLY_FIELD` |\n| `lid` | string | Идентификатор сайта-источника (всегда `\"s1\"` для облачных порталов) |\n| `personTypeId` | number | Идентификатор типа плательщика |\n| `currency` | string | Валюта заказа. Список: [`GET \u002Fv1\u002Fcurrencies`](\u002Fdocs\u002Fentities\u002Fcurrencies) |\n| `price` | number | Общая сумма заказа. Задаётся при создании. На обновлении значение пересчитывается из позиций корзины — переданное вручную игнорируется, при пустой корзине становится `0` |\n| `discountValue` | number | Значение скидки |\n| `taxValue` | number | Сумма налога |\n| `statusId` | string | Текущий статус заказа. Источник: [`GET \u002Fv1\u002Forder-statuses?filter[type]=O`](..\u002Forder-statuses\u002Flist.md) |\n| `userId` | number | Идентификатор пользователя Битрикс24 — покупателя в интернет-магазине. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `responsibleId` | number | Ответственный сотрудник. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `payed` | boolean | Оплачен ли заказ полностью. Только чтение — управляется подсистемой оплат. Запись отклоняется с `400 READONLY_FIELD` |\n| `canceled` | boolean | Отменён ли заказ |\n| `marked` | boolean | Отмечен ли заказ как проблемный. Задаётся при создании. На обновлении игнорируется |\n| `deducted` | boolean | Списан ли товар со склада |\n| `reasonCanceled` | string \\| null | Причина отмены. `null`, если заказ не отменён |\n| `reasonMarked` | string \\| null | Причина пометки. `null`, если пометки нет |\n| `additionalInfo` | string \\| null | Дополнительная информация. `null`, если не задана |\n| `comments` | string \\| null | Комментарий менеджера к заказу. `null`, если не задан |\n| `userDescription` | string \\| null | Комментарий покупателя к заказу. `null`, если не задан |\n| `orderTopic` | string \\| null | Тема заказа. `null`, если не задана |\n| `xmlId` | string | Внешний идентификатор для синхронизации |\n| `id1c` | string \\| null | Идентификатор в 1С. `null`, если заказ не синхронизирован с 1С |\n| `version1c` | string \\| null | Версия в 1С. `null`, если заказ не синхронизирован с 1С |\n| `updated1c` | boolean | Обновлён ли заказ через 1С |\n| `externalOrder` | boolean | Создан ли заказ во внешней системе |\n| `recountFlag` | boolean | Флаг автоматического пересчёта |\n| `affiliateId` | number \\| null | Идентификатор партнёра партнёрской программы. `null`, если не задан |\n| `lockedBy` | number \\| null | Идентификатор пользователя, заблокировавшего заказ (актуально для коробочных порталов). `null`, если заказ не заблокирован |\n| `dateLock` | datetime \\| null | Время блокировки. `null`, если заказ не заблокирован |\n| `recurringId` | number \\| null | Идентификатор подписки (если заказ создан из повторяющегося шаблона). `null`, если заказ не из подписки |\n| `dateInsert` | datetime | Дата создания (только чтение) |\n| `dateUpdate` | datetime | Дата последнего изменения (только чтение) |\n| `dateCanceled` | datetime \\| null | Дата отмены (только чтение). `null`, если заказ не отменён |\n| `dateStatus` | datetime | Дата установки текущего статуса (только чтение) |\n| `empCanceledId` | number \\| null | Сотрудник, отменивший заказ (только чтение). `null`, если заказ не отменён |\n| `empMarkedId` | number \\| null | Сотрудник, поставивший пометку (только чтение). `null`, если пометки нет |\n| `empStatusId` | number \\| null | Сотрудник, последний раз менявший статус (только чтение). `null`, если статус не менялся |\n\n### Дополнительные поля и вложенные массивы\n\nЭти поля тоже входят в схему `GET \u002Fv1\u002Forders\u002Ffields`. `companyId` доступен для чтения и записи и по нему можно фильтровать, остальные — только для чтения. Массивы `clients`, `payments`, `basketItems`, `propertyValues` возвращает только [`GET \u002Fv1\u002Forders\u002F:id`](.\u002Fget.md) — в списочном ответе [`GET \u002Fv1\u002Forders`](.\u002Flist.md) их нет. Логические поля внутри вложенных объектов приходят как `true`\u002F`false`, даты — в UTC формате `…Z`.\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `companyId` | number \\| null | Идентификатор связанной CRM-компании. `null`, если компания не задана. Доступен для записи и фильтрации. Список: [`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies) |\n| `dateMarked` | datetime \\| null | Дата последней пометки заказа (только чтение) |\n| `personTypeXmlId` | string \\| null | Внешний идентификатор типа плательщика (только чтение) |\n| `statusXmlId` | string \\| null | Внешний идентификатор статуса (только чтение) |\n| `version` | number | Внутренний номер версии записи (только чтение) |\n| `clients` | array | CRM-привязки заказа, только чтение. Каждый элемент: `{entityTypeId, entityId, isPrimary, roleId, sort}`, где `isPrimary` — `true`\u002F`false`. `entityTypeId` равен `3` — контакт ([`GET \u002Fv1\u002Fcontacts`](\u002Fdocs\u002Fentities\u002Fcontacts)), `4` — компания ([`GET \u002Fv1\u002Fcompanies`](\u002Fdocs\u002Fentities\u002Fcompanies)) |\n| `payments` | array \\| null | Оплаты заказа, только чтение. Поля оплаты — [Оплаты](..\u002Fpayments.md). `null`, если оплат нет |\n| `basketItems` | array | Позиции корзины, только чтение. Поля позиции — [Позиции корзины](..\u002Fbasket-items.md) |\n| `propertyValues` | array | Значения свойств заказа — ФИО, e-mail, телефон, адрес доставки, только чтение. Набор зависит от настройки портала |\n| `requisiteLink` | object | Связь с реквизитами получателя (requisiteId\u002FbankDetailId\u002FmcRequisiteId\u002FmcBankDetailId); `[]` если не задана; только чтение |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"id\": { \"type\": \"number\", \"readonly\": true },\n      \"accountNumber\": { \"type\": \"string\", \"readonly\": true },\n      \"price\": { \"type\": \"number\", \"readonly\": false },\n      \"currency\": { \"type\": \"string\", \"readonly\": false },\n      \"statusId\": { \"type\": \"string\", \"readonly\": false },\n      \"userId\": { \"type\": \"number\", \"readonly\": false },\n      \"dateInsert\": { \"type\": \"datetime\", \"readonly\": true },\n      \"dateUpdate\": { \"type\": \"datetime\", \"readonly\": true },\n      \"payed\": { \"type\": \"boolean\", \"readonly\": true },\n      \"canceled\": { \"type\": \"boolean\", \"readonly\": false }\n    },\n    \"aggregatable\": [\"price\", \"statusId\", \"payed\", \"canceled\", \"personTypeId\", \"responsibleId\", \"userId\"],\n    \"batch\": [\"create\", \"update\", \"delete\"]\n  }\n}\n```\n\nПоказаны самые важные поля. Полный набор описан в таблице выше — этот же набор возвращается живым вызовом `GET \u002Fv1\u002Forders\u002Ffields`.\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'sale' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Список заказов](.\u002Flist.md)\n- [Создать заказ](.\u002Fcreate.md)\n- [Агрегация заказов](.\u002Faggregate.md)\n- [Entity API](\u002Fdocs\u002Fentity-api)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Агрегация заказов\n\n`POST \u002Fv1\u002Forders\u002Faggregate`\n\nПодсчёт количества заказов и числовые агрегации (`sum`, `avg`, `min`, `max`) по полю `price`. Поддерживает фильтрацию и группировку по `statusId`, `payed`, `canceled`, `personTypeId`, `responsibleId`, `userId`.\n\n## Стандартные поля\n\n| Поле | Назначение |\n|------|------------|\n| `price` | Единственное числовое поле — подходит для `sum` \u002F `avg` \u002F `min` \u002F `max` |\n| `statusId` | Категориальное — используется в `groupBy` (статусы заказов) |\n| `payed`, `canceled` | Логические — используются в `groupBy` (оплачен \u002F отменён) |\n| `personTypeId`, `responsibleId`, `userId` | Идентификаторы — используются в `groupBy` (по типу плательщика, ответственному, покупателю) |\n\nПолный список агрегируемых полей — массив `aggregatable` в [`GET \u002Fv1\u002Forders\u002Ffields`](.\u002Ffields.md).\n\n## Поля запроса (body)\n\n| Поле | Тип | Обяз. | Описание |\n|------|-----|:-----:|---------|\n| `aggregate` | array | нет | Массив агрегаций: `[{ \"field\": \"price\", \"function\": \"sum\" }]`. Функции: `count`, `sum`, `avg`, `min`, `max`. Для `count` поле — `\"*\"`. Без параметра — только `count` (один запрос в Битрикс24, записи не выгружаются) |\n| `filter` | object | нет | Фильтрация — те же поля, что в [`GET \u002Fv1\u002Forders`](.\u002Flist.md). [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering) |\n| `groupBy` | string \\| string[] | нет | Поле или массив полей для группировки (максимум 5). Допустимые значения — из массива `aggregatable` |\n| `groupOrderBy` | array | нет | Сортировка групп: `[{ \"field\": \"price:sum\", \"direction\": \"desc\" }]`. Поля: `count`, имя dim из `groupBy`, или `\u003Cfield>:\u003Cfunction>` |\n| `groupLimit` | number | нет | Ограничение количества возвращаемых групп (1-1000) |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [\n      { \"field\": \"price\", \"function\": \"sum\" },\n      { \"field\": \"price\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"statusId\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [\n      { \"field\": \"price\", \"function\": \"sum\" },\n      { \"field\": \"price\", \"function\": \"avg\" }\n    ],\n    \"groupBy\": \"statusId\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    aggregate: [\n      { field: 'price', function: 'sum' },\n      { field: 'price', function: 'avg' },\n    ],\n    groupBy: 'statusId',\n  }),\n})\n\nconst { success, data } = await res.json()\n\u002F\u002F data.groups — массив групп по statusId\nconsole.log(data.groups)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Forders\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    aggregate: [{ field: 'price', function: 'sum' }],\n    groupBy: 'statusId',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Другие сценарии\n\nПодсчёт записей — `count` с полем `\"*\"`, самый быстрый запрос без выгрузки записей. Без массива `aggregate` результат тот же:\n\n```json\n{ \"aggregate\": [{ \"field\": \"*\", \"function\": \"count\" }] }\n```\n\nСумма по всем заказам без группировки:\n\n```json\n{\n  \"aggregate\": [{ \"field\": \"price\", \"function\": \"sum\" }]\n}\n```\n\nТоп-3 статуса по сумме оплат с сортировкой:\n\n```json\n{\n  \"aggregate\": [{ \"field\": \"price\", \"function\": \"sum\" }],\n  \"groupBy\": \"statusId\",\n  \"groupOrderBy\": [{ \"field\": \"price:sum\", \"direction\": \"desc\" }],\n  \"groupLimit\": 3\n}\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.count` | number | Общее количество заказов, соответствующих фильтру |\n| `data.aggregates` | object | Результаты агрегаций: `{ \"price\": { \"sum\": ..., \"avg\": ... } }` |\n| `data.groups` | array | Группы (присутствует только при `groupBy`). Каждый элемент: поля группировки + `count` + `aggregates` |\n| `data.meta.totalRecords` | number | Общее количество записей, обработанных для агрегации |\n| `data.meta.recordsProcessed` | number | Количество обработанных записей (до 5000) |\n| `data.meta.truncated` | boolean | `true`, если записей больше 5000 — агрегация по первым 5000 |\n| `data.meta.groupTotal` | number | Количество групп до применения `groupLimit` (только при `groupBy`) |\n| `data.meta.groupsTruncated` | boolean | Был ли список групп обрезан `groupLimit` |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"count\": 194,\n    \"aggregates\": {\n      \"price\": { \"sum\": 2890284.0999999996 }\n    },\n    \"groups\": [\n      {\n        \"statusId\": \"N\",\n        \"count\": 181,\n        \"aggregates\": { \"price\": { \"sum\": 2876316.6299999994 } }\n      },\n      {\n        \"statusId\": \"T\",\n        \"count\": 8,\n        \"aggregates\": { \"price\": { \"sum\": 2998.5 } }\n      },\n      {\n        \"statusId\": \"P\",\n        \"count\": 6,\n        \"aggregates\": { \"price\": { \"sum\": 9958.97 } }\n      },\n      {\n        \"statusId\": \"F\",\n        \"count\": 1,\n        \"aggregates\": { \"price\": { \"sum\": 1010 } }\n      },\n      {\n        \"statusId\": \"S\",\n        \"count\": 1,\n        \"aggregates\": { \"price\": { \"sum\": 0 } }\n      }\n    ],\n    \"meta\": {\n      \"totalRecords\": 194,\n      \"recordsProcessed\": 194,\n      \"truncated\": false,\n      \"groupTotal\": 5,\n      \"groupsTruncated\": false\n    }\n  }\n}\n```\n\nБез `groupBy` поле `data.groups` в ответе отсутствует.\n\n## Пример ответа при ошибке\n\n400 — поле в `groupBy` не агрегируется:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"groupBy field 'foo' is not aggregatable on this entity. Available: price, statusId, payed, canceled, personTypeId, responsibleId, userId.\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | Неизвестная функция или несуществующее поле в `aggregate` \u002F `groupBy` — сообщение содержит список допустимых полей |\n| 400 | `INVALID_PARAMS` | Передано больше 5 полей в `groupBy` |\n| 400 | `INVALID_PARAMS` | Зарезервированные ключевые слова в `groupBy`: `count`, `aggregates`, `meta`, `groups` |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**`count` против числовых функций.** `count` считается одним запросом в Битрикс24 — записи не выгружаются, время ответа не зависит от количества заказов. `sum` \u002F `avg` \u002F `min` \u002F `max` подгружают записи постранично (максимум 5000) и считают на стороне Вайбкод. При более чем 5000 записях `meta.truncated` будет `true`, и агрегация выполняется по первым 5000.\n\n**Логические поля в группировке.** `groupBy: \"payed\"` или `groupBy: \"canceled\"` возвращает группы со значениями `true` \u002F `false`.\n\n## Смотрите также\n\n- [Список заказов](.\u002Flist.md)\n- [Поиск заказов](.\u002Fsearch.md)\n- [Поля заказа](.\u002Ffields.md)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n"]