# Оптовые заказы — руководство по интеграции

`b2b-orders` управляет оптовыми заказами, резервами и отгрузками. Заказ содержит склад и товары, отгрузка — способ передачи заказа получателю. Для выкупа с ответственного хранения используется другой сервис — `responsible-storage`.

## Адрес API и формат запросов

Префикс — `/orders/v1` на сервере из API Reference. Далее пути указаны относительно него: например, `GET /orders` означает `GET /orders/v1/orders`.

- Тела запросов и обычные ответы передаются в JSON. Для запросов с телом указывайте `Content-Type: application/json`.
- Во всех перечисленных публичных методах обязателен заголовок `X-Client-ID` — строковый идентификатор клиента, например `00-00002323`.
- `client_id`, `storage_id`, код товара и номера документов храните как строки: ведущие нули значимы.
- `order_id` — числовой `id` заказа из ответа API, а не его строковый `number`. Номер может появиться после обработки заказа.
- Даты фильтров и `delivery_date` имеют формат `YYYY-MM-DD`; поля времени создания и изменения — `date-time` с часовым поясом.

:::warning{title="Testing пока нет"}

Создание и изменение заказов и отгрузок может затронуть реальные данные. Проверку таких запросов согласуйте с поддержкой. Суффикс `-sandbox` для b2b-orders не поддерживается.

:::

## Авторизация — TODO

**TODO:** получение, передача, обновление и отзыв токена, сроки действия и права доступа. Пока согласуйте доступ с поддержкой. `X-Client-ID` выбирает клиента и не заменяет авторизацию.

## Быстрый сценарий

<div class="stepper">

1. Подготовьте клиента, склад, артикулы, количество и цены.
2. [Создайте заказ](/api/заказы#создать-заказ) и сохраните его `id`.
3. [Получайте заказ по ID](/api/заказы#получить-заказ-по-идентификатору), пока не появится результат обработки. Начальный статус `under_review` не означает подтверждение наличия товара или готовность к отгрузке.
4. При необходимости [измените заказ](/api/заказы#обновить-заказ), передав полный актуальный состав товаров.
5. [Создайте отгрузку](/api/заказы#создать-отгрузку) с выбранным способом доставки.
6. Следите за состоянием [отгрузки](/api/заказы#получить-отгрузку-по-идентификатору-заказа) и заказа: у них разные статусы.

</div>

## Создание заказа

Метод: [POST /orders](/api/заказы#создать-заказ).

Обязательны `storage_id` и непустой `products`. Каждая позиция по текущему контракту содержит `id`, `code`, `quantity` и `price`; `quantity` — целое число не меньше 1. `comment` необязателен.

Пример тела запроса:

```json
{
  "storage_id": "100001",
  "products": [
    { "id": 0, "code": "41137268", "quantity": 4, "price": 4470 }
  ],
  "comment": "Тест интеграции — согласовать обработку"
}
```

:::note{title="Идентификатор позиции"}

Схема требует `products[].id`, но при создании сервис назначает его сам. В примере `0` заполняет обязательное поле; товар определяется артикулом `code`.

:::

Начальный статус — `under_review`. `total_products` — сумма количеств, `total_price` — сумма `quantity × price` из запроса. Подтверждение заказа происходит отдельно.

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

| Статус | Значение для интеграции |
| --- | --- |
| `under_review` | Заказ на рассмотрении; дождитесь результата. |
| `confirmed` | Заказ подтверждён. |
| `in_delivery` | Заказ на поставку. |
| `shipment_creation` | Создаётся отгрузка. |
| `shipment_under_review` | Отгрузка находится в обработке. |
| `collecting` | Идёт сборка. |
| `shipped` | Заказ отгружен. |
| `cancelled` | Заказ отменён. |
| `rejected` | Заказ отклонён. |
| `fix_required` | Требуется исправление; проверьте детали заказа. |
| `processing_error` | Ошибка обработки, в частности по остаткам или ценам. |

Это перечень состояний, а не обязательная линейная последовательность. Проверяйте также `error`, если это поле есть в заказе: оно содержит `error` и `details_message` и отличается от формата HTTP-ошибки.

## Изменение и отмена

[PUT /orders/{order_id}](/api/заказы#обновить-заказ) доступен, когда текущий статус заказа — `confirmed` или `part_confirmed`. В другом статусе обработчик возвращает `409`.

:::warning{title="Полная замена товаров"}

Непустой `products` заменяет весь состав заказа. Передавайте все позиции, которые должны остаться; количество и сумма пересчитываются. Пустой или отсутствующий `products` оставляет состав прежним.

:::

`comment` и `status` изменяются, если переданы.

[DELETE /orders/{order_id}](/api/заказы#отменить-заказ) означает отмену, а не физическое удаление записи. Ответ содержит `id` и статус `cancelled`. Если отгрузка уже началась, согласуйте её остановку отдельно.

## Резервы

[GET /reserves](/api/заказы#получить-список-резервов) возвращает позиции заказов клиента в статусах `confirmed` и `part_confirmed`.

Это не общий складской остаток и не отдельный метод резервирования. В ответе находятся `reserves` и `pagination`; у позиции есть `order_number`, `storage_id`, `code`, `quantity` и `price`.

## Отгрузки

[POST /orders/{order_id}/shipments](/api/заказы#создать-отгрузку) создаёт отгрузку для заказа. Новая отгрузка допускается при статусе заказа `under_review`, `confirmed` или `part_confirmed`, если действующей отгрузки ещё нет; иначе возвращается `409`.

Если действующая отгрузка уже есть, метод возвращает её. **Повторный POST не обновляет её адрес, получателя или тип доставки.** Для проверки используйте [GET /orders/{order_id}/shipments](/api/заказы#получить-отгрузку-по-идентификатору-заказа): несмотря на множественное число в пути, ответ описывает одну отгрузку.

| `type` | Способ получения |
| --- | --- |
| `delivery` | Доставка. |
| `pickup` | Самовывоз. |
| `delivery_tk` | Доставка транспортной компанией. |

Для всех типов, включая самовывоз, обязательны `type`, `address`, `recipient`, `recipient_phone`, `delivery_date` и `payer`.

Для `delivery_tk` дополнительно обязательны:

- `transport_company` — непустое название или код ТК.
- `tk_delivery_cost` — неотрицательное целое число **в копейках**.
- `tk_delivery_to_terminal` — `true` для терминала, `false` для адреса получателя. Не теряйте `false` при сериализации.

Для `delivery` и `pickup` поля `transport_company`, `tk_delivery_cost` и `tk_delivery_to_terminal` нужно опустить или передать как `null`; непустые значения приводят к `400`.

Пример тела запроса для ТК:

```json
{
  "type": "delivery_tk",
  "address": "Адрес согласованного терминала",
  "recipient": "Получатель заказа",
  "recipient_phone": "+79000000000",
  "payer": "Плательщик заказа",
  "delivery_date": "2026-12-01",
  "transport_company": "ПЭК",
  "tk_delivery_cost": 150000,
  "tk_delivery_to_terminal": true
}
```

Замените дату, адрес и реквизиты своими данными.

Начальный статус отгрузки — `shipment_creation`. Далее возможны `under_review`, `assembly_expected`, `collecting`, `collected`, `transfer_order_created`, `sending_marking_codes`, `marking_of_packages`, `ready_mark_before_labeling`, `marking`, `packed_in_pallet`, `ready_for_shipment`, `loading_control`, `shipped`, `cancelled`. Набор не совпадает со статусами заказа; не используйте для обеих сущностей один enum.

## Списки, фильтры и пагинация

- [Заказы](/api/заказы#получить-список-заказов): ответ `orders` + `pagination`.
- [Резервы](/api/заказы#получить-список-резервов): ответ `reserves` + `pagination`.
- [Отгрузки](/api/заказы#получить-список-отгрузок): ответ `shipments` + `pagination`.

Параметры: `page` от 1, `per_page` от 1 до 100; по умолчанию `page=1`, `per_page=20`. Метаданные `pagination` содержат `total`, `page`, `per_page`, `total_pages`.

Заказы и резервы можно фильтровать по складу, датам создания, номеру заказа и артикулу (`article`). Несколько складов передаются повторением параметра: `storage=100001&storage=100016`. У заказов есть фильтр `status`; резервы уже ограничены подтверждёнными заказами.

У отгрузок свои фильтры: `status`, `date_from`, `date_to`, `number` отгрузки и `order_number` заказа. `date_from` и `date_to` передавайте в формате `YYYY-MM-DD`.

Сортировка задаётся двумя параметрами: `order_by` и `sort=asc|desc`. По умолчанию — `date_insert` и `asc`. Допустимые поля зависят от метода; у отгрузок это `number`, `date_insert`, `type`, `status`.

## Ошибки и повторные запросы

Обычная JSON-ошибка сервиса содержит `error` и `message`, опционально `details`. Например:

```json
{ "error": "404", "message": "Заказ не найден" }
```

- `400` — проверьте JSON, обязательные поля, типы и сочетания параметров.
- `401` / `403` — проблема авторизации или доступа; порядок действий будет описан в разделе TODO.
- `404` — ресурс не найден в контексте указанного клиента; проверьте ID и `X-Client-ID`.
- `409` — операция недоступна в текущем состоянии; перечитайте заказ или отгрузку.
- `429` — снизьте частоту запросов; точный лимит и политика повторов требуют согласования.
- `5xx` или сетевой тайм-аут — результат операции может быть неопределённым. Сначала проверьте состояние через GET.

Не закладывайте автоматическое повторение создания заказа: отдельный ключ идемпотентности в публичном контракте не описан, повторный POST может создать новый заказ. Для GET используйте ограниченные повторы с увеличивающейся задержкой.
