# Статусы заказов

Управление статусами заказов и доставки интернет-магазина: создание, получение, обновление, удаление, поиск, агрегация. Статусы — это справочник, на который ссылается поле [`orders.statusId`](./orders/fields.md). У каждого статуса есть тип: `O` — статус заказа, `D` — статус доставки.

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

## Операции

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | string | Символьный код статуса (1-2 символа: `N`, `IP`, `DT`). **Задаётся пользователем при создании**, не генерируется автоматически |
| `type` | string | Тип статуса: `O` — статус заказа, `D` — статус доставки |
| `sort` | number \| null | Порядок сортировки в списках. При создании без `sort` поле остаётся `null` — значение по умолчанию не подставляется |
| `notify` | boolean | Отправлять ли уведомление клиенту при переходе заказа в этот статус. При создании без `notify` поле остаётся `false` — значение по умолчанию не подставляется |
| `color` | string \| null | HEX-код цвета для отображения, например `#FFA500`, либо `null`. При создании без `color` поле остаётся `null` — значение по умолчанию не подставляется |
| `xmlId` | string \| null | Внешний идентификатор. При создании без явного значения генерируется автоматически вида `bx_<hash>`. У части системных статусов — `null` |

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

Отдельного поля с локализованным названием статуса через этот API нет — для идентификации служат символьный код `id` и тип `type`.

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

1. **`id` задаётся пользователем.** При создании передавайте короткий символьный код (1-2 символа): например, `N` («новый»), `IP` («в работе»), `DT` («доставлен»). Идентификатор должен быть уникальным независимо от типа — нельзя создать два статуса с одинаковым `id`, даже если один из них для заказа, а второй для доставки.
2. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"id": "DT", "type": "O", ...}`. Обёртка `fields` не нужна.
3. **Набор статусов по умолчанию.** На новом портале есть стандартные статусы: `N` («Принят, ожидается оплата»), `P` («Оплачен»), `F` («Выполнен»), `D` («Отказ»), `DN` («Доставляется») и другие. Их можно изменять и удалять тем же API, но заказы со ссылками на старый `id` после удаления статуса не находятся в выборках по `statusId`.

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

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Заказы | [`GET /v1/orders?filter[statusId]=:id`](./orders/list.md) | Заказы, находящиеся в этом статусе — поле `orders.statusId` ссылается сюда. |

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

Создание нового статуса заказа и его использование:

1. Получить существующие статусы: [`GET /v1/order-statuses?filter[type]=O`](./order-statuses/list.md) — убедиться, что новый код `id` не занят.
2. Создать статус: [`POST /v1/order-statuses`](./order-statuses/create.md) с `id`, `type: "O"`, `sort`, `notify`, `color`.
3. Использовать в заказах: [`PATCH /v1/orders/:id`](./orders/update.md) с `statusId: "новый_id"`.

## Лимиты

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

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

- [Заказы](./orders.md)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)