Получение информации о заполненности карточек магазина

Метод доступен для моделей: FBY, FBS, Экспресс и DBS.

Если вы используете API-Key-токен, для вызова метода необходим один из доступов в списке

Возвращает сведения о состоянии контента для заданных товаров:

  • создана ли карточка товара и в каком она статусе;
  • рейтинг карточки — на сколько процентов она заполнена;
  • переданные характеристики товаров;
  • есть ли ошибки или предупреждения, связанные с контентом;
  • рекомендации по заполнению карточки.
⚙️ Лимит: 600 запросов в минуту

Request

POST

https://api.partner.market.yandex.ru/v2/businesses/{businessId}/offer-cards

Path parameters

Name

Description

businessId*

Type: integer<int64>

Идентификатор кабинета. Чтобы его узнать, воспользуйтесь запросом GET v2/campaigns.

ℹ️ Что такое кабинет и магазин на Маркете

Min value: 1

Query parameters

Name

Description

limit

Type: integer<int32>

Количество значений на одной странице.

Min value: 1
Example: 20

page_token

Type: string

Идентификатор страницы c результатами.

Если параметр не указан, возвращается первая страница.

Рекомендуем передавать значение выходного параметра nextPageToken, полученное при последнем запросе.

Если задан page_token и в запросе есть параметры page и pageSize, они игнорируются.
Example: eyBuZXh0SWQ6IDIzNDIgfQ==

Body

application/json
{
    "offerIds": [
        "string"
    ],
    "cardStatuses": [
        "HAS_CARD_CAN_NOT_UPDATE"
    ],
    "categoryIds": [
        0
    ]
}

Name

Description

cardStatuses

Type: OfferCardStatusType[]

Фильтр по статусам карточек.

Что такое карточка товара
Статус карточки товара:

  • HAS_CARD_CAN_NOT_UPDATE — Карточка Маркета.
  • HAS_CARD_CAN_UPDATE — Можно дополнить.
  • HAS_CARD_CAN_UPDATE_ERRORS — Изменения не приняты.
  • HAS_CARD_CAN_UPDATE_PROCESSING — Изменения на проверке.
  • NO_CARD_NEED_CONTENT — Создайте карточку.
  • NO_CARD_MARKET_WILL_CREATE — Создаст Маркет.
  • NO_CARD_ERRORS — Не создана из-за ошибки.
  • NO_CARD_PROCESSING — Проверяем данные.
  • NO_CARD_ADD_TO_CAMPAIGN — Разместите товар в магазине.

Enum: HAS_CARD_CAN_NOT_UPDATE, HAS_CARD_CAN_UPDATE, HAS_CARD_CAN_UPDATE_ERRORS, HAS_CARD_CAN_UPDATE_PROCESSING, NO_CARD_NEED_CONTENT, NO_CARD_MARKET_WILL_CREATE, NO_CARD_ERRORS, NO_CARD_PROCESSING, NO_CARD_ADD_TO_CAMPAIGN

Min items: 1

Unique items  

categoryIds

Type: integer<int32>[]

Фильтр по категориям на Маркете.
Идентификатор категории на Маркете.

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

Список категорий Маркета можно получить с помощью запроса POST v2/categories/tree.

Min value (exclusive): 0

Min items: 1

Max items: 200

Unique items  

offerIds

Type: string[]

Идентификаторы товаров, информация о которых нужна.

⚠️ Не используйте это поле одновременно с фильтрами по статусам карточек, категориям, брендам или тегам. Если вы хотите воспользоваться фильтрами, оставьте поле пустым.
Ваш SKU — идентификатор товара в вашей системе.

Правила использования SKU:

  • У каждого товара SKU должен быть свой.

  • Уже заданный SKU нельзя освободить и использовать заново для другого товара. Каждый товар должен получать новый идентификатор, до того никогда не использовавшийся в вашем каталоге.

SKU товара можно изменить в кабинете продавца на Маркете. О том, как это сделать, читайте в Справке Маркета для продавцов.

Что такое SKU и как его назначать

Min length: 1

Max length: 255

Pattern: ^(?=.*\S.*)[^\x00-\x08\x0A-\x1f\x7f]{1,255}$

Min items: 1

Max items: 200

Unique items  

OfferCardStatusType

Статус карточки товара:

  • HAS_CARD_CAN_NOT_UPDATE — Карточка Маркета.
  • HAS_CARD_CAN_UPDATE — Можно дополнить.
  • HAS_CARD_CAN_UPDATE_ERRORS — Изменения не приняты.
  • HAS_CARD_CAN_UPDATE_PROCESSING — Изменения на проверке.
  • NO_CARD_NEED_CONTENT — Создайте карточку.
  • NO_CARD_MARKET_WILL_CREATE — Создаст Маркет.
  • NO_CARD_ERRORS — Не создана из-за ошибки.
  • NO_CARD_PROCESSING — Проверяем данные.
  • NO_CARD_ADD_TO_CAMPAIGN — Разместите товар в магазине.

Type

Description

OfferCardStatusType

Enum: HAS_CARD_CAN_NOT_UPDATE, HAS_CARD_CAN_UPDATE, HAS_CARD_CAN_UPDATE_ERRORS, HAS_CARD_CAN_UPDATE_PROCESSING, NO_CARD_NEED_CONTENT, NO_CARD_MARKET_WILL_CREATE, NO_CARD_ERRORS, NO_CARD_PROCESSING, NO_CARD_ADD_TO_CAMPAIGN

Responses

200 OK

Информация о карточках указанных товаров.

Body

application/json
{
    "status": "OK",
    "result": {
        "offerCards": [
            {
                "offerId": "string",
                "mapping": {
                    "marketSku": 0,
                    "marketSkuName": "string",
                    "marketModelId": 0,
                    "marketModelName": "string",
                    "marketCategoryId": 0,
                    "marketCategoryName": "string"
                },
                "parameterValues": [
                    {
                        "parameterId": 0,
                        "unitId": 0,
                        "valueId": 0,
                        "value": "string"
                    }
                ],
                "cardStatus": "HAS_CARD_CAN_NOT_UPDATE",
                "contentRating": 0,
                "averageContentRating": 0,
                "contentRatingStatus": "UPDATING",
                "recommendations": [
                    {
                        "type": "HAS_VIDEO",
                        "percent": 0,
                        "remainingRatingPoints": 0
                    }
                ],
                "groupId": "string",
                "errors": [
                    {
                        "message": "string",
                        "comment": "string"
                    }
                ],
                "warnings": [
                    {
                        "message": "string",
                        "comment": "string"
                    }
                ]
            }
        ],
        "paging": {
            "nextPageToken": "string"
        }
    }
}

Name

Description

status*

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR

result

Type: OfferCardsContentStatusDTO

Список товаров с информацией о состоянии карточек.

ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Type

Description

ApiResponseStatusType

Enum: OK, ERROR

OfferCardsContentStatusDTO

Список товаров с информацией о состоянии карточек.

Name

Description

offerCards*

Type: OfferCardDTO[]

Страница списка товаров с информацией о состоянии карточек.
Информация о состоянии карточки товара.

Если поле mapping отсутствует в ответе, Маркет еще не успел обработать информацию о товаре. Чтобы определить категорию такого товара, повторите запрос через несколько минут.

paging

Type: ForwardScrollingPagerDTO

Идентификатор следующей страницы.

OfferCardDTO

Информация о состоянии карточки товара.

Если поле mapping отсутствует в ответе, Маркет еще не успел обработать информацию о товаре. Чтобы определить категорию такого товара, повторите запрос через несколько минут.

Name

Description

offerId*

Type: string

Ваш SKU — идентификатор товара в вашей системе.

Правила использования SKU:

  • У каждого товара SKU должен быть свой.

  • Уже заданный SKU нельзя освободить и использовать заново для другого товара. Каждый товар должен получать новый идентификатор, до того никогда не использовавшийся в вашем каталоге.

SKU товара можно изменить в кабинете продавца на Маркете. О том, как это сделать, читайте в Справке Маркета для продавцов.

Что такое SKU и как его назначать

Min length: 1

Max length: 255

Pattern: ^(?=.*\S.*)[^\x00-\x08\x0A-\x1f\x7f]{1,255}$

averageContentRating

Type: integer<int32>

Средний рейтинг карточки у товаров той категории, которая указана в marketCategoryId.

cardStatus

Type: OfferCardStatusType

Статус карточки товара:

  • HAS_CARD_CAN_NOT_UPDATE — Карточка Маркета.
  • HAS_CARD_CAN_UPDATE — Можно дополнить.
  • HAS_CARD_CAN_UPDATE_ERRORS — Изменения не приняты.
  • HAS_CARD_CAN_UPDATE_PROCESSING — Изменения на проверке.
  • NO_CARD_NEED_CONTENT — Создайте карточку.
  • NO_CARD_MARKET_WILL_CREATE — Создаст Маркет.
  • NO_CARD_ERRORS — Не создана из-за ошибки.
  • NO_CARD_PROCESSING — Проверяем данные.
  • NO_CARD_ADD_TO_CAMPAIGN — Разместите товар в магазине.

Enum: HAS_CARD_CAN_NOT_UPDATE, HAS_CARD_CAN_UPDATE, HAS_CARD_CAN_UPDATE_ERRORS, HAS_CARD_CAN_UPDATE_PROCESSING, NO_CARD_NEED_CONTENT, NO_CARD_MARKET_WILL_CREATE, NO_CARD_ERRORS, NO_CARD_PROCESSING, NO_CARD_ADD_TO_CAMPAIGN

contentRating

Type: integer<int32>

Рейтинг карточки.

contentRatingStatus

Type: OfferCardContentStatusType

Статус вычисления рейтинга карточки и рекомендаций.

Enum: UPDATING, ACTUAL

errors

Type: OfferErrorDTO[]

Ошибки в контенте, препятствующие размещению товара на витрине.
Сообщение об ошибке, связанной с размещением товара.

Min items: 1

groupId

Type: string

Идентификатор группы товаров.

У товаров, которые объединены в одну группу, будет одинаковый идентификатор.

Как объединить товары на карточке

mapping

Type: GetMappingDTO

Основная информация о карточке товара.
Идентификатор карточки на Маркете. Показывает текущую привязку товара к карточке.

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

parameterValues

Type: ParameterValueDTO[]

Список характеристик с их значениями.
Значение характеристики.

Вы можете указывать несколько значений одной характеристики при условии, что:

  • Тип характеристики — ENUM.
  • В ответе на запрос POST v2/category/{categoryId}/parameters у данной характеристики поле multivalue имеет значение true.

Для этого в parameterValues передавайте каждое значение отдельно — несколько объектов с параметрами parameterId, valueId и value. Параметр parameterId должен быть одинаковым.

Min items: 1

recommendations

Type: OfferCardRecommendationDTO[]

Список рекомендаций к заполнению карточки.

Рекомендации Маркета помогают заполнять карточку так, чтобы покупателям было проще найти ваш товар и решиться на покупку.
Рекомендация по заполнению карточки товара.

Min items: 1

warnings

Type: OfferErrorDTO[]

Связанные с контентом предупреждения, не препятствующие размещению товара на витрине.
Сообщение об ошибке, связанной с размещением товара.

Min items: 1

ForwardScrollingPagerDTO

Идентификатор следующей страницы.

Name

Description

nextPageToken

Type: string

Идентификатор следующей страницы результатов.

OfferCardContentStatusType

Статус вычисления рейтинга карточки товара и рекомендаций:

  • UPDATING — рейтинг обновляется.
  • ACTUAL — рейтинг актуальный.

Type

Description

OfferCardContentStatusType

Enum: UPDATING, ACTUAL

OfferErrorDTO

Сообщение об ошибке, связанной с размещением товара.

Name

Description

comment

Type: string

Пояснение.

message

Type: string

Тип ошибки.

GetMappingDTO

Информация о товарах в каталоге.

Name

Description

marketCategoryId

Type: integer<int64>

Идентификатор категории на Маркете, в которую попал товар.

Может отсутствовать в ответе, если Маркет еще не определил категорию товара.

marketCategoryName

Type: string

Название категории карточки на Маркете.

Может отсутствовать в ответе, если Маркет еще не определил категорию товара.

marketModelId

⦸

Type: integer<int64>

Идентификатор модели на Маркете.

Может отсутствовать в ответе, если товар еще не привязан к карточке.

marketModelName

⦸

Type: string

Название модели на Маркете.

Может отсутствовать в ответе, если товар еще не привязан к карточке.

marketSku

Type: integer<int64>

Идентификатор карточки на Маркете.

Min value: 1

marketSkuName

Type: string

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

Может отсутствовать в ответе, если товар еще не привязан к карточке.

ParameterValueDTO

Значение характеристики.

Вы можете указывать несколько значений одной характеристики при условии, что:

  • Тип характеристики — ENUM.
  • В ответе на запрос POST v2/category/{categoryId}/parameters у данной характеристики поле multivalue имеет значение true.

Для этого в parameterValues передавайте каждое значение отдельно — несколько объектов с параметрами parameterId, valueId и value. Параметр parameterId должен быть одинаковым.

Name

Description

parameterId*

Type: integer<int64>

Идентификатор характеристики.

Min value: 1

unitId

Type: integer<int64>

Идентификатор единицы измерения. Если вы не передали параметр unitId, используется единица измерения по умолчанию.

value

Type: string

Значение.

Для характеристик типа ENUM передавайте вместе с valueId.

valueId

Type: integer<int64>

Идентификатор значения.

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

Передавайте вместе с value.

Только для характеристик типа ENUM.

OfferCardRecommendationDTO

Рекомендация по заполнению карточки товара.

Name

Description

type*

Type: OfferCardRecommendationType

Рекомендация по дополнению или замене контента. Не возвращается для карточек, которые заполнены Маркетом или содержат бывшие в употреблении товары.

Часть рекомендаций относятся к основным параметрам, которые есть у товаров любых категорий. Другие — к тем характеристикам, которые есть у товара потому, что он относится к определенной категории.

1. Рекомендации, относящиеся к основным параметрам

Каждая такая рекомендация относится к единственному параметру. Чтобы заполнить этот параметр, пользуйтесь запросом POST v2/businesses/{businessId}/offer-mappings/update.

Рекомендации по заполнению параметров в updateOfferMappings:

  • RECOGNIZED_VENDOR — напишите название производителя так, как его пишет сам производитель (параметр vendor).

  • PICTURE_COUNT — добавьте изображения (параметр pictures). Требования

    Для рекомендации приходит процент ее выполнения.

  • FIRST_PICTURE_SIZE— замените первое изображение более крупным (параметр pictures). Требования

  • TITLE_LENGTH — измените название (параметр name). Составьте название по схеме: тип + бренд или производитель + модель + особенности, если есть (размер, вес, цвет). Требования

  • DESCRIPTION_LENGTH — добавьте описание рекомендуемого размера (параметр description). Требования

  • AVERAGE_PICTURE_SIZE — замените все изображения на изображения высокого качества (параметр pictures). Требования

  • FIRST_VIDEO_LENGTH — добавьте первое видео рекомендуемой длины (параметр videos). Требования

  • FIRST_VIDEO_SIZE — замените первое видео на видео высокого качества (параметр videos). Требования

  • AVERAGE_VIDEO_SIZE — замените все видео на видео высокого качества (параметр videos). Требования

  • VIDEO_COUNT — добавьте хотя бы одно видео (параметр videos). Требования

    Для рекомендации приходит процент ее выполнения.

2. Рекомендации, относящиеся к характеристикам по категориям

Каждая такая рекомендация предполагает заполнение одной или нескольких характеристик. Чтобы узнать, какие именно характеристики нужно заполнить, воспользуйтесь запросом POST v2/category/{categoryId}/parameters. Например, если вы получили рекомендацию MAIN, нужно заполнить характеристики, имеющие MAIN в массиве recommendationTypes.

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

  • MAIN — заполните ключевые характеристики товара, которые используются в поиске и фильтрах.

    Для рекомендации приходит процент ее выполнения.

  • ADDITIONAL — заполните дополнительные характеристики товара.

    Для рекомендации приходит процент ее выполнения.

  • DISTINCTIVE — заполните характеристики, которыми отличаются друг от друга варианты товара.

    Для рекомендации приходит процент ее выполнения.

3. Устаревшие рекомендации

  • HAS_VIDEO.
  • FILTERABLE.
  • HAS_DESCRIPTION.
  • HAS_BARCODE.

Enum: HAS_VIDEO, RECOGNIZED_VENDOR, MAIN, ADDITIONAL, DISTINCTIVE, FILTERABLE, PICTURE_COUNT, HAS_DESCRIPTION, HAS_BARCODE, FIRST_PICTURE_SIZE, TITLE_LENGTH, DESCRIPTION_LENGTH, AVERAGE_PICTURE_SIZE, FIRST_VIDEO_SIZE, FIRST_VIDEO_LENGTH, AVERAGE_VIDEO_SIZE, VIDEO_COUNT

percent

Type: integer<int32>

Процент выполнения рекомендации.

Указывается для рекомендаций некоторых типов:

  • PICTURE_COUNT.
  • VIDEO_COUNT.
  • MAIN.
  • ADDITIONAL.
  • DISTINCTIVE.

Min value: 0

Max value (exclusive): 100

remainingRatingPoints

Type: integer<int32>

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

Min value: 1

Max value: 100

OfferCardRecommendationType

Рекомендация по дополнению или замене контента. Не возвращается для карточек, которые заполнены Маркетом или содержат бывшие в употреблении товары.

Часть рекомендаций относятся к основным параметрам, которые есть у товаров любых категорий. Другие — к тем характеристикам, которые есть у товара потому, что он относится к определенной категории.

1. Рекомендации, относящиеся к основным параметрам

Каждая такая рекомендация относится к единственному параметру. Чтобы заполнить этот параметр, пользуйтесь запросом POST v2/businesses/{businessId}/offer-mappings/update.

Рекомендации по заполнению параметров в updateOfferMappings:

  • RECOGNIZED_VENDOR — напишите название производителя так, как его пишет сам производитель (параметр vendor).

  • PICTURE_COUNT — добавьте изображения (параметр pictures). Требования

    Для рекомендации приходит процент ее выполнения.

  • FIRST_PICTURE_SIZE— замените первое изображение более крупным (параметр pictures). Требования

  • TITLE_LENGTH — измените название (параметр name). Составьте название по схеме: тип + бренд или производитель + модель + особенности, если есть (размер, вес, цвет). Требования

  • DESCRIPTION_LENGTH — добавьте описание рекомендуемого размера (параметр description). Требования

  • AVERAGE_PICTURE_SIZE — замените все изображения на изображения высокого качества (параметр pictures). Требования

  • FIRST_VIDEO_LENGTH — добавьте первое видео рекомендуемой длины (параметр videos). Требования

  • FIRST_VIDEO_SIZE — замените первое видео на видео высокого качества (параметр videos). Требования

  • AVERAGE_VIDEO_SIZE — замените все видео на видео высокого качества (параметр videos). Требования

  • VIDEO_COUNT — добавьте хотя бы одно видео (параметр videos). Требования

    Для рекомендации приходит процент ее выполнения.

2. Рекомендации, относящиеся к характеристикам по категориям

Каждая такая рекомендация предполагает заполнение одной или нескольких характеристик. Чтобы узнать, какие именно характеристики нужно заполнить, воспользуйтесь запросом POST v2/category/{categoryId}/parameters. Например, если вы получили рекомендацию MAIN, нужно заполнить характеристики, имеющие MAIN в массиве recommendationTypes.

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

  • MAIN — заполните ключевые характеристики товара, которые используются в поиске и фильтрах.

    Для рекомендации приходит процент ее выполнения.

  • ADDITIONAL — заполните дополнительные характеристики товара.

    Для рекомендации приходит процент ее выполнения.

  • DISTINCTIVE — заполните характеристики, которыми отличаются друг от друга варианты товара.

    Для рекомендации приходит процент ее выполнения.

3. Устаревшие рекомендации

  • HAS_VIDEO.
  • FILTERABLE.
  • HAS_DESCRIPTION.
  • HAS_BARCODE.

Type

Description

OfferCardRecommendationType

Enum: HAS_VIDEO, RECOGNIZED_VENDOR, MAIN, ADDITIONAL, DISTINCTIVE, FILTERABLE, PICTURE_COUNT, HAS_DESCRIPTION, HAS_BARCODE, FIRST_PICTURE_SIZE, TITLE_LENGTH, DESCRIPTION_LENGTH, AVERAGE_PICTURE_SIZE, FIRST_VIDEO_SIZE, FIRST_VIDEO_LENGTH, AVERAGE_VIDEO_SIZE, VIDEO_COUNT

400 Bad Request

Запрос содержит неправильные данные. Подробнее об ошибке

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

Min items: 1

status

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR

ApiErrorDTO

Общий формат ошибки.

Name

Description

code*

Type: string

Код ошибки.

message

Type: string

Описание ошибки.

401 Unauthorized

В запросе не указаны данные для авторизации. Подробнее об ошибке

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

Min items: 1

status

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR

403 Forbidden

Данные для авторизации неверны или доступ к ресурсу запрещен. Подробнее об ошибке

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

Min items: 1

status

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR

404 Not Found

Запрашиваемый ресурс не найден. Подробнее об ошибке

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

Min items: 1

status

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR

420 Method Failure

Превышено ограничение на доступ к ресурсу. Подробнее об ошибке

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

Min items: 1

status

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR

500 Internal Server Error

Внутренняя ошибка Маркета. Подробнее об ошибке

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

Список ошибок.
Общий формат ошибки.

Min items: 1

status

Type: ApiResponseStatusType

Тип ответа. Возможные значения:

  • OK — ошибок нет.
  • ERROR — при обработке запроса произошла ошибка.

Enum: OK, ERROR

No longer supported, please use an alternative and newer version.

Предыдущая
Получение файла со штрихкодами (FBY)
Следующая
Редактирование категорийных характеристик товара