Ozon Seller API — Полная документация

Версия документа: 1.0 Дата обновления: 10 февраля 2026 Базовый URL: https://api-seller.ozon.ru

Содержание

Аутентификация
Базовый URL
Ограничения на запросы (Rate Limits)
Обзор категорий API
Детальное описание эндпоинтов
Коды ошибок
Webhooks (Push-уведомления)
Скачать файлы спецификаций

Аутентификация

Ozon Seller API использует два HTTP-заголовка для аутентификации:

Требуемые заголовки

Имя заголовка	Тип	Описание	Пример
Client-Id	String	Идентификатор клиента продавца	`123456789`
Api-Key	String	API-ключ для аутентификации	`your-api-key-here`

Формат заголовков

Все запросы к API должны включать эти заголовки:

POST /v1/product/list HTTP/1.1
Host: api-seller.ozon.ru
Client-Id: 123456789
Api-Key: your-api-key-here
Content-Type: application/json

Как получить учетные данные

Пошаговая инструкция

1. Войдите в кабинет продавца

Перейдите на seller.ozon.ru
Войдите в аккаунт с правами администратора
Убедитесь, что ваш аккаунт имеет право управлять API-ключами

2. Перейдите в настройки API

Нажмите на аватар/иконку в правом верхнем углу интерфейса
Выберите "Настройки" из выпадающего меню
Перейдите в раздел "API ключи" или "Seller API"

3. Получите Client-Id

Client-Id генерируется автоматически и уже отображается в интерфейсе API-ключей
Просто скопируйте значение Client-Id
Ручная генерация не требуется

4. Сгенерируйте Api-Key

Нажмите кнопку "Сгенерировать ключ"
Введите описательное имя для ключа (например, "Production System", "Integration App")
Выберите роль/уровень доступа для ключа:
- Администратор — полный доступ ко всем методам API
- Другие уровни прав с ограниченным доступом
Нажмите "Подтвердить" для генерации
⚠️ ВАЖНО: Api-Key отображается только один раз после генерации
Сразу скопируйте и сохраните его в безопасном месте

Визуальный путь навигации

seller.ozon.ru
    ↓
[Иконка аватара справа вверху]
    ↓
Настройки (Settings)
    ↓
API ключи (API Keys)
    ↓
┌─────────────────────────────────┐
│ Client-Id: [Автоматически создан]│ ← Скопируйте это
└─────────────────────────────────┘
    ↓
[Сгенерировать ключ] (Generate Key)
    ↓
┌─────────────────────────────────┐
│ 1. Введите имя ключа             │
│ 2. Выберите роль (Administrator) │
│ 3. Подтвердите                   │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ Api-Key: [Показан только один раз]│ ← Скопируйте СЕЙЧАС!
└─────────────────────────────────┘

Управление API-ключами

Несколько ключей

Вы можете создать несколько API-ключей для разных систем интеграции
Рекомендуемая практика: используйте отдельные ключи для:
- Продуктивной среды
- Среды разработки/тестирования
- Различных сторонних интеграций

Безопасность ключей

⚠️ Api-Key отображается только один раз после генерации
Храните ключи безопасно (используйте переменные окружения, системы управления секретами)
Никогда не коммитьте ключи в системы контроля версий (Git и т.д.)
Периодически ротируйте ключи для безопасности
Сразу удаляйте неиспользуемые ключи

Ролевой доступ (RBAC)

При создании API-ключа вы можете указать уровень доступа:

Administrator: Полный доступ ко всем методам Seller API
Ограниченные роли: Ограниченный доступ к конкретным категориям API

Справка: Документация по отображению ролей

Примеры использования

Python (Async)

from ozon_api import OzonAPI
import asyncio

async def main():
    # Рекомендуется: использовать context manager
    async with OzonAPI(
        client_id="your_client_id",
        api_key="your_api_key"
    ) as api:
        # Получить список товаров
        products = await api.product_list(...)
        print(products)

if __name__ == "__main__":
    asyncio.run(main())

Python (HTTP-клиент)

import requests

headers = {
    "Client-Id": "your_client_id",
    "Api-Key": "your_api_key",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api-seller.ozon.ru/v1/product/list",
    headers=headers,
    json={"page": 1, "page_size": 100}
)

TypeScript/JavaScript

import { OzonSellerAPI } from 'daytona-ozon-seller-api';

const api = new OzonSellerAPI({
  clientId: 'your-client-id',
  apiKey: 'your-api-key'
});

// Получить товары
const products = await api.product.getList({ limit: 10 });

// Получить FBS-заказы
const orders = await api.fbs.getOrdersList({
  filter: { status: 'awaiting_packaging' }
});

cURL

curl -X POST "https://api-seller.ozon.ru/v1/product/list" \
  -H "Client-Id: your_client_id" \
  -H "Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 100
  }'

PHP

use Gam6itko\OzonSeller\Service\V1\ProductService;

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api-seller.ozon.ru',
    'headers' => [
        'Client-Id' => 'your_client_id',
        'Api-Key' => 'your_api_key',
        'Content-Type' => 'application/json'
    ]
]);

$productService = new ProductService($client);
$products = $productService->list(['page' => 1, 'page_size' => 100]);

Go

package main

import (
    "context"
    "github.com/diphantxm/ozon-api-client"
)

func main() {
    client := ozon_api.NewClient(
        "your_client_id",
        "your_api_key",
    )

    products, err := client.Product().List(context.Background(), ...)
    if err != nil {
        panic(err)
    }
}

Обработка ошибок аутентификации

HTTP Код	Тип ошибки	Описание
400	`OzonAPIClientError`	Неверный формат запроса
403	`OzonAPIForbiddenError`	Неверные учетные данные или недостаточно прав
404	`OzonAPINotFoundError`	Эндпоинт не найден
409	`OzonAPIConflictError`	Конфликт запроса
500	`OzonAPIServerError`	Ошибка сервера

Пример ошибки:

{
  "code": 403,
  "message": "Invalid Client-Id or Api-Key",
  "details": "Authentication failed"
}

Конфигурация

Переменные окружения (.env):

OZON_CLIENT_ID=your_client_id
OZON_API_KEY=your_api_key
OZON_API_URL=https://api-seller.ozon.ru

Python с python-dotenv:

from dotenv import load_dotenv
import os

load_dotenv()

client_id = os.getenv("OZON_CLIENT_ID")
api_key = os.getenv("OZON_API_KEY")

Поддержка языков

API поддерживает несколько языков через заголовок Accept-Language или конфигурацию клиента:

Поддерживаемые языки:

DEFAULT — язык по умолчанию
RU — Русский
EN — Английский
TR — Турецкий
ZH_HANS — Китайский (упрощенный)

Пример на Python:

api = OzonAPI(client_id="...", api_key="...")
api.language = "RU"  # Установить язык

Базовый URL

https://api-seller.ozon.ru

Все эндпоинты API доступны через этот базовый URL.

Пример полного URL:

https://api-seller.ozon.ru/v1/product/list

Ограничения на запросы (Rate Limits)

Глобальные ограничения

Тип ограничения	Значение	Область действия	Дата вступления в силу
Запросов в секунду	50 RPS	Все методы на один Client ID	19 мая 2025

Важные детали:

Ограничение 50 запросов в секунду применяется ко всем методам API с одного Client ID
Это ограничение на уровень аккаунта, а не на эндпоинт
Все запросы учитываются в этом едином лимите, независимо от эндпоинта
Ограничение было внедрено/увеличено 19 мая 2025

Ответы при превышении лимитов

HTTP-код состояния

HTTP Код	Код ошибки	Сообщение	Описание
429	8	"You have reached request rate limit per second"	Превышен лимит запросов

Формат ответа с ошибкой

{
  "code": 8,
  "message": "You have reached request rate limit per second",
  "details": "Too many requests"
}

Специфические ограничения эндпоинтов

Управление товарами

Операция	Ограничение	Примечания
POST /v2/product/import	До 100 товаров за запрос	Лимит импорта пакетами
POST /v1/product/import/stocks	До 100 товаров за запрос	Размер пакета обновления остатков
POST /v1/product/import/prices	До 100 товаров за запрос	Размер пакета обновления цен
Создание товаров в день	60 PDP в день	Product Detail Pages
Редактирование товаров в день	300 PDP в день	Product Detail Pages
Общий лимит PDP	120 PDP	Максимальное количество товаров

Обновление складских остатков

Операция	Ограничение	Примечания
Обновление остатков (один товар/склад)	Раз в 2 минуты	На один SKU на склад
Обновление доступности товаров	До 80 запросов/минуту	Общая рекомендация
POST /v2/products/stocks	До 100 товаров за запрос	Обновление остатков на нескольких складах

Операции с штрихкодами

Операция	Ограничение	Примечания
POST /v1/barcode/add	Максимум 100 товаров за запрос	Пакетная привязка штрихкодов
Штрихкодов на товар	Максимум 100 штрихкодов	Лимит на товар
Использование метода	Максимум 20 раз	За период времени

Аналитика и отчеты

Категория	Ограничение	Примечания
Performance API	100,000 запросов в день	Для аккаунтов Ozon Performance
Генерация отчетов	По типу отчета	Асинхронная генерация с проверкой статуса

Заголовки ограничения частоты

Текущий статус: ❌ Нет стандартных заголовков

Важно: В отличие от многих других API (Amazon, GitHub и т.д.), Ozon Seller API не предоставляет стандартные заголовки ограничения частоты в ответах API.

Отсутствующие заголовки:

Нет заголовка X-RateLimit-Limit
Нет заголовка X-RateLimit-Remaining
Нет заголовка X-RateLimit-Reset
Нет заголовка retry-after в ответах 429

Следствия:

Нельзя проактивно мониторить оставшуюся квоту
Необходимо реализовать ограничение частоты на стороне клиента
Необходимо реактивно обрабатывать ошибки 429

Лучшие практики обработки ограничений

1. Ограничение частоты на стороне клиента

Рекомендуемый подход:

import time
from collections import deque
from threading import Lock

class RateLimiter:
    def __init__(self, max_requests=50, time_window=1.0):
        self.max_requests = max_requests
        self.time_window = time_window  # секунды
        self.requests = deque()
        self.lock = Lock()

    def wait_if_needed(self):
        with self.lock:
            now = time.time()
            # Удалить старые запросы за пределами временного окна
            while self.requests and self.requests[0] <= now - self.time_window:
                self.requests.popleft()

            # Если достигнут лимит, подождать
            if len(self.requests) >= self.max_requests:
                sleep_time = self.time_window - (now - self.requests[0])
                if sleep_time > 0:
                    time.sleep(sleep_time)
                    # Очистить старые запросы после ожидания
                    now = time.time()
                    while self.requests and self.requests[0] <= now - self.time_window:
                        self.requests.popleft()

            # Добавить текущий запрос
            self.requests.append(now)

# Использование
rate_limiter = RateLimiter(max_requests=50, time_window=1.0)

def make_api_request(url, headers, data):
    rate_limiter.wait_if_needed()
    response = requests.post(url, headers=headers, json=data)
    # Обработать ответ...

2. Логика повторных попыток с экспоненциальной задержкой

import time
import random

def make_request_with_retry(url, headers, data, max_retries=5):
    for attempt in range(max_retries):
        rate_limiter.wait_if_needed()
        response = requests.post(url, headers=headers, json=data)

        if response.status_code == 429:
            # Превышен лимит - экспоненциальная задержка
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"Превышен лимит. Ожидание {wait_time:.2f}с...")
            time.sleep(wait_time)
            continue

        elif response.status_code >= 500:
            # Ошибка сервера - повторная попытка с задержкой
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"Ошибка сервера {response.status_code}. Повтор через {wait_time:.2f}с...")
            time.sleep(wait_time)
            continue

        else:
            # Успех или другая ошибка - вернуть как есть
            return response

    raise Exception(f"Превышено максимальное количество попыток: {max_retries}")

3. Пакетирование запросов

Оптимизируйте запросы с помощью пакетирования:

# Вместо множественных отдельных вызовов:
for product in products:
    update_stock(product['sku'], product['stock'])  # ❌ Неэффективно

# Используйте пакетные операции:
batch_size = 100
for i in range(0, len(products), batch_size):
    batch = products[i:i+batch_size]
    update_stocks_batch(batch)  # ✅ Эффективно

4. Асинхронная обработка запросов

import asyncio
import aiohttp

async def fetch_with_rate_limit(session, url, headers, data, semaphore):
    async with semaphore:  # Ограничить параллельные запросы
        async with session.post(url, headers=headers, json=data) as response:
            return await response.json()

async def bulk_request(items, max_concurrent=10):
    semaphore = asyncio.Semaphore(max_concurrent)
    async with aiohttp.ClientSession() as session:
        tasks = [
            fetch_with_rate_limit(session, url, headers, item, semaphore)
            for item in items
        ]
        return await asyncio.gather(*tasks)

Мониторинг ограничений частоты

Ведение журнала

import logging
from datetime import datetime

class APIRequestLogger:
    def __init__(self):
        self.request_count = 0
        self.rate_limit_hits = 0
        self.logger = logging.getLogger('ozon_api')

    def log_request(self, url, status_code, response_time):
        self.request_count += 1

        if status_code == 429:
            self.rate_limit_hits += 1

        self.logger.info(
            f"[{datetime.now().isoformat()}] "
            f"Запрос #{self.request_count} | "
            f"Статус: {status_code} | "
            f"Время: {response_time:.3f}с | "
            f"URL: {url}"
        )

        if status_code == 429:
            self.logger.warning(
                f"Превышен лимит! Всего попаданий: {self.rate_limit_hits}"
            )

Метрики для отслеживания

Всего запросов в секунду — Мониторинг RPS в реальном времени
Процент попаданий в лимит — Процент запросов с кодом 429
Среднее время ответа — Обнаружение ухудшения производительности
Пиковые часы использования — Идентификация периодов высокого трафика
Использование по эндпоинтам — Наиболее часто вызываемые эндпоинты

Распределение ограничений по категориям API

Товары

Общие операции: Подчинены глобальному ограничению 50 RPS
Пакетные операции: Максимум 100 элементов за запрос
Создание товаров: 60 PDP в день
Редактирование товаров: 300 PDP в день

Заказы

Получение списка заказов: Подчинено глобальному ограничению 50 RPS
Обновление статуса заказа: Рекомендуется пакетировать запросы
Операции FBO/FBS: Специфических ограничений нет, кроме глобальных

Финансы

Списки транзакций: Подчинены глобальному ограничению 50 RPS
Финансовые отчеты: Асинхронная генерация, без синхронных ограничений

Аналитика

Получение данных: Подчинено глобальному ограничению 50 RPS
Performance API: 100,000 запросов в день (специальные аккаунты)

Склад и Цены

Обновление остатков: Рекомендуется 80 запросов/минуту
Обновление одного SKU: Раз в 2 минуты на склад
Пакетные обновления: До 100 товаров за запрос

Резюме по ограничениям

Ключевые моменты:

✅ Глобальный лимит: 50 запросов в секунду на Client ID (с 19 мая 2025)
✅ Ошибка: HTTP 429 с кодом ошибки 8
✅ Нет заголовков лимита: Необходимо реализовать ограничение на стороне клиента
✅ Специфические лимиты: Различные ограничения для обновления остатков, создания товаров и т.д.
✅ Пакетные операции: Используйте пакетирование для минимизации количества запросов
✅ Стратегия повтора: Реализуйте экспоненциальную задержку для ошибок 429
✅ Мониторинг: Ведите журналы запросов и отслеживайте попадания в лимит

Обзор категорий API

Ozon Seller API предоставляет 247 эндпоинтов в 22 категориях, охватывающих все аспекты управления продажами на маркетплейсе.

Основные категории

Категория	Эндпоинтов	Описание
Товары (Products)	21	Управление товарами: создание, обновление, архивация, изображения, характеристики, цифровые товары
Заказы (Orders)	68	Управление заказами по всем моделям fulfilment: FBO, FBS, rFBS. Отслеживание статусов, отмена, этикетки
FBO/FBS Исполнение	81	Специализированные операции fulfilment: поставки на склад, интервалы отгрузки, документы, маркировка
Финансы (Finance)	7	Финансовые операции: транзакции, отчеты о реализации, взаиморасчеты, B2B продажи
Аналитика (Analytics)	4	Бизнес-аналитика: отчеты по остаткам, оборачиваемость, управление запасами
Цены и Склад (Prices & Stocks)	20	Управление ценами и остатками: обновление цен, управление скидками, автоматические стратегии ценообразования
Возвраты и Акции (Returns & Promotions)	31	Управление возвратами (18) и промо-акциями (13): заявки на возврат, скидки, Hot Sales

Дополнительные категории

Категория	Эндпоинтов	Описание
Категории (Categories)	4	Дерево категорий товаров, характеристики, справочники значений атрибутов
Штрихкоды (Barcodes)	2	Генерация и привязка штрихкодов к товарам
Бренды (Brands)	1	Сертификация брендов
Сертификация (Certification)	15	Управление сертификацией товаров (самая большая дополнительная категория)
Чаты (Chats)	6	Обмен сообщениями с поддержкой Ozon
Грузы (Cargoes)	10	Управление грузоперевозками и перевозками
Пропуска (Passes)	7	Пропуска для водителей и транспорта на склады
Полигоны (Polygons)	2	Управление зонами доставки
Вопросы и ответы (Q&A)	7	Вопросы покупателей о товарах и ответы на них
Отзывы (Reviews)	7	Управление отзывами на товары
Рейтинг продавца (Seller Rating)	2	Метрики качества продаж и производительности
Поставщики/Счета (Supplier/Invoices)	4	B2B операции, управление счетами
Склады (Warehouses)	2	Информация о складах Ozon
Quants	6	Операции с количеством товаров
Отчеты (Reports)	8	Генерация различных типов отчетов

Статистика по категориям

Показатель	Значение
Всего категорий	22
Всего эндпоинтов	247
Крупнейшая категория	FBO/FBS Исполнение (81)
Основные бизнес-категории	7 (208 эндпоинтов)
Дополнительные категории	15 (39 эндпоинтов)
Самый используемый HTTP метод	POST (97%+)

Модели fulfilment

Ozon использует три модели исполнения заказов, каждая со специализированным набором эндпоинтов:

Модель	Описание	Количество эндпоинтов
FBO	Fulfillment by Ozon — Ozon хранит, упаковывает и отправляет товары	~22 эндпоинта
FBS	Fulfillment by Seller — Продавец хранит и отправляет на склад Ozon	~35 эндпоинтов
rFBS	realized FBS — Продавец хранит и отправляет напрямую покупателям	~12 эндпоинтов

Детальное описание эндпоинтов

Ниже представлены подробные таблицы эндпоинтов для всех категорий Ozon Seller API.

1. Товары (Products) — 21 эндпоинт

Управление товарами: создание, обновление, архивация, изображения, характеристики, цифровые товары.

#	Метод	Путь	Описание
1	POST	`/v2/products/delete`	Удалить товар без SKU из архива
2	POST	`/v1/product/import/info`	Узнать статус добавления товара
3	POST	`/v4/product/info/attributes`	Получить описание характеристик товара
4	POST	`/v1/product/info/description`	Получить описание товара
5	POST	`/v3/product/info/list`	Получить информацию о товарах по идентификаторам
6	POST	`/v1/product/info/subscription`	Количество подписавшихся на товар пользователей
7	POST	`/v2/product/info`	Информация о товарах
8	POST	`/v3/product/list`	Список товаров
9	POST	`/v1/product/rating-by-sku`	Получить контент-рейтинг товаров по SKU
10	POST	`/v4/product/info/limit`	Лимиты на ассортимент, создание и обновление товаров
11	POST	`/v1/product/import-by-sku`	Создать товар по SKU
12	POST	`/v3/product/import`	Создать или обновить товар
13	POST	`/v1/product/archive`	Перенести товар в архив
14	POST	`/v1/product/related-sku/get`	Получить связанные SKU
15	POST	`/v1/product/pictures/import`	Загрузить или обновить изображения товара
16	POST	`/v2/product/pictures/info`	Получить изображения товаров
17	POST	`/v1/product/unarchive`	Вернуть товар из архива
18	POST	`/v1/product/attributes/update`	Обновить характеристики товара
19	POST	`/v1/product/update/offer-id`	Изменить артикулы товаров из системы продавца
20	POST	`/v1/product/upload_digital_codes`	Загрузить коды активации для услуг и цифровых товаров
21	POST	`/v1/product/upload_digital_codes/info`	Статус загрузки кодов активации

Группировка по функциям:

Получение информации (7): list, info, info/list, info/attributes, info/description, rating-by-sku, info/subscription
Создание и обновление (3): import, import-by-sku, attributes/update
Изображения (2): pictures/import, pictures/info
Архив (3): archive, unarchive, delete
Идентификаторы (2): update/offer-id, related-sku/get
Цифровые товары (2): upload_digital_codes, upload_digital_codes/info
Статус и лимиты (2): import/info, info/limit

2. Заказы (Orders) — 68 эндпоинтов

Управление заказами по всем моделям fulfilment: FBO, FBS, rFBS. Отслеживание статусов, отмена, этикетки.

2.1 FBO Заказы (7 эндпоинтов)

#	Метод	Путь	Описание
1	POST	`/v2/posting/fbo/get`	Информация об отправлении FBO
2	POST	`/v2/posting/fbo/list`	Список отправлений FBO
3	POST	`/v1/posting/fbo/cancel-reason/list`	Причины отмены отправлений по схеме FBO
4	GET	`/v1/supplier/available_warehouses`	Загруженность складов Ozon
5	POST	`/v1/supply-order/timeslot/status`	Статус интервала поставки
6	POST	`/v1/supply-order/timeslot/get`	Интервалы поставки
7	POST	`/v2/supply-order/list`	Список заявок на поставку на склад Ozon

2.2 Управление поставками FBO (6 эндпоинтов)

#	Метод	Путь	Описание
8	POST	`/v2/supply-order/get`	Информация о заявке на поставку
9	POST	`/v1/supply-order/pass/create`	Указать данные о водителе и автомобиле
10	POST	`/v1/supply-order/pass/status`	Статус ввода данных о водителе и автомобиле
11	POST	`/v1/supply-order/status/counter`	Количество заявок по статусам
12	POST	`/v1/supply-order/timeslot/update`	Обновить интервал поставки
13	POST	`/v1/supply-order/bundle`	Состав поставки или заявки на поставку

2.3 FBS Заказы — Основные операции (20 эндпоинтов)

#	Метод	Путь	Описание
14	POST	`/v2/posting/fbs/cancel`	Отменить отправление
15	POST	`/v2/posting/fbs/product/cancel`	Отменить отправку некоторых товаров в отправлении
16	POST	`/v2/posting/fbs/product/change`	Добавить вес для весовых товаров в отправлении
17	POST	`/v1/posting/fbs/package-label/create`	Создать задание на выгрузку этикеток
18	POST	`/v2/posting/fbs/package-label/create`	Создать задание на формирование этикеток (v2)
19	POST	`/v1/posting/global/etgb`	Таможенные декларации ETGB
20	POST	`/v2/posting/fbs/get-by-barcode`	Получить информацию об отправлении по штрихкоду
21	POST	`/v3/posting/fbs/list`	Список отправлений (версия 3)
22	POST	`/v3/posting/fbs/unfulfilled/list`	Список необработанных отправлений (версия 3)
23	POST	`/v3/posting/fbs/get`	Получить информацию об отправлении по идентификатору
24	POST	`/v1/posting/fbs/package-label/get`	Получить файл с этикетками
25	POST	`/v2/posting/fbs/cancel-reason/list`	Причины отмены отправлений
26	POST	`/v1/posting/fbs/cancel-reason`	Причины отмены отправления (v1)
27	POST	`/v1/posting/fbs/restrictions`	Получить ограничения пункта приёма
28	POST	`/v2/posting/fbs/product/country/list`	Список доступных стран-изготовителей
29	POST	`/v2/posting/fbs/arbitration`	Открыть спор по отправлению
30	POST	`/v2/posting/fbs/awaiting-delivery`	Передать отправление к отгрузке
31	POST	`/v2/posting/fbs/package-label`	Напечатать этикетку
32	POST	`/v1/posting/fbs/pick-up-code/verify`	Проверить код курьера
33	POST	`/v3/posting/multiboxqty/set`	Указать количество коробок для многокоробочных отправлений
34	POST	`/v2/posting/fbs/product/country/set`	Добавить информацию о стране-изготовителе товара
35	POST	`/v1/posting/unpaid-legal/product/list`	Список неоплаченных товаров, заказанных юридическими лицами

2.4 Управление доставкой FBS (12 эндпоинтов)

#	Метод	Путь	Описание
36	POST	`/v1/carriage/get`	Информация о перевозке
37	POST	`/v1/posting/fbs/split`	Разделить заказ на отправления без сборки
38	POST	`/v2/posting/fbs/act/get-postings`	Список отправлений в акте
39	POST	`/v2/posting/fbs/act/list`	Список актов по отгрузкам
40	POST	`/v1/posting/carriage-available/list`	Список доступных перевозок
41	POST	`/v2/posting/fbs/act/check-status`	Статус отгрузки и документов
42	POST	`/v2/posting/fbs/act/create`	Подтвердить отгрузку и создать документы
43	POST	`/v2/posting/fbs/act/get-container-labels`	Этикетки для грузового места
44	POST	`/v2/posting/fbs/digital/act/check-status`	Статус формирования накладной
45	POST	`/v2/posting/fbs/act/get-pdf`	Получить PDF c документами
46	POST	`/v2/posting/fbs/act/get-barcode`	Штрихкод для отгрузки отправления
47	POST	`/v2/posting/fbs/act/get-barcode/text`	Значение штрихкода для отгрузки отправления

2.5 Статусы доставки rFBS (7 эндпоинтов)

#	Метод	Путь	Описание
48	POST	`/v2/fbs/posting/delivered`	Изменить статус на «Доставлено»
49	POST	`/v2/fbs/posting/delivering`	Изменить статус на «Доставляется»
50	POST	`/v2/fbs/posting/last-mile`	Изменить статус на «Последняя миля»
51	POST	`/v2/fbs/posting/sent-by-seller`	Изменить статус на «Отправлено продавцом»
52	POST	`/v2/fbs/posting/tracking-number/set`	Добавить трек-номера
53	POST	`/v1/posting/fbs/timeslot/change-restrictions`	Доступные даты для переноса доставки
54	POST	`/v1/posting/cutoff/set`	Уточнить дату отгрузки отправления
55	POST	`/v1/posting/fbs/timeslot/set`	Перенести дату доставки

2.6 Отмена rFBS (4 эндпоинта)

#	Метод	Путь	Описание
56	POST	`/v1/conditional-cancellation/approve`	Подтвердить заявку на отмену rFBS
57	POST	`/v1/conditional-cancellation/reject`	Отклонить заявку на отмену rFBS
58	POST	`/v1/conditional-cancellation/get`	Получить информацию о заявке на отмену rFBS
59	POST	`/v1/conditional-cancellation/list`	Получить список заявок на отмену rFBS

2.7 Управление маркировкой товаров (10 эндпоинтов)

#	Метод	Путь	Описание
60	POST	`/v5/fbs/posting/product/exemplar/create-or-get`	Получить данные созданных экземпляров
61	POST	`/v5/fbs/posting/product/exemplar/set`	Проверить и сохранить данные экземпляров (v5)
62	POST	`/v4/fbs/posting/product/exemplar/validate`	Валидация кодов маркировки
63	POST	`/v4/fbs/posting/product/exemplar/status`	Получить статус добавления экземпляров
64	POST	`/v4/fbs/posting/product/exemplar/set`	Проверить и сохранить данные экземпляров
65	POST	`/v4/posting/fbs/ship/package`	Частичная сборка отправления (v4)
66	POST	`/v4/posting/fbs/ship`	Собрать заказ (v4)
67	POST	`/v6/fbs/posting/product/exemplar/create-or-get`	Получить данные созданных экземпляров (v6)
68	POST	`/v6/fbs/posting/product/exemplar/set`	Проверить и сохранить данные экземпляров (v6)
69	POST	`/v5/fbs/posting/product/exemplar/status`	Получить статус добавления экземпляров (v5)
70	POST	`/v5/fbs/posting/product/exemplar/validate`	Валидация кодов маркировки (v5)
71	POST	`/v1/fbs/posting/product/exemplar/update`	Обновить данные экземпляров

Примечание: Маркировка товаров поддерживает несколько версий API (v4, v5, v6) для различных операций.

3. FBO/FBS Исполнение — 81 эндпоинт

Специализированные операции fulfilment: поставки на склад, интервалы отгрузки, документы, маркировка.

Подробные таблицы эндпоинтов FBO/FBS приведены в разделе «Заказы» выше, так как эти категории тесно связаны.

Распределение по моделям исполнения:

FBO (Ozon Fulfillment): 22 эндпоинта — заказы + управление поставками
FBS (Seller Fulfillment): 35 эндпоинтов — жизненный цикл заказа + доставка + документы
rFBS (Direct Fulfillment): 12 эндпоинтов — статусы + условная отмена
Маркировка товаров: 12 эндпоинтов (v4, v5, v6)

4. Финансы (Finance) — 7 эндпоинтов

Финансовые операции: транзакции, отчеты о реализации, взаиморасчеты, B2B продажи.

#	Метод	Путь	Описание
1	POST	`/v3/finance/transaction/list`	Список транзакций
2	POST	`/v3/finance/transaction/totals`	Суммы транзакций
3	POST	`/v1/finance/realization`	Отчёт о реализации товаров
4	POST	`/v2/finance/realization`	Отчёт о реализации товаров (версия 2)
5	POST	`/v1/finance/cash-flow-statement/list`	Финансовый отчёт
6	POST	`/v1/finance/document-b2b-sales`	Реестр продаж юридическим лицам
7	POST	`/v1/finance/mutual-settlement`	Отчёт о взаиморасчётах

Группировка по функциям:

Управление транзакциями (2): transaction/list, transaction/totals
Отчеты о реализации (2): realization (v1, v2)
Финансовые отчеты (1): cash-flow-statement/list
B2B операции (1): document-b2b-sales
Взаиморасчеты (1): mutual-settlement

5. Аналитика (Analytics) — 4 эндпоинта

Бизнес-аналитика: отчеты по остаткам, оборачиваемость, управление запасами.

#	Метод	Путь	Описание
1	POST	`/v1/analytics/data`	Данные аналитики
2	POST	`/v2/analytics/stock_on_warehouses`	Отчёт по остаткам и товарам
3	POST	`/v1/analytics/turnover/stocks`	Оборачиваемость товара
4	POST	`/v1/analytics/manage/stocks`	Управление остатками (Beta)

Группировка по функциям:

Общая аналитика (1): analytics/data
Отчеты по складам (1): stock_on_warehouses (v2)
Оборачиваемость (1): turnover/stocks
Управление запасами (1): manage/stocks (Beta)

6. Цены и Склад (Prices & Stocks) — 20 эндпоинтов

Управление ценами и остатками: обновление цен, управление скидками, автоматические стратегии ценообразования.

6.1 Управление ценами и остатками (8 эндпоинтов)

#	Метод	Путь	Описание
1	POST	`/v5/product/info/prices`	Получить информацию о цене товара
2	POST	`/v1/product/import/prices`	Обновить цену
3	POST	`/v4/product/info/stocks`	Информация о количестве товаров
4	POST	`/v1/product/import/stocks`	Обновить остатки
5	POST	`/v1/product/info/stocks-by-warehouse/fbs`	Информация об остатках на складах продавца (FBS и rFBS)
6	POST	`/v2/products/stocks`	Обновить количество товаров на складах
7	POST	`/v1/product/info/discounted`	Узнать информацию об уценке и основном товаре по SKU уценённого товара
8	POST	`/v1/product/update/discount`	Установить скидку на уценённый товар

6.2 Стратегии ценообразования (13 эндпоинтов)

#	Метод	Путь	Описание
9	POST	`/v1/pricing-strategy/competitors/list`	Список конкурентов
10	POST	`/v1/pricing-strategy/create`	Создать стратегию
11	POST	`/v1/pricing-strategy/delete`	Удалить стратегию
12	POST	`/v1/pricing-strategy/strategy-ids-by-product-ids`	Список идентификаторов стратегий
13	POST	`/v1/pricing-strategy/info`	Информация о стратегии
14	POST	`/v1/pricing-strategy/products/add`	Добавить товары в стратегию
15	POST	`/v1/pricing-strategy/products/delete`	Удалить товары из стратегии
16	POST	`/v1/pricing-strategy/product/info`	Цена товара у конкурента
17	POST	`/v1/pricing-strategy/products/list`	Список товаров в стратегии
18	POST	`/v1/pricing-strategy/list`	Список стратегий
19	POST	`/v1/pricing-strategy/status`	Изменить статус стратегии
20	POST	`/v1/pricing-strategy/update`	Обновить стратегию

Группировка по функциям:

Информация о ценах и обновление (3): info/prices, import/prices, info/discounted
Информация об остатках и обновление (4): info/stocks, import/stocks, products/stocks, stocks-by-warehouse/fbs
Управление скидками (2): info/discounted, update/discount
CRUD стратегий (4): create, info, update, delete
Управление товарами в стратегиях (3): products/add, products/delete, products/list
Конкуренты и анализ (2): competitors/list, product/info
Управление стратегиями (2): list, status

7. Возвраты и Акции (Returns & Promotions) — 31 эндпоинт

Управление возвратами (18) и промо-акциями (13): заявки на возврат, скидки, Hot Sales.

7.1 Возвраты (18 эндпоинтов)

rFBS Управление возвратами (7 эндпоинтов):

#	Метод	Путь	Описание
1	POST	`/v2/returns/rfbs/list`	Список заявок на возврат
2	POST	`/v2/returns/rfbs/get`	Информация о заявке на возврат
3	POST	`/v2/returns/rfbs/return-money`	Вернуть деньги покупателю
4	POST	`/v2/returns/rfbs/reject`	Отклонить заявку на возврат
5	POST	`/v2/returns/rfbs/verify`	Одобрить заявку на возврат
6	POST	`/v2/returns/rfbs/compensate`	Вернуть часть стоимости товара
7	POST	`/v2/returns/rfbs/receive-return`	Подтвердить получение товара на проверку

Операции с возвратными отгрузками (7 эндпоинтов):

#	Метод	Путь	Описание
8	POST	`/v1/return/giveout/list`	Список возвратных отгрузок
9	POST	`/v1/return/giveout/info`	Информация о возвратной отгрузке
10	POST	`/v1/return/giveout/is-enabled`	Проверить возможность получения возвратных отгрузок по штрихкоду
11	POST	`/v1/return/giveout/barcode`	Значение штрихкода для возвратных отгрузок
12	POST	`/v1/return/giveout/get-pdf`	Штрихкод для получения возвратной отгрузки в формате PDF
13	POST	`/v1/return/giveout/get-png`	Штрихкод для получения возвратной отгрузки в формате PNG
14	POST	`/v1/return/giveout/barcode-reset`	Сгенерировать новый штрихкод

Общая информация о возвратах (2 эндпоинта):

#	Метод	Путь	Описание
15	POST	`/v1/returns/list`	Информация о возвратах FBO и FBS
16	POST	`/v1/returns/company/fbs/info`	Количество возвратов FBS

7.2 Акции (13 эндпоинтов)

Общие акции (5 эндпоинтов):

#	Метод	Путь	Описание
17	GET	`/v1/actions`	Список акций
18	POST	`/v1/actions/candidates`	Список доступных для акции товаров
19	POST	`/v1/actions/products`	Список участвующих в акции товаров
20	POST	`/v1/actions/products/activate`	Добавить товар в акцию
21	POST	`/v1/actions/products/deactivate`	Удалить товары из акции

Управление заявками на скидки (3 эндпоинта):

#	Метод	Путь	Описание
22	POST	`/v1/actions/discounts-task/list`	Список заявок на скидку
23	POST	`/v1/actions/discounts-task/approve`	Согласовать заявку на скидку
24	POST	`/v1/actions/discounts-task/decline`	Отклонить заявку на скидку

Акции Hot Sale (5 эндпоинтов):

#	Метод	Путь	Описание
25	POST	`/v1/actions/hotsales/list`	Список доступных акций Hot Sale
26	POST	`/v1/actions/hotsales/products`	Список товаров, которые участвуют в акции Hot Sale
27	POST	`/v1/actions/hotsales/activate`	Добавить товары в акцию Hot Sale
28	POST	`/v1/actions/hotsales/deactivate`	Удалить товары из акции Hot Sale

8. Дополнительные категории

Категории (Categories) — 4 эндпоинта

Дерево категорий товаров, характеристики, справочники значений атрибутов.

Штрихкоды (Barcodes) — 2 эндпоинта

Генерация и привязка штрихкодов к товарам.

Бренды (Brands) — 1 эндпоинт

Сертификация брендов.

Сертификация (Certification) — 15 эндпоинтов

Управление сертификацией товаров (самая большая дополнительная категория, отражает требования российского законодательства).

Чаты (Chats) — 6 эндпоинтов

Обмен сообщениями с поддержкой Ozon.

Грузы (Cargoes) — 10 эндпоинтов

Управление грузоперевозками и перевозками.

Пропуска (Passes) — 7 эндпоинтов

Пропуска для водителей и транспорта на склады.

Полигоны (Polygons) — 2 эндпоинта

Управление зонами доставки.

Вопросы и ответы (Q&A) — 7 эндпоинтов

Вопросы покупателей о товарах и ответы на них.

Отзывы (Reviews) — 7 эндпоинтов

Управление отзывами на товары.

Рейтинг продавца (Seller Rating) — 2 эндпоинта

Метрики качества продаж и производительности.

Поставщики/Счета (Supplier/Invoices) — 4 эндпоинта

B2B операции, управление счетами.

Склады (Warehouses) — 2 эндпоинта

Информация о складах Ozon.

Quants — 6 эндпоинтов

Операции с количеством товаров.

Отчеты (Reports) — 8 эндпоинтов

Генерация различных типов отчетов.

Примечания к эндпоинтам

Версии API

Ozon Seller API активно развивается, и многие эндпоинты доступны в нескольких версиях:

v1: Базовые стабильные эндпоинты
v2: Улучшенные версии с расширенным функционалом
v3-v6: Последние версии для специализированных операций

Рекомендации:

Используйте последние версии API (v2, v3, v4, v5, v6) для новых интеграций
v1 поддерживается для обратной совместимости

HTTP Методы

Подавляющее большинство эндпоинтов (97%+) используют метод POST, что соответствует паттерну дизайна Ozon API для сложных запросов и операций.

Модели исполнения

Ozon использует три модели исполнения заказов, каждая со специализированным набором эндпоинтов:

FBO: Ozon хранит, упаковывает и отправляет товары (~22 эндпоинта)
FBS: Продавец хранит и отправляет на склад Ozon (~35 эндпоинтов)
rFBS: Продавец хранит и отправляет напрямую покупателям (~12 эндпоинтов)

Специфичные для России функции

Некоторые категории эндпоинтов специфичны для российского рынка:

Маркировка товаров (Chestny Znak): 12 эндпоинтов для работы с системой «Честный ЗНАК»
Сертификация: 15 эндпоинтов для управления сертификатами соответствия

Коды ошибок

Ozon Seller API использует комбинированную систему кодов ошибок, включающую:

HTTP статусы — основные коды состояния HTTP
Числовые коды ошибок Ozon — специфические коды ошибок платформы
Строковые коды ошибок — описательные коды для конкретных сценариев

HTTP Статус коды

400 Bad Request — Ошибка клиента

Python исключение: OzonAPIClientError

Описание: Неверный формат запроса, невалидные данные или параметры.

Частые причины:

Неверный JSON формат в теле запроса
Отсутствие обязательных полей
Неверные значения параметров
Нарушение валидации данных

Пример ответа:

{
  "code": 400,
  "message": "Bad Request",
  "details": [
    {
      "field": "price",
      "message": "Ставка не входит в диапазон допустимых значений"
    }
  ]
}

403 Forbidden — Ошибка доступа

Python исключение: OzonAPIForbiddenError

Описание: Доступ запрещён или недостаточно прав.

Частые причины:

Offer not signed — в личном кабинете продавца отсутствует подписанная офферта
Обращение к методу, недоступному в текущей роли
Недостаточно прав для выполнения операции

Пример ответа:

{
  "code": 403,
  "message": "Forbidden",
  "details": "Offer not signed"
}

404 Not Found — Ресурс не найден

Python исключение: OzonAPINotFoundError

Описание: Запрашиваемый ресурс не существует или недоступен.

Частые причины:

Invalid Api-Key — неверный API ключ
Несуществующий endpoint URL
Удалённый ресурс (товар, заказ и т.д.)

Пример ответа:

{
  "code": 404,
  "message": "Not Found",
  "details": "Invalid Api-Key, please contact support"
}

409 Conflict — Конфликт

Python исключение: OzonAPIConflictError

Описание: Конфликт состояния ресурса с выполняемой операцией.

Частые причины:

Попытка создать уже существующий ресурс
Конфликт версий при обновлении
Нарушение бизнес-логики

Пример ответа:

{
  "code": 409,
  "message": "Conflict",
  "details": "Product already exists"
}

429 Too Many Requests — Превышение лимита запросов

Числовой код ошибки Ozon: 8

Описание: Превышен лимит частоты запросов.

Глобальные лимиты (на 19 мая 2025):

50 запросов в секунду на Client ID

Пример ответа:

{
  "code": 8,
  "message": "Too many requests",
  "details": "Rate limit exceeded. Please retry later."
}

500 Internal Server Error — Ошибка сервера

Python исключение: OzonAPIServerError

Описание: Внутренняя ошибка сервера Ozon.

Частые причины:

Временные сбои на стороне Ozon
Ошибка в обработке запроса
Проблемы с инфраструктурой

Рекомендация: Повторить запрос через некоторое время.

Пример ответа:

{
  "code": 500,
  "message": "Internal Server Error",
  "details": "An unexpected error occurred. Please try again later."
}

Специфические коды ошибок Ozon

"Circle is open" — Блокировка метода

Описание: Система блокирует работу метода на несколько минут при выполнении слишком большого количества запросов.

Тип ошибки: Rate limiting / Request throttling

Причина: Превышение порога частоты запросов

Длительность блокировки: Несколько минут

Решение:

Реализовать rate limiting на стороне клиента
Использовать экспоненциальную задержку (exponential backoff)
Оптимизировать код для уменьшения количества запросов
Мониторить частоту запросов

Строковые коды ошибок

Ошибки API ключей (обновлено февраль 2025)

INVALID_API_KEY — Неверный API ключ
API_KEY_DISABLED — API ключ отключён
API_KEY_EXPIRED — Срок действия API ключа истёк

Ошибки товаров и цен

PRICE_IS_NOT_SENT — товар ещё не создан или находится на стадии обновления
MP_DELIVERY_ONLY_3PL_ERROR — товар нельзя размещать на складе с методом доставки «Ozon»
PRODUCT_NOT_FOUND — товар не найден
INVALID_PRODUCT_ID — неверный ID товара

Ошибки атрибутов товаров

MISSING_REQUIRED_ATTRIBUTE — отсутствует обязательный атрибут
INVALID_ATTRIBUTE_VALUE — неверное значение атрибута
TYPE_ID_REQUIRED — не указан тег type_id

Ошибки категорий

INVALID_CATEGORY_ID — неверная категория
CATEGORY_NOT_FOUND — категория не найдена

Структура ошибок в ответах API

Базовая структура ошибки

{
  "code": <числовой_код>,
  "message": "<текст_ошибки>",
  "details": [<дополнительная_информация>]
}

Пример полной структуры ошибки

{
  "code": 5,
  "message": "Validation error",
  "details": [
    {
      "code": "MISSING_REQUIRED_FIELD",
      "field": "barcode",
      "message": "Поле 'barcode' обязательно для заполнения"
    },
    {
      "code": "INVALID_VALUE",
      "field": "price",
      "message": "Цена должна быть больше 0"
    }
  ]
}

Обработка ошибок

Python (с библиотекой ozon-api)

from ozon_api import OzonAPIError, OzonAPIClientError, OzonAPIForbiddenError
from ozon_api import OzonAPINotFoundError, OzonAPIConflictError, OzonAPIServerError

try:
    response = await api.product_list(request)
except OzonAPIClientError as e:
    print(f"Ошибка клиента (400): {e.message}")
except OzonAPIForbiddenError as e:
    print(f"Ошибка доступа (403): {e.message}")
    print("Проверьте подписанную офферт в личном кабинете")
except OzonAPINotFoundError as e:
    print(f"Ресурс не найден (404): {e.message}")
    print("Проверьте API ключ")
except OzonAPIConflictError as e:
    print(f"Конфликт (409): {e.message}")
except OzonAPIServerError as e:
    print(f"Ошибка сервера (500): {e.message}")
    print("Повторите запрос позже")
except OzonAPIError as e:
    print(f"Общая ошибка API: {e.message}")

Обработка rate limiting (429)

import asyncio
from asyncio import sleep

async def call_with_retry(api_call, max_retries=5):
    for attempt in range(max_retries):
        try:
            return await api_call()
        except Exception as e:
            if e.code == 8 or e.status == 429:  # Rate limit
                wait_time = 2 ** attempt  # Экспоненциальная задержка
                print(f"Rate limit exceeded. Waiting {wait_time}s...")
                await sleep(wait_time)
            else:
                raise e
    raise Exception("Max retries exceeded")

Go (с библиотекой ozon-api-client)

package main

import (
    "fmt"
    "github.com/diphantxm/ozon-api-client/ozon"
)

func handleError(err error) {
    if ozonErr, ok := err.(*ozon.Error); ok {
        switch ozonErr.StatusCode {
        case 400:
            fmt.Printf("Client Error: %s\n", ozonErr.Message)
        case 403:
            fmt.Printf("Forbidden: %s\n", ozonErr.Message)
        case 404:
            fmt.Printf("Not Found: %s\n", ozonErr.Message)
        case 429:
            fmt.Printf("Rate Limit: %s\n", ozonErr.Message)
        case 500:
            fmt.Printf("Server Error: %s\n", ozonErr.Message)
        default:
            fmt.Printf("Unknown Error: %s\n", ozonErr.Message)
        }
    }
}

Стратегии обработки ошибок

1. Retry Logic (Повторные попытки)

Применимо для:

HTTP 429 (Too Many Requests)
HTTP 500 (Internal Server Error)
Временных сетевых ошибок

Стратегия:

Экспоненциальная задержка (exponential backoff)
Максимум 3-5 попыток
Увеличение времени ожидания между попытками

2. Логирование ошибок

Рекомендации:

Логировать все ошибки с контекстом
Сохранять request ID для трассировки
Записывать параметры запроса (без чувствительных данных)
Фиксировать timestamp для анализа

3. Мониторинг

Метрики для отслеживания:

Частота ошибок по типам
Время ответа
Процент неудачных запросов
Количество retry операций

4. Обработка специфических ошибок

Invalid Api-Key (404):

Проверить корректность API ключа
Убедиться, что ключ не отозван
Проверить права доступа роли

Offer not signed (403):

Подписать оферту в личном кабинете
Проверить роль пользователя

"Circle is open":

Уменьшить частоту запросов
Реализовать пакетную обработку
Добавить задержки между запросами

Лучшие практики

Rate Limiting на стороне клиента — реализовать ограничение частоты запросов
Пакетная обработка — использовать пакетные запросы вместо множества одиночных
Асинхронная обработка — использовать асинхронные библиотеки для эффективности
Circuit Breaker Pattern — прекратить запросы при постоянных ошибках
Логирование — сохранять подробную информацию об ошибках
Мониторинг — отслеживать метрики ошибок

Полезные ресурсы

Webhooks (Push-уведомления)

Ozon Seller API использует механизм push-уведомлений (webhooks) для отправки реальных событий на ваш сервер. Это позволяет вашей системе мгновенно реагировать на изменения в заказах, товарах, сообщениях и других сущностях маркетплейса.

Официальная документация: https://docs.ozon.ru/api/seller/en/#tag/push_intro

Обзор

Ozon Seller API поддерживает 13 типов push-уведомлений для автоматической интеграции:

Категория	Типы уведомлений	Количество
Управление заказами	Новый заказ, отмена, изменение статуса, изменение дат	5
Управление товарами	Создание/обновление, изменение цены, изменение остатков	3
Коммуникации	Новое сообщение, редактирование, прочтение, закрытие чата	4
Служебные	Проверка соединения	1
ИТОГО		13

Важные термины

Push-уведомление — HTTP-запрос, который Ozon отправляет на ваш URL при наступлении события
MessageType — тип уведомления (константа, идентифицирующая событие)
Payload — JSON-тело уведомления с данными события

Типы уведомлений (Message Types)

1. TYPE_PING — Проверка соединения

Отправляется при первоначальном подключении и периодически для проверки доступности вашего сервера.

Payload:

{
  "message_type": "TYPE_PING",
  "time": "2026-02-10T12:00:00Z"
}

Ожидаемый ответ:

{
  "version": "1.0",
  "name": "Ozon Seller API",
  "time": "2026-02-10T12:00:00Z"
}

2. TYPE_NEW_POSTING — Новое отправление (заказ)

Уведомление о создании нового заказа.

Payload:

{
  "message_type": "TYPE_NEW_POSTING",
  "posting_number": "12345678-0001",
  "products": [
    {
      "sku": 123456,
      "quantity": 2
    }
  ],
  "in_process_at": "2026-02-10T12:00:00Z",
  "warehouse_id": 123456789,
  "seller_id": 12345
}

Поля:

posting_number (string) — Номер отправления
products (array) — Массив товаров в отправлении
in_process_at (datetime) — Дата и время начала обработки в UTC
warehouse_id (int64) — ID склада
seller_id (int64) — ID продавца

3. TYPE_POSTING_CANCELLED — Отмена отправления

Заказ был отменён.

Payload:

{
  "message_type": "TYPE_POSTING_CANCELLED",
  "posting_number": "12345678-0001",
  "products": [
    {
      "sku": 123456,
      "quantity": 2
    }
  ],
  "old_state": "awaiting_packaging",
  "new_state": "posting_canceled",
  "changed_state_date": "2026-02-10T12:00:00Z",
  "reason": {
    "id": 1,
    "message": "Покупатель отменил заказ"
  },
  "warehouse_id": 123456789,
  "seller_id": 12345
}

Дополнительные поля:

old_state (string) — Предыдущий статус
new_state (string) — Новый статус
reason (object) — Причина отмены

4. TYPE_STATE_CHANGED — Изменение статуса отправления

Статус заказа изменился.

Payload:

{
  "message_type": "TYPE_STATE_CHANGED",
  "posting_number": "12345678-0001",
  "new_state": "delivering",
  "changed_state_date": "2026-02-10T12:00:00Z",
  "warehouse_id": 123456789,
  "seller_id": 12345
}

5. TYPE_CUTOFF_DATE_CHANGED — Изменение даты отгрузки

Дата, к которой нужно подготовить товар, изменилась.

Payload:

{
  "message_type": "TYPE_CUTOFF_DATE_CHANGED",
  "posting_number": "12345678-0001",
  "new_cutoff_date": "2026-02-12T18:00:00Z",
  "old_cutoff_date": "2026-02-11T18:00:00Z",
  "warehouse_id": 123456789,
  "seller_id": 12345
}

6. TYPE_DELIVERY_DATE_CHANGED — Изменение даты доставки

Промежуток времени для доставки изменился.

Payload:

{
  "message_type": "TYPE_DELIVERY_DATE_CHANGED",
  "posting_number": "12345678-0001",
  "new_delivery_date_begin": "2026-02-15T00:00:00Z",
  "new_delivery_date_end": "2026-02-17T23:59:59Z",
  "old_delivery_date_begin": "2026-02-14T00:00:00Z",
  "old_delivery_date_end": "2026-02-16T23:59:59Z",
  "warehouse_id": 123456789,
  "seller_id": 12345
}

7. TYPE_CREATE_OR_UPDATE_ITEM — Создание/обновление товара

Товар создан, обновлён или возникла ошибка при обработке.

Payload:

{
  "message_type": "TYPE_CREATE_OR_UPDATE_ITEM",
  "offer_id": "PRODUCT-123",
  "product_id": 123456789,
  "is_error": false,
  "changed_at": "2026-02-10T12:00:00Z",
  "seller_id": 12345
}

Поля:

offer_id (string) — Идентификатор товара в системе продавца
product_id (int64) — ID товара в Ozon
is_error (boolean) — true если при создании/обновлении возникли ошибки

8. TYPE_PRICE_INDEX_CHANGED — Изменение ценового индекса

Изменился ценовой индекс товара.

Payload:

{
  "message_type": "TYPE_PRICE_INDEX_CHANGED",
  "updated_at": "2026-02-10T12:00:00Z",
  "sku": 123456,
  "product_id": 123456789,
  "price_index": 1500,
  "seller_id": 12345
}

Поля:

price_index (int64) — Новый ценовой индекс (в копейках)

9. TYPE_STOCKS_CHANGED — Изменение остатков

Остатки товаров на складе изменились.

Payload:

{
  "message_type": "TYPE_STOCKS_CHANGED",
  "items": [
    {
      "updated_at": "2026-02-10T12:00:00Z",
      "sku": 123456,
      "product_id": 123456789,
      "stocks": [
        {
          "warehouse_id": 123456789,
          "present": 100,
          "reserved": 10
        }
      ]
    }
  ],
  "seller_id": 12345
}

Поля:

items (array) — Массив товаров с изменившимися остатками
stocks (array) — Массив остатков по складам
- present (int64) — Общее количество товара
- reserved (int64) — Зарезервировано

10. TYPE_NEW_MESSAGE — Новое сообщение в чате

Покупатель или служба поддержки отправили сообщение.

Payload:

{
  "message_type": "TYPE_NEW_MESSAGE",
  "chat_id": "chat-12345",
  "chat_type": "CUSTOMER",
  "message_id": "msg-67890",
  "created_at": "2026-02-10T12:00:00Z",
  "user": {
    "id": "user-999",
    "type": "CUSTOMER"
  },
  "data": [
    "Здравствуйте, когда будет отправка?"
  ],
  "seller_id": 12345
}

Поля:

chat_id (string) — ID чата
chat_type (string) — Тип чата (CUSTOMER, SUPPORT)
message_id (string) — ID сообщения
data (array of strings) — Содержание сообщения в формате Markdown

11. TYPE_UPDATE_MESSAGE — Изменение сообщения в чате

Сообщение было отредактировано.

Payload:

{
  "message_type": "TYPE_UPDATE_MESSAGE",
  "chat_id": "chat-12345",
  "chat_type": "CUSTOMER",
  "message_id": "msg-67890",
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-10T12:05:00Z",
  "user": {
    "id": "user-999",
    "type": "CUSTOMER"
  },
  "data": [
    "Здравствуйте, уточните когда будет отправка?"
  ],
  "seller_id": 12345
}

12. TYPE_MESSAGE_READ — Прочитанное сообщение

Покупатель или служба поддержки прочитали ваше сообщение.

Payload:

{
  "message_type": "TYPE_MESSAGE_READ",
  "chat_id": "chat-12345",
  "chat_type": "CUSTOMER",
  "message_id": "msg-67890",
  "created_at": "2026-02-10T12:00:00Z",
  "user": {
    "id": "user-999",
    "type": "CUSTOMER"
  },
  "data": [
    "Ваше сообщение"
  ],
  "last_read_message_id": "msg-67890",
  "seller_id": 12345
}

Дополнительное поле:

last_read_message_id (string) — ID последнего прочитанного сообщения

13. TYPE_CHAT_CLOSED — Чат закрыт

Чат с покупателем был закрыт.

Payload:

{
  "message_type": "TYPE_CHAT_CLOSED",
  "chat_id": "chat-12345",
  "chat_type": "CUSTOMER",
  "user": {
    "id": "user-999",
    "type": "SELLER"
  },
  "seller_id": 12345
}

Настройка webhook-сервера

Требования к серверу

Доступность: Сервер должен быть доступен из интернета по HTTPS
Порт: Любой порт (настраивается в личном кабинете Ozon)
Отклик: Сервер должен отвечать HTTP 200 с телом {"result": true}
Timeout: Обрабатывать запросы быстро (рекомендуется < 5 секунд)

Пример реализации на Python (Flask)

from flask import Flask, request, jsonify
from datetime import datetime

app = Flask(__name__)

@app.route('/', methods=['POST'])
def handle_webhook():
    data = request.json
    message_type = data.get('message_type')

    if message_type == 'TYPE_PING':
        # Проверка соединения
        return jsonify({
            'version': '1.0',
            'name': 'Ozon Seller API',
            'time': datetime.utcnow().isoformat()
        })

    elif message_type == 'TYPE_NEW_POSTING':
        posting_number = data.get('posting_number')
        products = data.get('products', [])
        # Обработка нового заказа
        print(f"Новое отправление: {posting_number}")
        for product in products:
            print(f"  SKU: {product['sku']}, Кол-во: {product['quantity']}")

    elif message_type == 'TYPE_POSTING_CANCELLED':
        posting_number = data.get('posting_number')
        reason = data.get('reason', {}).get('message', 'Неизвестно')
        print(f"Отправление {posting_number} отменено: {reason}")

    elif message_type == 'TYPE_NEW_MESSAGE':
        chat_id = data.get('chat_id')
        message_data = data.get('data', [])
        print(f"Новое сообщение в чате {chat_id}: {message_data}")

    # ... обработка остальных типов ...

    # Всегда возвращаем успешный ответ
    return jsonify({'result': True})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, ssl_context='adhoc')

Пример реализации на Go

package main

import (
    "log"
    "github.com/diphantxm/ozon-api-client/ozon/notifications"
)

func main() {
    port := 5000
    server := notifications.NewNotificationServer(port)

    server.Register(notifications.NewPostingType, func(req interface{}) error {
        notification := req.(*notifications.NewPosting)
        log.Printf("Новое отправление: %s\n", notification.PostingNumber)
        return nil
    })

    server.Register(notifications.PostingCancelledType, func(req interface{}) error {
        notification := req.(*notifications.PostingCancelled)
        log.Printf("Отправление %s отменено\n", notification.PostingNumber)
        return nil
    })

    server.Register(notifications.StateChangedType, func(req interface{}) error {
        notification := req.(*notifications.StateChanged)
        log.Printf("Статус отправления %s изменен на %s\n",
            notification.PostingNumber, notification.NewState)
        return nil
    })

    if err := server.Run(); err != nil {
        log.Printf("Ошибка запуска сервера: %s", err)
    }
}

Процесс настройки webhook-интеграции

Шаг 1: Разверните webhook-сервер

Разработайте и разверните сервер для приёма webhook-уведомлений
Убедитесь, что сервер доступен из интернета по HTTPS
Протестируйте обработку TYPE_PING запроса

Шаг 2: Зарегистрируйте webhook в личном кабинете

Процесс регистрации:

Войдите в личный кабинет продавца Ozon (seller.ozon.ru)
Перейдите в раздел Настройки → API
Найдите подраздел Push-уведомления или Webhooks
Укажите URL вашего webhook-сервера
Выберите типы уведомлений, которые хотите получать
Сохраните настройки

Важно: Точный путь настройки может отличаться. Рекомендуется обратиться к официальной документации Ozon.

Шаг 3: Проверьте работу webhook

Ozon отправит тестовый запрос TYPE_PING на ваш URL
Ваш сервер должен ответить корректной структурой с версией и временем
После успешной проверки Ozon начнёт отправлять уведомления

Обработка ошибок webhook

Структура ошибки

{
  "error": {
    "code": "400",
    "message": "Ошибка валидации",
    "details": "Поле 'posting_number' обязательно"
  }
}

HTTP-коды ответов

200 OK — Уведомление успешно обработано
400 Bad Request — Неверный формат запроса или невалидные данные
500 Internal Server Error — Внутренняя ошибка вашего сервера

Важно: Даже если ваш сервер вернёт ошибку, Ozon может повторить отправку уведомления. Рекомендуется всегда возвращать 200 с {"result": true} после успешной обработки.

Категории уведомлений по бизнес-процессам

Управление заказами

TYPE_NEW_POSTING — Новый заказ
TYPE_POSTING_CANCELLED — Отмена заказа
TYPE_STATE_CHANGED — Изменение статуса
TYPE_CUTOFF_DATE_CHANGED — Изменение даты отгрузки
TYPE_DELIVERY_DATE_CHANGED — Изменение даты доставки

Управление товарами

TYPE_CREATE_OR_UPDATE_ITEM — Создание/обновление товара
TYPE_PRICE_INDEX_CHANGED — Изменение цены
TYPE_STOCKS_CHANGED — Изменение остатков

Коммуникации с клиентами

TYPE_NEW_MESSAGE — Новое сообщение
TYPE_UPDATE_MESSAGE — Редактирование сообщения
TYPE_MESSAGE_READ — Прочитанное сообщение
TYPE_CHAT_CLOSED — Закрытие чата

Служебные

TYPE_PING — Проверка соединения

Полезные ссылки

Официальная документация

Клиентские библиотеки с поддержкой webhook

Go (diPhantxm/ozon-api-client) — Поддержка всех 13 типов уведомлений
Laravel (muscobytes/laravel-ozon-seller-webhook) — Конфигурация через Laravel

Сообщество

Telegram канал (EN)

Скачать файлы спецификаций

В этом разделе приведены ссылки на файлы спецификаций API Ozon Seller, которые могут быть полезны для интеграции.

Локальные файлы

Файл	Описание	Формат
ozon-postman-collection.json	Коллекция запросов Postman для Ozon Seller API	Postman Collection v2.1.0

Путь к файлу: ./ozon-postman-collection.json

Описание: Коллекция Postman содержит примеры запросов ко всем основным эндпоинтам Ozon Seller API. Включает предварительно настроенные заголовки (Client-Id, Api-Key) и примеры тел запросов. Полезна для тестирования API и изучения формата запросов/ответов.

Онлайн спецификации

Ресурс	URL	Описание
OpenAPI/Swagger JSON	https://docs.ozon.ru/api/seller/swagger.json	Официальная спецификация OpenAPI/Swagger в формате JSON
Postman Collection	https://www.postman.com/googlesheets/ozon-seller-api/documentation/m2uvw9f/ozon-seller-api	Онлайн-коллекция Postman с документацией
Официальная документация	https://docs.ozon.ru/api/seller/	Полная документация API (на русском языке)
English Documentation	https://docs.ozon.ru/api/seller/en/	Документация API на английском языке

Использование спецификаций

Импорт Postman коллекции

Откройте Postman
Нажмите Import в левом верхнем углу
Выберите файл ozon-postman-collection.json
Коллекция будет загружена в ваш Postman workspace

Преимущества:

Готовые примеры запросов для всех эндпоинтов
Предварительно настроенные заголовки аутентификации
Удобное тестирование API без написания кода
Возможность сохранять окружения (environments) для разных аккаунтов

Использование OpenAPI/Swagger спецификации

Для генерации клиентских библиотек:

# OpenAPI Generator (Java)
openapi-generator generate -i ozon-swagger.json -g python -o ./ozon-client

# Swagger Codegen
swagger-codegen generate -i ozon-swagger.json -l python -o ./ozon-client

Для загрузки в инструменты:

Insomnia: File → Import → From File → ozon-swagger.json
Swagger UI: https://editor.swagger.io/ (загрузите файл)
Stoplight Studio: Import → OpenAPI Document

Дополнительные ресурсы

Клиентские библиотеки (с исходным кодом)

Язык	Библиотека	Репозиторий
Python	ozon-api	https://pypi.org/project/ozon-api/
Python	ozon-api-client	https://pypi.org/project/ozon-api-client/
PHP	gam6itko/ozon-seller	https://github.com/gam6itko/ozon-seller
Go	diPhantxm/ozon-api-client	https://github.com/diPhantxm/ozon-api-client
TypeScript	ozon-daytona-seller-api	https://www.npmjs.com/package/ozon-daytona-seller-api
C#	OzonSellerApi	https://github.com/feeleen/OzonSellerApi

Эти библиотеки содержат реализации всех методов API и могут использоваться как справочник при интеграции.

Примечания к спецификациям

⚠️ Важно:

Ozon периодически обновляет API и добавляет новые эндпоинты
Рекомендуется регулярно проверять актуальность спецификаций
Некоторые новые эндпоинты могут отсутствовать в старых версиях коллекций
Официальная документация на docs.ozon.ru является наиболее авторитетным источником

Актуальность:

Локальный файл Postman коллекции: загружен 10 февраля 2026
Swagger JSON доступен онлайн в реальном времени
Рекомендуется использовать swagger.json для проверки последних изменений

Конец документа

Содержание​

Аутентификация​

Требуемые заголовки​

Формат заголовков​

Как получить учетные данные​

Пошаговая инструкция​

Визуальный путь навигации​

Управление API-ключами​

Несколько ключей​

Безопасность ключей​

Ролевой доступ (RBAC)​

Примеры использования​

Python (Async)​

Python (HTTP-клиент)​

TypeScript/JavaScript​

cURL​

PHP​

Go​

Обработка ошибок аутентификации​

Конфигурация​

Поддержка языков​

Базовый URL​

Ограничения на запросы (Rate Limits)​

Глобальные ограничения​

Ответы при превышении лимитов​

HTTP-код состояния​

Формат ответа с ошибкой​

Специфические ограничения эндпоинтов​

Управление товарами​

Обновление складских остатков​

Операции с штрихкодами​

Аналитика и отчеты​

Заголовки ограничения частоты​

Текущий статус: ❌ Нет стандартных заголовков​

Лучшие практики обработки ограничений​

1. Ограничение частоты на стороне клиента​

2. Логика повторных попыток с экспоненциальной задержкой​

3. Пакетирование запросов​

4. Асинхронная обработка запросов​

Мониторинг ограничений частоты​

Ведение журнала​

Метрики для отслеживания​

Распределение ограничений по категориям API​

Товары​

Заказы​

Финансы​

Аналитика​

Склад и Цены​

Рекомендации по интеграции​

1. Не выходите за пределы лимита​

2. Реализуйте плавную деградацию​

3. Мониторинг и оповещения​

4. Оптимизация шаблонов запросов​

5. Планирование роста​

Резюме по ограничениям​

Обзор категорий API​

Основные категории​

Дополнительные категории​

Статистика по категориям​

Модели fulfilment​

Детальное описание эндпоинтов​

1. Товары (Products) — 21 эндпоинт​

2. Заказы (Orders) — 68 эндпоинтов​

2.1 FBO Заказы (7 эндпоинтов)​

2.2 Управление поставками FBO (6 эндпоинтов)​

2.3 FBS Заказы — Основные операции (20 эндпоинтов)​

2.4 Управление доставкой FBS (12 эндпоинтов)​

2.5 Статусы доставки rFBS (7 эндпоинтов)​

2.6 Отмена rFBS (4 эндпоинта)​

2.7 Управление маркировкой товаров (10 эндпоинтов)​

3. FBO/FBS Исполнение — 81 эндпоинт​

4. Финансы (Finance) — 7 эндпоинтов​

5. Аналитика (Analytics) — 4 эндпоинта​

6. Цены и Склад (Prices & Stocks) — 20 эндпоинтов​

6.1 Управление ценами и остатками (8 эндпоинтов)​

6.2 Стратегии ценообразования (13 эндпоинтов)​

7. Возвраты и Акции (Returns & Promotions) — 31 эндпоинт​

7.1 Возвраты (18 эндпоинтов)​

7.2 Акции (13 эндпоинтов)​

8. Дополнительные категории​

Содержание

Аутентификация

Требуемые заголовки

Формат заголовков

Как получить учетные данные

Пошаговая инструкция

Визуальный путь навигации

Управление API-ключами

Несколько ключей

Безопасность ключей

Ролевой доступ (RBAC)

Примеры использования

Python (Async)

Python (HTTP-клиент)

TypeScript/JavaScript

cURL

PHP

Go

Обработка ошибок аутентификации

Конфигурация

Поддержка языков

Базовый URL

Ограничения на запросы (Rate Limits)

Глобальные ограничения

Ответы при превышении лимитов

HTTP-код состояния

Формат ответа с ошибкой

Специфические ограничения эндпоинтов

Управление товарами

Обновление складских остатков

Операции с штрихкодами

Аналитика и отчеты

Заголовки ограничения частоты

Текущий статус: ❌ Нет стандартных заголовков

Лучшие практики обработки ограничений

1. Ограничение частоты на стороне клиента

2. Логика повторных попыток с экспоненциальной задержкой

3. Пакетирование запросов

4. Асинхронная обработка запросов

Мониторинг ограничений частоты

Ведение журнала

Метрики для отслеживания

Распределение ограничений по категориям API

Товары

Заказы

Финансы

Аналитика

Склад и Цены

Рекомендации по интеграции

1. Не выходите за пределы лимита

2. Реализуйте плавную деградацию

3. Мониторинг и оповещения

4. Оптимизация шаблонов запросов

5. Планирование роста

Резюме по ограничениям

Обзор категорий API

Основные категории

Дополнительные категории

Статистика по категориям

Модели fulfilment

Детальное описание эндпоинтов

1. Товары (Products) — 21 эндпоинт

2. Заказы (Orders) — 68 эндпоинтов

2.1 FBO Заказы (7 эндпоинтов)

2.2 Управление поставками FBO (6 эндпоинтов)

2.3 FBS Заказы — Основные операции (20 эндпоинтов)

2.4 Управление доставкой FBS (12 эндпоинтов)

2.5 Статусы доставки rFBS (7 эндпоинтов)

2.6 Отмена rFBS (4 эндпоинта)

2.7 Управление маркировкой товаров (10 эндпоинтов)

3. FBO/FBS Исполнение — 81 эндпоинт

4. Финансы (Finance) — 7 эндпоинтов

5. Аналитика (Analytics) — 4 эндпоинта

6. Цены и Склад (Prices & Stocks) — 20 эндпоинтов

6.1 Управление ценами и остатками (8 эндпоинтов)

6.2 Стратегии ценообразования (13 эндпоинтов)

7. Возвраты и Акции (Returns & Promotions) — 31 эндпоинт

7.1 Возвраты (18 эндпоинтов)

7.2 Акции (13 эндпоинтов)

8. Дополнительные категории