Вызов методов

Запросы к API Яндекс Маркета передаются по протоколу HTTPS, таймаут — 10 секунд, Keep-Alive не поддерживается.

<http_method> https://api.partner.market.yandex.ru/<version>/<resource>.<format>?<query_parameters>

Где:

• <http_method> ― DELETE, GET, POST или PUT.

• <version> ― версия конкретного метода (v1, v2, v3, ...).

  • Версии разных методов независимы.

  • Актуальная версия указана на странице этого метода.

  • Версия указывается в пути URL и является обязательной.

    Обязательно указывайте версию, если не делали этого раньше

    Скоро мы отключим возможность работать с запросами без указания версии.

• <resource> ― URL ресурса, над которым выполняется действие. Названия ресурсов приведены в описании соответствующих методов.

  Здесь передаются параметры пути (path parameters) — данные, которые отличаются в зависимости от магазина или кабинета.

  Пример

  https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}
  

  /{campaignId} — параметр пути, где вы указываете свой идентификатор кампании.

• <format> ― это необязательная часть запроса, которая влияет на способ представления ответа. Формат ответа может быть указан в HTTP-заголовке Accept. Данные передаются в формате JSON. В описании каждого метода приведены примеры запросов и ответов.

• <query_parameters> ― обязательные и необязательные параметры запроса.

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

  Параметры запроса отделяются от URL ресурса вопросительным знаком, а между парами «ключ-значение» используется амперсанд (&).

  Пример

  https://api.partner.market.yandex.ru/v2/reports/shows-sales/generate?format=CSV
  

  ?format=CSV — параметр запроса.

Для продавцов Market Yandex Go: также прочтите инструкцию.

Если произошла ошибка, прекращается обработка запроса и возвращается информация о ней. Типы ошибок и что с ними делать

Как работает версионирование методов

Версия относится к конкретному методу. Разные методы могут иметь разные актуальные версии (например, один — v1, другой — v3).

Примеры одного и того же метода в разных версиях

GET https://api.partner.market.yandex.ru/v1/campaigns
GET https://api.partner.market.yandex.ru/v2/campaigns

Здесь v1 и v2 — версии одного и того же метода .../campaigns. Они могут отличаться составом полей, правилами валидации и доступными параметрами.

Как выбрать и зафиксировать версию

• Откройте страницу нужного метода в документации — там указана актуальная версия и статус предыдущих.
• Фиксируйте конкретную версию в клиенте и URL (не используйте «последнюю по умолчанию»).
• Отслеживайте объявления о новых версиях и планах вывода старых из эксплуатации на странице метода.

Миграция между версиями

1. Изучите изменения на странице метода (что добавлено/изменено/удалено).
2. Обновите схему запросов/ответов и параметры под новую версию.
3. Протестируйте свои изменения.
4. Переключите версию в URL на новую.
5. Мониторьте ошибки и метрики; при необходимости временно вернитесь на прежнюю версию.

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

• Что будет, если указать несуществующую версию? — Вернётся ошибка 404 Not Found. Указывайте строчную букву v, заглавная V так же приведёт к ошибке 404.
• Где посмотреть, какая версия используется сейчас? — В URL вашего запроса: сегмент v1/v2/v3 в пути.
• Меняется ли версия у всех методов разом? — Нет. Каждый метод версионируется независимо.