Оптовые заказы — руководство по интеграции
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с часовым поясом.
Testing пока нет
Создание и изменение заказов и отгрузок может затронуть реальные данные. Проверку таких запросов согласуйте с поддержкой. Суффикс -sandbox для b2b-orders не поддерживается.
Авторизация — TODO
TODO: получение, передача, обновление и отзыв токена, сроки действия и права доступа. Пока согласуйте доступ с поддержкой. X-Client-ID выбирает клиента и не заменяет авторизацию.
Быстрый сценарий
- Подготовьте клиента, склад, артикулы, количество и цены.
- Создайте заказ и сохраните его
id. - Получайте заказ по ID, пока не появится результат обработки. Начальный статус
under_reviewне означает подтверждение наличия товара или готовность к отгрузке. - При необходимости измените заказ, передав полный актуальный состав товаров.
- Создайте отгрузку с выбранным способом доставки.
- Следите за состоянием отгрузки и заказа: у них разные статусы.
Создание заказа
Метод: POST /orders.
Обязательны storage_id и непустой products. Каждая позиция по текущему контракту содержит id, code, quantity и price; quantity — целое число не меньше 1. comment необязателен.
Пример тела запроса:
Code
Идентификатор позиции
Схема требует 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} доступен, когда текущий статус заказа — confirmed или part_confirmed. В другом статусе обработчик возвращает 409.
Полная замена товаров
Непустой products заменяет весь состав заказа. Передавайте все позиции, которые должны остаться; количество и сумма пересчитываются. Пустой или отсутствующий products оставляет состав прежним.
comment и status изменяются, если переданы.
DELETE /orders/{order_id} означает отмену, а не физическое удаление записи. Ответ содержит id и статус cancelled. Если отгрузка уже началась, согласуйте её остановку отдельно.
Резервы
GET /reserves возвращает позиции заказов клиента в статусах confirmed и part_confirmed.
Это не общий складской остаток и не отдельный метод резервирования. В ответе находятся reserves и pagination; у позиции есть order_number, storage_id, code, quantity и price.
Отгрузки
POST /orders/{order_id}/shipments создаёт отгрузку для заказа. Новая отгрузка допускается при статусе заказа under_review, confirmed или part_confirmed, если действующей отгрузки ещё нет; иначе возвращается 409.
Если действующая отгрузка уже есть, метод возвращает её. Повторный POST не обновляет её адрес, получателя или тип доставки. Для проверки используйте GET /orders/{order_id}/shipments: несмотря на множественное число в пути, ответ описывает одну отгрузку.
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.
Пример тела запроса для ТК:
Code
Замените дату, адрес и реквизиты своими данными.
Начальный статус отгрузки — 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.
Списки, фильтры и пагинация
- Заказы: ответ
orders+pagination. - Резервы: ответ
reserves+pagination. - Отгрузки: ответ
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. Например:
Code
400— проверьте JSON, обязательные поля, типы и сочетания параметров.401/403— проблема авторизации или доступа; порядок действий будет описан в разделе TODO.404— ресурс не найден в контексте указанного клиента; проверьте ID иX-Client-ID.409— операция недоступна в текущем состоянии; перечитайте заказ или отгрузку.429— снизьте частоту запросов; точный лимит и политика повторов требуют согласования.5xxили сетевой тайм-аут — результат операции может быть неопределённым. Сначала проверьте состояние через GET.
Не закладывайте автоматическое повторение создания заказа: отдельный ключ идемпотентности в публичном контракте не описан, повторный POST может создать новый заказ. Для GET используйте ограниченные повторы с увеличивающейся задержкой.