При разработке нашей системы OpenPIM мы столкнулись с необходимостью выгружать карточки товаров на Озон. У Озона есть официальная документация по АПИ, но при этом существует масса мелочей которые не всегда ясны и мы потратили много времени чтобы со всем этим разобраться. Поэтому мы решили поделиться с вами техническими деталями работы с API Озон.

При этом, надо учитывать, что мы занимаемся только созданием или обновлением карточек товаров со всей необходимой информацией, но не занимаемся вопросами цен, остатков и т.д. Поэтому в данной статье мы остановимся только на этом.

О чём нужно знать перед началом?

Прежде чем переходить к интеграции с Озон, разберём основные принципы: у Озон есть чёткая структура категорий, в которую должен вписываться каждый товар. Товары характеризуются определёнными атрибутами. Одни из них обязательны (например, "Бренд"), другие — опциональны (например, "Цвет"). Некоторые атрибуты используют справочники - заранее предопределённые списки значений. Например, если у вас есть атрибут "Цвет", то его значение должно совпадать с одним из предложенных Озон вариантов ("Красный", "Синий" и т.д.).

В итоге, вам необходимо точно выдать информацию о товаре так, как требует Озон иначе у вас ничего не получится. То есть, сначала надо получить всю эту справочную информацию, категории, атрибуты, значения атрибутов и потом уже сформировать запрос в Озон согласно этим правилам.

Получение категорий товаров

Для создания карточки товара необходимо указать правильную категорию, к которой он относится. Каждая категория имеет уникальный description_category_id, который используется при взаимодействии с API.

Чтобы получить актуальный список категорий, используется https://docs.ozon.ru/api/seller/#operation/DescriptionCategoryAPI_GetTree. Этот метод возвращает не просто дерево категорий, но и их статус доступности для использования.

Пример запроса POST:

{
  "language": "RU"
}

Ответ API:

{
  "result": [
    {
      "description_category_id": 17027492,
      "category_name": "Канцелярские товары",
      "disabled": false,
      "children": [
        {
          "description_category_id": 17029016,
          "category_name": "Печати и штампы",
          "disabled": false,
          "children": [
            {
              "type_name": "Пистолет-маркиратор",
              "type_id": 970778135,
              "disabled": false,
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

Расшифровка ответа:

description_category_id — уникальный ID категории, который используется для создания карточек товаров.

category_name — название категории.

disabled — статус категории (false — доступна, true — недоступна).

children — вложенные подкатегории.

Пример:

Для "Пистолет-маркиратор" ID категории будет 970778135. Этот идентификатор используется в запросах при создании карточек товаров.

Важно!

Обращайте внимание на значение поля disabled. Если оно равно true, категория или подкатегория временно недоступна для использования, и товары в неё добавлять нельзя.

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

Получение характеристик для категории

После выбора категории важно определить, какие атрибуты необходимо заполнить для товаров этой категории. Это делается с помощью метода https://docs.ozon.ru/api/seller/#operation/DescriptionCategoryAPI_GetAttributes, который возвращает полный список характеристик, их свойства и требования.

Пример POST запроса для категории:

{
  "description_category_id": 200000933,
  "language": "DEFAULT",
  "type_id": 93080
}

В запросе нам необходимо передать ID категории, для которой мы хотим получить атрибуты.

Ответ API:

{
  "result": [
    {
      "id": 31,
      "attribute_complex_id": 0,
      "name": "Бренд в одежде и обуви",
      "description": "Укажите наименование бренда, под которым произведён товар. Если товар не имеет бренда, используйте значение \"Нет бренда\"",
      "type": "string",
      "is_collection": false,
      "is_required": true,
      "is_aspect": false,
      "max_value_count": 0,
      "group_name": "",
      "group_id": 0,
      "dictionary_id": 28732849,
      "category_dependent": true
    }
  ]
}

Описание атрибутов

id — Уникальный идентификатор атрибута. Это числовой код, который однозначно определяет конкретный атрибут в API Ozon

Например: Для атрибута "Бренд в одежде и обуви" ID = 31. Используется для обращения к атрибуту в запросах, таких как заполнение карточки товара или получение значений атрибута.

Если вы хотите обновить атрибут "Бренд" в карточке товара, в запросе на обновление товара необходимо указать:

{
  "attribute_id": 31,
  "value": "Adidas"
}

name — Название атрибута. Это понятное для пользователя название. Например, "Бренд в одежде и обуви" позволяет определить, что это поле отвечает за указание бренда. Пример: Название "Материал" ясно указывает, что необходимо заполнить материал товара, например, для категории "Одежда" — "Хлопок".

description — Описание атрибута и правила его заполнения. Важная информация для правильного заполнения поля. Например: Для "Бренд в одежде и обуви": "Укажите наименование бренда, под которым произведён товар. Если товар не имеет бренда, используйте значение 'Нет бренда'."

type — Тип значения атрибута. Указывает формат данных, которые можно вводить:

string — текстовое поле. Например, для бренда: "Nike".
dictionary — предопределённые значения, такие как цвет ("Красный", "Синий").
numeric — числа, например, "Объём памяти: 128 ГБ".
boolean — булевое значение (true/false), например: "Наличие чехла: true".

is_collection — Может ли атрибут содержать несколько значений.Определяет, можно ли указать несколько вариантов для одного товара. Если true, то атрибут поддерживает множественное заполнение. Например, товар может быть доступен в нескольких размерах: "Размеры: S, M, L".

is_required — Обязательность заполнения. Указывает, должен ли быть атрибут обязательно заполнен. Если true, карточка товара не будет создана без заполнения этого поля. Пример: Для "Бренд в одежде и обуви" это поле обязательное. Если его не заполнить, API вернёт ошибку.

is_aspect — Важность для фильтрации. Показывает, используется ли атрибут в качестве фильтра для покупателей. Например: "Цвет" и "Размер" в одежде важны для фильтрации на сайте Ozon, чтобы покупатель мог найти товар нужного цвета и размера.

max_value_count — Максимальное количество значений. Указывает, сколько значений можно указать для одного товара. Если 0, то ограничений нет. Если, например, значение 1, можно указать только одно значение, например, один бренд.

dictionary_id — Уникальный идентификатор справочника. Используется, если атрибут опирается на справочник с заранее заданными значениями. Например: Для "Цвета" справочник может содержать значения: "Красный", "Синий", "Зелёный".

Если атрибут использует справочник (тип dictionary), например, "Цвет", то значения должны соответствовать предопределённым в справочнике. Получить доступные варианты можно через GetAttributeValues. Более подробно мы опишет это ниже.

category_dependent — Зависимость от категории. Показывает, влияет ли категория на набор значений или обязательность атрибута.Например, атрибут "Материал" обязателен для одежды, но не используется для электроники.

Правильное заполнение характеристик критично для успешного отображения товара на маркетплейсе. Например: is_required атрибуты обязательны — без их заполнения товар не будет опубликован. Справочные значения помогают унифицировать данные и упрощают поиск товаров покупателями. Категорийно-зависимые атрибуты обеспечивают точность заполнения для каждой группы товаров, например, разные списки допустимых материалов для одежды и мебели.

Получение значений справочника.

Если атрибут использует справочник (например, "Цвет"), необходимо запросить его возможные значения. Для этого применяется метод https://docs.ozon.ru/api/seller/#operation/DescriptionCategoryAPI_GetAttributeValues, который позволяет получить доступные варианты.

Пример POST запроса для получения значений атрибута:

{
  "attribute_id": 85,
  "description_category_id": 17054869,
  "language": "DEFAULT",
  "last_value_id": 0,
  "limit": 100,
  "type_id": 97311
}

Параметры запроса:

attribute_id — уникальный идентификатор атрибута. В данном случае используется ID = 85.

description_category_id — ID категории, к которой относится атрибут (здесь 17054869).

language — язык, на котором будут возвращены значения (например, "DEFAULT").

last_value_id — позволяет постранично получать значения справочника. Для первой страницы используется 0.

limit — количество записей на страницу (в данном случае 100).

type_id — идентификатор типа атрибута (97311).

Ответ API:

{
  "result": [
    {
      "id": 5055881,
      "value": "Sunshine",
      "info": "",
      "picture": "https://cdn1.ozone.ru/s3/multimedia-i/6010930878.jpg"
    },
    {
      "id": 5056737,
      "value": "Essence",
      "info": "Красота и здоровье",
      "picture": "https://cdn1.ozone.ru/s3/multimedia-v/6088253599.jpg"
    }
  ],
  "has_next": true
}

Описание полей ответа:

id — уникальный идентификатор значения в справочнике.

value — текстовое значение атрибута. Например, "Sunshine" или "Essence".

info — дополнительная информация о значении, например, "Красота и здоровье".

picture — ссылка на изображение, если оно связано со значением атрибута (например, цветовая палитра).

has_next — указывает, есть ли следующая страница значений. Если true, нужно выполнить ещё один запрос, увеличив last_value_id.

Важно! Значение атрибута должно строго соответствовать одному из предложенных вариантов.

Например: Если атрибут "Цвет" содержит значение "Sunshine", в карточке товара следует указывать именно это слово. Неправильное значение, например, "Солнечный", будет отклонено платформой Ozon.

Пример использования в запросе на создание или изменение товара:

Если вы добавляете товар с атрибутом "Цвет", значения можно указать следующим образом:

{
  "attribute_id": 85,
  "value": "Sunshine"
}

Если атрибут поддерживает несколько значений (например, товар доступен в нескольких цветах), перечислите их в массиве:

{
  "attribute_id": 85,
  "value": ["Sunshine", "Essence"]
}

Создание карточки товара.

Когда у вас есть все необходимые данные (категория, атрибуты, значения справочников), можно создать карточку товара, используя метод https://docs.ozon.ru/api/seller/#operation/ProductAPI_ImportProductsV3. Этот метод позволяет передать полное описание товара, включая его параметры, изображения и цены.

Пример создания карточки:

{
  "items": [
    {
      "attributes": [
        {
          "complex_id": 0,
          "id": 5076,
          "values": [
            {
              "dictionary_value_id": 971082156,
              "value": "Стойка для акустической системы"
            }
          ]
        },
        {
          "complex_id": 0,
          "id": 9048,
          "values": [
            {
              "value": "Комплект защитных плёнок для X3 NFC. Темный хлопок"
            }
          ]
        },
        {
          "complex_id": 0,
          "id": 8229,
          "values": [
            {
              "dictionary_value_id": 95911,
              "value": "Комплект защитных плёнок для X3 NFC. Темный хлопок"
            }
          ]
        },
        {
          "complex_id": 0,
          "id": 85,
          "values": [
            {
              "dictionary_value_id": 5060050,
              "value": "Samsung"
            }
          ]
        },
        {
          "complex_id": 0,
          "id": 10096,
          "values": [
            {
              "dictionary_value_id": 61576,
              "value": "серый"
            }
          ]
        }
      ],
      "barcode": "112772873170",
      "description_category_id": 17028922,
      "new_description_category_id": 0,
      "color_image": "",
      "complex_attributes": [],
      "currency_code": "RUB",
      "depth": 10,
      "dimension_unit": "mm",
      "height": 250,
      "images": [],
      "images360": [],
      "name": "Комплект защитных плёнок для X3 NFC. Темный хлопок",
      "offer_id": "143210608",
      "old_price": "1100",
      "pdf_list": [],
      "price": "1000",
      "primary_image": "",
      "vat": "0.1",
      "weight": 100,
      "weight_unit": "g",
      "width": 150
    }
  ]
}

Пояснение параметров запроса:

attributes — массив характеристик товара. Каждая характеристика задаётся через:

id — идентификатор атрибута.

values — массив значений атрибута, включая текстовое значение (value) и/или идентификатор из справочника (dictionary_value_id). Пример: атрибут "Цвет" с id = 10096 принимает значение "серый" через dictionary_value_id = 61576.

barcode — штрихкод товара. Уникален для каждого товара.

description_category_id — ID категории, в которой создаётся товар.

dimension_unit — единицы измерения габаритов товара (например, "mm").

images — массив ссылок на изображения товара. Поддерживаются URL, ведущие на изображения в формате JPG или PNG.

name — название товара, понятное пользователю (например, "Комплект защитных плёнок для X3 NFC. Темный хлопок").

offer_id — уникальный идентификатор товара, создаваемый продавцом.

price — текущая цена товара.

old_price — цена до скидки (если товар участвует в акции).

vat — ставка НДС. Указывается в формате десятичной дроби, например, 0.1 (10%).

weight и weight_unit — вес товара и его единицы измерения (например, "g" для граммов).

width, height, depth — габариты товара в указанных единицах измерения.

Ответ API:

{
  "result": {
    "task_id": 172549793
  }
}

task_id — идентификатор задачи, с помощью которого можно отслеживать статус обработки карточки товара. То есть при отправке запроса на создание или изменения товара вы не получите сразу ответ, а получите id созданной задачи. А затем уже надо проверять статус этой задачи чтобы узнать результат запроса.

Проверка статуса загрузки товаров.

После отправки данных о товаре в метод ProductAPI_ImportProductsV3, необходимо проверить статус обработки задачи. Для этого используется метод https://docs.ozon.ru/api/seller/#operation/ProductAPI_GetImportProductsInfo.

Пример запроса:

{
  "task_id": 172549793
}

Ответ API:

{
	"result": {
		"items": [
			{
				"offer_id": "143210608",
				"product_id": 137285792,
				"status": "imported",
				"errors": []
			}
		],
		"total": 1
	}
}

Пояснения:

task_id — идентификатор задачи, полученный после создания карточки товара.
status:
- success — карточка успешно создана.
- error — возникли ошибки (подробнее в разделе errors).
- in_progress — задача находится в обработке.
errors — массив ошибок, если они возникли.

Если задача завершилась с ошибками, необходимо:

Изучить массив errors.
Исправить данные и повторить загрузку.

Стандартные и сложные атрибуты

Помимо стандартных категориальных атрибутов, Ozon поддерживает комплексные атрибуты, которые позволяют объединять данные о товарах, имеющих вариации или дополнительные связанные параметры. Комплексные атрибуты передаются с использованием параметра complex_id. Этот идентификатор группирует атрибуты, относящиеся к одному набору данных. Например атрибут Адрес может быть комплексным и состоять из Города, Улицы и номера дома.

Пример использования комплексных атрибутов:

Рассмотрим ситуацию, когда для товара нужно указать два типа данных: названия видеороликов и ссылки на них. Для этого используется единый complex_id, который объединяет данные в логический блок.

[
  {
    "complex_id": 100001,
    "id": 21837,
    "values": [
      {
        "value": "videoName_1"
      },
      {
        "value": "videoName_2"
      }
    ]
  },
  {
    "complex_id": 100001,
    "id": 21841,
    "values": [
      {
        "value": "https://www.youtube.com/watch?v=ZwM0iBn03dY"
      },
      {
        "value": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      }
    ]
  }
]

Пояснение:

complex_id — идентификатор, объединяющий связанные атрибуты. В данном примере он равен 100001, что связывает названия видеороликов и их ссылки.

id — уникальный идентификатор каждого атрибута:

21837 — атрибут для названий видео.

21841 — атрибут для ссылок на видео.

values — массив значений, передаваемых для каждого атрибута.

Для атрибута с id: 21837 передаются текстовые значения, такие как videoName_1 и videoName_2.

Для атрибута с id: 21841 передаются ссылки на видеоролики: https://www.youtube.com/watch?v=ZwM0iBn03dY и https://www.youtube.com/watch?v=dQw4w9WgXcQ.

Пример с вариациями товара. Для товара с различными размерами можно указать их через комплексный атрибут:

[
  {
    "complex_id": 200002,
    "id": 10096,
    "values": [
      {
        "value": "S"
      },
      {
        "value": "M"
      },
      {
        "value": "L"
      }
    ]
  },
  {
    "complex_id": 200002,
    "id": 8229,
    "values": [
      {
        "dictionary_value_id": 95911,
        "value": "Синий"
      }
    ]
  }
]

Пояснение:

complex_id: 200002 связывает размеры и цвета товара.

id: 10096 — атрибут, указывающий размеры (например, "S", "M", "L").

id: 8229 — атрибут для указания цвета, который передаётся как значение справочника (dictionary_value_id: 95911, соответствующее "Синий").

Зачем использовать комплексные атрибуты?

Группировка данных. Они позволяют объединить связанные параметры товара, такие как размеры, цвета, или мультимедийные данные.

Повышение точности. Связанные данные остаются структурированными, что упрощает их обработку на платформе.

Поддержка вариативности. Удобно для описания товаров с вариациями (например, одежда с разными цветами и размерами).

Использование комплексных атрибутов делает описание товара более точным и позволяет улучшить представление продукта на площадке.

Заключение

Интеграция с Ozon через Ozon Seller API может показаться сложной на первый взгляд, но если действовать пошагово, как описано в статье, процесс значительно упрощается:

Получаем ID категории.
Узнаём обязательные атрибуты для этой категории.
Получаем значения справочников для атрибутов.
Создаём карточку товара и загружаем изображения.

Следуя этим шагам, вы сможете автоматизировать процесс загрузки товаров на маркетплейс и избавитесь от рутинной работы.

Выгрузка карточек товаров на Озон через API