Данный проект представляет собой интерактивный аналитический инструмент на базе Jupyter Lab, предназначенный для интеграции с Ozon Seller API, выгрузки ключевых коммерческих метрик и глубокой постобработки финансовых данных. Инструмент автоматизирует сбор информации о товарах, остатках, оборачиваемости и продажах, а также детализацию и пропорциональное распределение сборных финансовых транзакций по конкретным SKU.
Язык программирования: Python
Библиотеки для работы с данными: Pandas, NumPy
Интеграция с API: Requests, Python-dotenv (безопасное хранение ключей в .env)
Среда разработки: Jupyter Notebook / Jupyter Lab
Проект ориентирован на работу с конкретными аккаунтами (в коде используется профиль "Michael"). При запуске скрипт автоматически создает изолированную структуру папок и имена файлов для экспорта.
Модуль последовательно тестирует и использует следующие методы Ozon API: Реализованные эндпоинты Ozon API
Функция в коде: get_products_list Назначение: Получение базового списка товаров (связка offer_id → product_id).
Функция в коде: get_stocks_by_product_id Назначение: Выгрузка остатков товаров на складах FBO с получением SKU.
Функция в коде: get_analytics_stocks Назначение: Детальная аналитика по остаткам в разрезе складов и кластеров.
Функция в коде: get_analytics_turnover Назнажение: Получение метрик оборачиваемости и дефицита товаров.
Функция в коде: get_product_info Назначение: Извлечение расширенной информации о ценах, старых ценах и квантах.
Функция в коде: download_products_report_to_df Назначение: Асинхронное создание, проверка готовности и скачивание CSV-отчета по товарам.
Функция в коде: get_analytics / _today Назначение: Сбор комплексной аналитики (просмотры, переходы в корзину, конверсии).
Функция в коде: get_transactions Назначение: Получение полной финансовой ленты (начисления, комиссии, эквайринг).
Инструмент предназначен для интеграции с рекламным API Ozon (https://api-performance.ozon.ru). Он автоматизирует аутентификацию, сбор данных обо всех типах рекламных кампаний селлера, загрузку детальной ежедневной статистики и синхронный/асинхронный экспорт отчетов по расходам. Модуль позволяет осуществлять сквозной контроль эффективности маркетинга в разрезе конкретных SKU, кампаний и дат.
В модуле настроен базовый клиент для выполнения запросов с автоматическим менеджментом сессии и авторизации. Ниже представлены используемые методы API Ozon Performance:
Функция в коде: get_token
Назначение: Реализация протокола OAuth2 (grant_type: "client_credentials").
Функция автоматически запрашивает новый токен доступа или обновляет текущий, если до истечения его срока действия осталось менее 60 секунд.
Функция в коде: fetch_campaigns
Назначение: Постраничный (пагинация по 100 позиций) сбор данных обо всех рекламных кампаниях.
Позволяет фильтровать кампании по их статусу (например, только активные — CAMPAIGN_STATE_RUNNING).
Функция в коде: get_campaign_objects
Назначение: Получение списка уникальных идентификаторов (SKU/ID товаров), привязанных к конкретной рекламной кампании.
Функция в коде: get_report_resilient / get_report_resilient_new
Назначение: Асинхронный заказ и скачивание глубоких аналитических отчетов по рекламе в формате JSON.
Функция в коде: get_expense_report
Назначение: Синхронный сбор данных исключительно о финансовых расходах на рекламу за выбранный период времени.
Поскольку генерация рекламных отчетов на стороне Ozon происходит асинхронно и может занимать длительное время, в функциях get_report_resilient реализован продвинутый механизм контроля сессии: Файл-чекпоинт (ozon_last_uuid.txt): Утилита сохраняет уникальный UUID заказанного отчета на диск. Если скрипт прервется, при перезапуске он сначала проверит файл, найдет незавершенный отчет и продолжит опрашивать Ozon, не создавая дублирующих запросов и экономя лимиты API. Политика ожидания: Скрипт совершает до 30 попыток проверки статуса ответа (state == "OK") с шагом в 15 секунд.
Специфика S3 облака: Реализована корректная обработка прямых S3-ссылок Ozon для скачивания готовых файлов, где принудительно отключаются заголовки авторизации API, которые вызывают ошибку доступа на серверах хранения данных Amazon/S3.
OzonAPI Performance выдает данные в разной структуре в зависимости от параметров группировки и типов кампаний. Код содержит встроенный парсер трех конфигураций ответов: Структура с явным списком рекламных кампаний ({"campaigns": [...]}). Словарь, где ID кампаний выступают в роли корневых ключей. Плоский классический список строк. Скрипт автоматически распаковывает любую из этих вложенностей, обогащает каждую строку метаданными (ID и название кампании) и собирает плоский датафрейм Pandas.
Модуль выполняет автоматическую чистку текстовых данных Ozon, переводя финансовые показатели из строкового представления с запятыми ("1053,06") в классический вещественный тип float (1053.06). Нормализации подвергаются ключевые e-commerce метрики: moneySpent — затраченный бюджет. views и clicks — показы и переходы. orders и ordersMoney — количество заказов с рекламы и оборот. drr (ДРР) — доля рекламных расходов. product_gmv — общий оборот товара.
OZON_CLIENT_ID="ваш_client_id" OZON_API_KEY="ваш_api_key"
Запустите Jupyter Lab и последовательно выполните ячейки ноутбука.