AI Asist
v2
Д
Д

Возвраты Ozon к получению продавцом

← Заметки  ·  Раздел: Ozon  ·  Файл: data/notes/ozon/returns-to-pickup-playbook.md

Возвраты Ozon к получению продавцом

Актуализировано: 18.08.2026.

Цель

Показать по каждому Ozon-магазину:

  • что уже лежит в пункте возврата и можно забирать;
  • что едет к продавцу;
  • что ожидает отправки именно в подтверждённый пункт продавца;
  • где и когда начнётся тарификация хранения и когда Ozon прогнозирует утилизацию;
  • сформировал ли Ozon возвратную отгрузку для получения по штрихкоду.

Рабочая точка входа для ручного отчёта — scripts/ozon_returns_to_pickup.py. Полная история и JSON для автоматизации — scripts/marketplace_returns.py; общие правила хранения описаны в data/notes/marketplace-returns-history-playbook.md. Оба контура read-only относительно Ozon.

Два обязательных источника

Источник Что даёт Почему нужен
POST /v1/returns/list Поштучный возврат: статус, товар, текущая и целевая точка, хранение Главный источник факта «в пункте выдачи» и «едет к вам»
POST /v1/return/giveout/list Активные возвратные отгрузки, склад, подтверждённое/общее число товаров Контроль сформированного пакета для выдачи
POST /v1/return/giveout/is-enabled Доступность получения по штрихкоду Показывать как контроль, не как количество возвратов

giveout/list нельзя использовать в одиночку. Контроль реализации от 17.08.2026: по returns/list у магазинов 2 и 4 было по 3 товара в статусе ArrivedAtReturnPlace, а giveout/list у обоих был пуст. Нулевой список отгрузок в такой ситуации не означает, что на ПВЗ нечего забирать.

Статусы /v1/returns/list

visual.status.sys_name В отчёте Действие
ArrivedAtReturnPlace Готово Товар находится в пункте возврата; вывести поштучно
MovingToSeller Едет Товар направлен в точку продавца
WaitingShipment Ожидает Включать только при подтверждённой целевой точке продавца
ReceivedBySeller Закрыто Использовать для распознавания точек продавца, но не считать активным
MovingToOzon, ReturnedToOzon Возврат в Ozon Не включать в маршрут продавцу
PotentiallyLost, WriteOff, Utilizing, Utilized Исключение Показывать в диагностике потерь, но не как товар к получению

WaitingShipment нельзя включать целиком: часть таких товаров направлена на склады возвратов Ozon, а часть — в точку продавца. Подтверждённые точки продавца строятся по target_place.id из ArrivedAtReturnPlace, MovingToSeller, истории ReceivedBySeller и активных giveout/list. Совпавшие ожидания считаются маршрутом продавцу; остальные выводятся отдельным контрольным количеством без смешения с возвратами на ПВЗ.

Алгоритм

  1. Выбрать все магазины shops.marketplace='ozon', если пользователь не указал один.
  2. Запросить отдельно ArrivedAtReturnPlace, MovingToSeller, WaitingShipment и ReceivedBySeller. Ozon разрешает только один фильтр в одном запросе.
  3. Для каждого статуса пройти пагинацию до has_next=false: limit=500, следующий last_id — id последней строки предыдущей страницы.
  4. Запросить все giveout/list: limit<=500, следующий last_id — последний giveout_id.
  5. Группировать точки по place.id / target_place.id, а не по строке адреса: Ozon может вернуть один адрес в нескольких вариантах написания.
  6. Считать единицы по product.quantity; одна строка обычно равна одной единице, но это не должно быть предположением в коде.
  7. Отдельно показать по каждому магазину Готово, Едет, Ожидает, пакет выдачи и точный адрес. Для готовых единиц вывести offer_id, название, причину и ID возврата.
  8. Зафиксировать абсолютные дату и время среза в MSK.

Для полной истории в БД /v1/returns/list запрашивается с пустым filter и пагинацией до has_next=false: так сохраняются все статусы, а не только текущий маршрут продавцу. В сводку на ПВЗ после записи всё равно проходит только точный ArrivedAtReturnPlace.

Хранение и дедлайн

Не переносить правила WB на Ozon и не рассчитывать дедлайн вручную. Для каждой готовой единицы использовать поля самого Ozon:

  • storage.arrived_moment — когда возврат прибыл;
  • storage.tariffication_start_date — начало тарификации;
  • storage.tariffication_first_date — первое начисление;
  • storage.sum.price — уже начисленное хранение;
  • storage.utilization_forecast_date — прогноз утилизации.

Все UTC-метки переводить в Europe/Moscow и показывать с датой и временем.

Запрет двойного счёта

  • Строки returns/list и пакет giveout/list описывают один возвратный поток. Их количества показываются рядом для сверки, но не складываются.
  • Детализацию returns/list не прибавлять к return_from_customer_stock_count в оценке остатков Ozon: это агрегат и его расшифровка, а не два разных запаса.
  • ReceivedBySeller уже закрыт; ReturnedToOzon уже вернулся в контур Ozon.

Безопасность

  • Отчёт только читает API и БД.
  • Не выводить logistic.barcode по умолчанию.
  • Методы получения PDF/PNG или значения штрихкода вызывать только по явному запросу.
  • /v1/return/giveout/barcode-reset меняет внешний объект: без отдельного прямого разрешения не вызывать.

Запуск

.venv\Scripts\python.exe scripts\ozon_returns_to_pickup.py
.venv\Scripts\python.exe scripts\ozon_returns_to_pickup.py --shop-id 4
.venv\Scripts\python.exe scripts\marketplace_returns.py collect --attempts 3
.venv\Scripts\python.exe scripts\marketplace_returns.py report --json

Чек-лист

  1. ☐ Проверены оба Ozon-магазина или явно назван выбранный магазин?
  2. ☐ returns/list полностью пропагинирован по каждому статусу?
  3. ☐ Готовые, едущие и ожидающие разделены?
  4. ☐ WaitingShipment на склады Ozon не попал в маршрут продавцу?
  5. ☐ Нулевой giveout/list не затёр готовые возвраты?
  6. ☐ Для готовых товаров показаны точка, состав, тарификация и прогноз утилизации?
  7. ☐ Штрихкод не раскрыт и никакое внешнее действие не выполнено?
Фильтры