# Заказы

Управление заказами интернет-магазина: создание, получение, обновление, удаление, поиск, агрегация. Заказ — корневая сущность интернет-магазина: с него начинается путь покупателя, к нему привязываются позиции корзины, оплаты, отгрузки и статусы.

Битрикс24 API: `sale.order.*`
Скоуп: `sale`

## Операции

- [Создать заказ](./orders/create.md) — `POST /v1/orders`
- [Список заказов](./orders/list.md) — `GET /v1/orders`
- [Получить заказ](./orders/get.md) — `GET /v1/orders/:id`
- [Обновить заказ](./orders/update.md) — `PATCH /v1/orders/:id`
- [Удалить заказ](./orders/delete.md) — `DELETE /v1/orders/:id`
- [Поиск заказов](./orders/search.md) — `POST /v1/orders/search`
- [Поля заказа](./orders/fields.md) — `GET /v1/orders/fields`
- [Агрегация заказов](./orders/aggregate.md) — `POST /v1/orders/aggregate`

## Ключевые поля

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор заказа (только чтение) |
| `accountNumber` | string | Номер счёта для покупателя — порядковый номер заказа на портале |
| `lid` | string | Идентификатор сайта-источника, всегда `"s1"` для облачных порталов |
| `personTypeId` | number | Идентификатор типа плательщика (юр. лицо, физ. лицо и т. п.). На каждом портале свой набор типов. Узнать ID можно по существующим заказам: `GET /v1/orders` или `POST /v1/orders/aggregate` с `groupBy: "personTypeId"` |
| `currency` | string | Валюта заказа. Список: [`GET /v1/currencies`](/docs/entities/currencies) |
| `price` | number | Общая сумма заказа |
| `statusId` | string | Текущий статус заказа. Источник: [`GET /v1/order-statuses?filter[type]=O`](./order-statuses/list.md) |
| `userId` | number | Идентификатор пользователя Битрикс24 — покупателя в интернет-магазине. Источник: [`GET /v1/users`](/docs/entities/users) |
| `payed` | boolean | Оплачен ли заказ полностью |
| `canceled` | boolean | Отменён ли заказ |
| `responsibleId` | number | Ответственный сотрудник. Источник: [`GET /v1/users`](/docs/entities/users) |
| `dateInsert` | datetime | Дата создания (только чтение) |
| `dateUpdate` | datetime | Дата последнего изменения (только чтение) |

Полный список полей — [`GET /v1/orders/fields`](./orders/fields.md).

## Что нужно знать перед работой

1. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"lid": "s1", "personTypeId": 5, ...}`. Обёртка `fields` не нужна.
2. **Для создания обязательны три поля:** `lid` (всегда `"s1"` для облачных порталов), `personTypeId` (тип плательщика — на каждом портале свой набор), `currency`. Без них `POST /v1/orders` вернёт `BITRIX_ERROR` с перечислением отсутствующих полей.
3. **Заказ возвращает связанные сущности вложенно.** `GET /v1/orders/:id` отдаёт массивы `basketItems[]` (позиции корзины), `payments[]` (оплаты), `propertyValues[]` (свойства заказа), `clients[]` (CRM-привязки) внутри одного объекта. Отдельные эндпоинты [`/v1/basket-items`](./basket-items.md) и [`/v1/payments`](./payments.md) используются для создания и обновления — но для чтения содержимого одного заказа отдельные вызовы не нужны.
4. **Автоматическая пагинация** включается при `limit > 50`. Общее количество приходит в `meta.total`.

## Связанные сущности

Полноценный жизненный цикл заказа использует семейство сущностей `sale.*`:

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Позиции корзины | [`GET /v1/basket-items?filter[orderId]=:id`](./basket-items.md) | Товарные позиции заказа — что купил покупатель, по какой цене, с какой скидкой. |
| Оплаты | [`GET /v1/payments?filter[orderId]=:id`](./payments.md) | Оплаты заказа — сумма, платёжная система, статус «оплачено / возврат». |
| Статусы заказов | [`GET /v1/order-statuses?filter[type]=O`](./order-statuses.md) | Каталог статусов для заполнения `statusId`. Тип `O` — статусы заказа, `D` — статусы доставки. |

## Типичный сценарий

Обработка нового заказа из внешней системы (CMS, маркетплейс):

1. Получить список статусов заказов: [`GET /v1/order-statuses?filter[type]=O`](./order-statuses/list.md) — найти ID нужного статуса (например, `N` — «Принят»).
2. Создать заказ: [`POST /v1/orders`](./orders/create.md) с минимумом полей (`lid`, `personTypeId`, `currency`, `price`, `statusId`, `userId`).
3. Добавить позиции корзины: [`POST /v1/basket-items`](./basket-items/create.md) — по одной позиции на товар (`orderId`, `productId`, `quantity`, `price`).
4. Зарегистрировать оплату: [`POST /v1/payments`](./payments/create.md) — указав `orderId`, `paySystemId`, `sum`.
5. По мере выполнения — обновить статус: [`PATCH /v1/orders/:id`](./orders/update.md) с новым `statusId`.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Автоматическая пагинация | включается при `limit > 50` |
| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Позиции корзины](./basket-items.md)
- [Оплаты](./payments.md)
- [Статусы заказов](./order-statuses.md)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)