/yandex-direct

Фиды и товарные объявления

Читайте этот справочник при добавлении или обновлении каталога, создании товарной рекламы, изменении отбора товаров и разборе отсутствия показов после создания товарных объявлений. Сначала определите, что меняется:

В ЕПК FeedId и FeedFilterConditions принадлежат товарному объявлению. Не записывайте их в UnifiedAdGroup. Старые SmartAdGroup и DynamicTextFeedAdGroup устроены иначе; правила этих форматов не заменяют механику ЕПК. shopping.py работает с ShoppingAd. Объявления каталога ListingAd читает ads.py; для них доступна привязка дополнений через extensions.py bind, а создание и изменение содержимого пока требуют интерфейса.

Фиды в библиотеке

Команды запускаются из каталога скилла. Примеры используют условные логины, ID и адреса; подставляйте данные выбранного кабинета.

uv run scripts/feeds.py list --account example --no-cache
uv run scripts/feeds.py get --account example --feed 123 --no-cache --json
uv run scripts/feeds.py add --account example --name 'Каталог товаров' \
  --business-type RETAIL --url https://example.com/catalog.xml
uv run scripts/feeds.py add --account example --name 'Каталог из файла' \
  --business-type RETAIL --file catalog.xml
uv run scripts/feeds.py update --account example --feed 123 \
  --url https://example.com/catalog-new.xml --remove-utm-tags YES
uv run scripts/feeds.py delete --account example --feed 123

Без --apply изменение остаётся планом; флаг выполняет уже порученную запись. Покажите содержимое «было → станет» и затрагиваемые кампании: обновление общего фида может затронуть несколько кампаний. CampaignIds из Feeds.get может быть неполным: при проверке поле оказалось пустым даже у фида действующего товарного объявления. Для ЕПК прочитайте ShoppingAd и ListingAd через ads.py в кампаниях выбранного кабинета и сопоставьте FeedId; список кампаний получает campaigns.py. При ограниченной проверке назовите её охват, не утверждайте, что других привязок нет. Удаление применимо к неиспользуемому фиду; архивирование кампании само по себе не доказывает, что фид свободен. SourceType и BusinessType после создания не меняются. Для другого типа источника создайте новый фид. Значение RETAIL в примере подходит розничному каталогу; при копировании существующего фида сохраняйте его фактический тип бизнеса.

Команда принимает публичную ссылку либо локальный файл. Для защищённого логином и паролем источника используйте интерфейс Директа. --remove-utm-tags доступен только у URL-фида. Файл передаётся целиком в base64; лимит 50 МБ относится ко всему запросу, поэтому доступный размер исходного файла меньше. В плане показываются размер и SHA-256. API не возвращает содержимое файла: проверка имени и статуса не является побайтовой проверкой загрузки.

Обработка каталога

Успех Feeds.add/update подтверждает сохранение настроек, а обработка идёт отдельно. Повторно выполните uv run scripts/feeds.py get --account example --feed 123 --no-cache:

До подготовки объявления получите FilterSchema и TitleAndTextSources: они определяют доступные поля отбора и источники заголовка/текста. Не придумывайте эти поля по названию сайта. При нулевом числе товаров проверьте доступность каталога, формат и содержимое. Не обещайте показы только потому, что фид сохранён или обработан.

Товарное объявление

В группе допускается одно неархивное ShoppingAd. Сначала прочитайте группу и существующие объявления; для новой кампании применяйте обычный порядок создания, выбора мест показа и управления бюджетом. Фид и формат ShoppingAd не ограничивают кампанию товарной галереей: до создания отдельно выберите места, а для «только галереи» используйте явный набор настроек из справочника. Добавление объявления в существующую кампанию не меняет её места показа.

uv run scripts/shopping.py get --account example --ad 789 --no-cache --json
uv run scripts/shopping.py add --account example --group 456 --feed 123 \
  --default-text 'Подбор оборудования. Доставка.'
uv run scripts/shopping.py update --account example --ad 789 \
  --default-text 'Подбор оборудования. Доставка и самовывоз.'

При создании требуется один текст по умолчанию. Он должен подходить всем выбранным товарам и соответствовать реальным условиям продавца. Источники задаются повторяемыми --title-source и --text-source; допустимые имена возьмите из TitleAndTextSources обработанного фида. Непереданные при правке поля сохраняются. Явно переданный список заменяется целиком.

Быстрые ссылки и уточнения привязывайте к ID объявления через extensions.py bind. Для нового объявления сначала выполните shopping.py add, затем используйте полученный ID:

uv run scripts/extensions.py --account example bind --ad 789 \
  --sitelink-set 102 --callout-id 200 --callout-id 202

Создание наборов, замена и снятие привязок, проверка «до/после» — в EXTENSIONS.md. Эта же команда меняет дополнения существующего ListingAd; фид, отбор товаров и тексты объявления она сохраняет.

Сохранение объявления не означает запуск показов или одобрение модерацией. Прочитайте его фактические State, Status и FeedProcessingStatus: UNPROCESSED — обработка ещё не закончена, PROCESSED — закончена, EMPTY_RESULT — по отбору не получились товары. Для проверки содержания покажите товары и страницы, соответствующие фильтрам; точный вид автоматически собранных карточек проверьте в предпросмотре Директа.

Генерация товарных объявлений и первые показы

Предупреждайте пользователя при создании: генерация товарных объявлений может занимать до трёх дней. Такой срок указала поддержка Яндекс Директа в ответе, предоставленном пользователем 20.09.2026. Это ориентир для ожидания, а не гарантия начала показов к определённому часу.

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

Если явных препятствий нет и объявление создано недавно, объясните возможную задержку и предложите повторно проверить статусы и статистику после генерации. Если поддержка уже подтвердила её недавнее завершение, дождитесь накопления статистики: отсчитывать ещё три дня на генерацию не нужно. Не увеличивайте бюджет и ставки только из-за отсутствия первых показов: для этого нужна отдельная причина. Если спустя три дня показы не появились, продолжите диагностику и при необходимости предложите обратиться в поддержку с временем создания и актуальными статусами.

Фильтры товаров

--filters filters.json принимает JSON-массив правил. Например, отобрать две категории и товары дороже указанной цены:

[
  {"Operand": "categoryId", "Operator": "EQUALS_ANY", "Arguments": ["10", "20"]},
  {"Operand": "price", "Operator": "GREATER_THAN", "Arguments": ["1000"]}
]

Это пример полей для товарного каталога; сверяйте их с FilterSchema. Между правилами действует И; EQUALS_ANY допускает любое из перечисленных значений. Аргументы записываются строками, включая числа. До 30 правил и 65 КБ JSON; допустимые операторы и число аргументов зависят от поля фида. Для диапазона используется IN_RANGE, например Arguments: ["1000-5000"].

uv run scripts/shopping.py update --account example --ad 789 --filters filters.json
uv run scripts/shopping.py update --account example --ad 789 --clear-filters

Файл заменяет весь отбор. Для добавления условия сначала прочитайте текущие правила и включите сохраняемые в итоговый файл. Снятие фильтров открывает отбор по всему фиду: явно объясните расширение пользователю. Перед изменением покажите правила до и после, после — перечитайте их и проверьте результат обработки. Если условия дали пустую выборку, не считайте задачу выполненной только по успешному ответу API.

В API при Ads.add фильтры и источники текста передаются массивами; при update/get — объектом {"Items": [...]} либо null. Команда выполняет это преобразование. Пропуск поля при обновлении означает «сохранить», null — очистить. DefaultTexts остаётся массивом и при частичной правке ShoppingAd может быть опущен.

Замена фида

FeedId отсутствует в Ads.update. Для замены подготовьте новое объявление с нужным фидом, сохраняя подходящие настройки. Учитывайте предел одного неархивного товарного объявления в группе: заранее согласуйте замену в той же группе или создание отдельной группы. Покажите старое и новое объявление, фильтры и источники текста. Архивация старого и запуск нового — отдельные изменения; не останавливайте работающую рекламу только ради подготовки копии.

Справка: Feeds, требования к фиду, Ads.add, Ads.update, правила отбора.