Зачем нужна интеграция по API

Application Programming Interface (API) — это набор способов и правил, по которым различные программы могут взаимодействовать друг с другом. Интеграция с Ozon по API позволяет полностью автоматизировать процесс обмена данными между вашей учетной системой (например, 1С, МойСклад, самописная ERP/CRM-система) и маркетплейсом. Этот метод необходим крупным продавцам, чей ассортимент исчисляется тысячами и десятками тысяч позиций, а цены и остатки меняются очень динамично.

Использование API позволяет исключить человеческий фактор при переносе данных, обеспечить моментальное обновление информации о товарах и оперативно реагировать на заказы. Загрузка товаров по API требует привлечения программистов для настройки интеграции. Все технические спецификации и документацию по методам всегда уточняйте в личном кабинете в разделе Ozon for Developers или на официальном портале документации API Ozon.

Получение доступов к API Ozon

Для того чтобы ваша система могла отправлять запросы к серверам Ozon, ей необходимо авторизоваться. Авторизация в API Ozon происходит с использованием двух ключевых параметров, которые передаются в заголовках каждого HTTP-запроса.

  • Client-Id. Это уникальный идентификатор вашего личного кабинета продавца на Ozon.
  • Api-Key. Это секретный ключ, который служит паролем для доступа к данным. Относитесь к Api-Key так же, как к паролю от банковского счета. Не передавайте его третьим лицам и не публикуйте в открытом доступе.

Чтобы получить эти данные, выполните следующие шаги:

  1. Зайдите в личный кабинет Ozon Seller с правами Управляющего или Администратора.
  2. Перейдите в раздел Настройки (иконка шестеренки) -> API ключи.
  3. Ваш Client-Id будет отображен на этой странице.
  4. Для создания нового ключа выберите тип ключа (например, Администратор для полного доступа), введите название ключа (например, Интеграция 1С) и нажмите Создать ключ. Скопируйте сгенерированный ключ, так как он показывается только один раз.

Основные методы для работы с товарами

Процесс создания карточки товара через API состоит из нескольких этапов и вызовов различных методов. Базовый URL для всех запросов — https://api-seller.ozon.ru.

1. Получение дерева категорий (/v1/description-category/tree). Прежде чем создать товар, вам нужно знать ID категории, в которую он будет загружен. Этот метод возвращает структуру всех категорий Ozon.

2. Получение характеристик категории (/v1/description-category/attribute). Зная ID категории, вы запрашиваете список характеристик, которые необходимо заполнить для товаров этой категории. Ответ содержит информацию о том, какие поля обязательны, их типы данных и ID справочников.

3. Импорт товаров («/v2/product/import»). Это основной метод для создания и обновления карточек товаров. Запрос отправляется методом POST. Тело запроса (Body) должно быть в формате JSON и содержать массив объектов товаров.

Структура JSON-запроса на импорт товаров

Рассмотрим базовую структуру массива «items», который передается в метод «/v2/product/import».

  • «offer_id» (string): Ваш артикул товара. Обязательное поле.
  • «name» (string): Название товара.
  • «barcode» (string): Штрихкод.
  • «price» (string): Цена продажи.
  • «old_price» (string): Цена до скидки.
  • «vat» (string): Ставка НДС (например, "0.1" для 10%, "0.2" для 20%, "0" для без НДС).
  • «description_category_id» (integer): ID категории.
  • «depth», «width», «height», «dimension_unit»: Габариты и единица измерения (обычно "mm").
  • «weight», «weight_unit»: Вес и единица измерения (обычно "g").
  • «attributes» (array): Массив объектов с характеристиками товара, где передаются id характеристики («id»), массив значений («values») и признак («complex_id»).

Особое внимание нужно уделить массиву «attributes». Именно здесь передаются все специфические данные: бренд, цвет, материал, ссылки на изображения. Формат передачи характеристик жестко регламентирован, и малейшее несоответствие приведет к ошибке валидации JSON схемы.

Асинхронная обработка и статусы задач

Метод /v2/product/import работает асинхронно. Это означает, что в ответ на успешный запрос вы не получаете информацию о том, созданы товары или нет. Вы получаете только «task_id» — номер задачи (задания) в очереди на обработку серверами Ozon.

Чтобы узнать результат обработки, вам необходимо использовать другой метод — «/v1/product/import/info», передав в него полученный task_id.

Рекомендуемый алгоритм работы:

  1. Собрать пачку товаров (до 1000 позиций в одном запросе) и отправить их методом импорта.
  2. Сохранить полученный «task_id».
  3. Сделать паузу (от 30 секунд до нескольких минут, в зависимости от размера пакета).
  4. Сделать запрос статуса задачи.
  5. Если статус задачи completed, проанализировать ответ. Он будет содержать массив «items» с указанием «offer_id», «product_id» (внутренний ID товара на Ozon) и массивом «errors» (если при создании конкретного товара возникли ошибки).

Лимиты API и обработка ошибок

Как и любая публичная система, API Ozon имеет ограничения (Rate Limits) для защиты от DDoS-атак и чрезмерной нагрузки. Ваша интеграция должна уметь корректно обрабатывать эти лимиты.

Обычно ограничения устанавливаются на количество запросов в секунду (RPS) для конкретного метода или группы методов. Если вы превысите лимит, сервер Ozon вернет HTTP статус 429 (Too Many Requests). При получении такого статуса ваша система не должна аварийно завершаться. Необходимо реализовать механизм экспоненциальной задержки (Exponential Backoff): подождать несколько секунд и повторить запрос.

Другие распространенные ошибки возвращают HTTP статусы 400 (Bad Request — неверная структура JSON, отсутствуют обязательные поля) или 401/403 (Unauthorized / Forbidden — неверный Client-Id или Api-Key). Подробное описание ошибок всегда содержится в теле ответа в поле message. Если текст ошибки непонятен, уточняйте в личном кабинете через поддержку разработчиков.

Частые вопросы

  • Вопрос: Можно ли через API загружать видео и rich-контент? Ответ: Да, для этого существуют отдельные методы API. Загрузка Rich-контента происходит через передачу специального JSON-объекта, описывающего виджеты.
  • Вопрос: Как часто можно отправлять запросы на обновление цен и остатков? Ответ: Методы обновления цен и остатков имеют свои собственные лимиты RPS, которые обычно выше, чем лимиты на создание товаров. Подробные актуальные цифры лимитов указаны в официальной документации API Ozon.
  • Вопрос: Что делать, если возвращается ошибка "Неизвестный атрибут" при отправке характеристик? Ответ: Это означает, что вы пытаетесь передать характеристику (ID атрибута), которая не предназначена для выбранной категории (description_category_id). Сначала всегда получайте актуальный список атрибутов для конкретной категории через метод /v1/description-category/attribute.
  • Вопрос: Как получить актуальный список брендов через API? Ответ: Имена брендов передаются как справочные значения. Вы можете получить ID справочника для характеристики "Бренд" и затем использовать метод получения значений справочника для поиска нужного бренда. Если бренда нет, его создание через API невозможно, потребуется ручная заявка через личный кабинет.
  • Вопрос: Существуют ли готовые библиотеки (SDK) для работы с API Ozon? Ответ: Ozon не предоставляет официальных SDK для всех языков программирования, однако на платформах вроде GitHub можно найти множество неофициальных библиотек (на Python, PHP, Go), созданных сообществом разработчиков, которые могут значительно ускорить процесс интеграции.