Google Ads API связал промокоды с POS: что изменилось — PIUN MARKETING

Google Ads API получил отдельный слой данных для промоакций, которые погашаются вне рекламной системы — например, в кассе магазина или в партнёрской POS-платформе. В release notes версии 26.1 от 28 октября Google описал поле PromotionAsset.external_redeem_info, тип промокода, источник кода и идентификатор акции во внешней системе.

Это обновление не превращает любой промокод из объявления в автоматически измеряемую офлайн-конверсию. Оно предназначено для аккаунтов, где уже существует поддерживаемая интеграция погашения промоакций. Главная ценность — связать рекламный asset с записью в партнёрской системе так, чтобы команда могла однозначно сопоставить настройки акции, проверить формат идентификатора и построить аудит через Google Ads Query Language.

Для бизнеса в Казахстане практический сценарий возможен у сетевого ритейла, ресторанов, сервисных компаний и омниканальных магазинов, которые выдают код в рекламе, а принимают его в кассе или собственной CRM. Но Google не публикует отдельный список доступности функции для Казахстана. Поэтому сначала проверяют наличие интеграции и требования конкретного аккаунта, а уже потом меняют генератор assets.

В статье:

что добавил Google Ads API v26.1;
из каких полей состоит external_redeem_info;
почему данные задаются только при создании;
как проверить assets через GAQL;
как безопасно внедрить изменение;
что учитывать бизнесу Казахстана.

Что именно добавил Google Ads API v26.1

В PromotionAsset появилось неизменяемое поле external_redeem_info. Оно хранит сведения о внешнем погашении акции и состоит из трёх логических частей:

code_type — одноразовый или многоразовый промокод;
code_source — код загружен рекламодателем либо сгенерирован Google;
partner_promotion_id — идентификатор той же акции в системе партнёра.

Google также добавил ошибку AssetError.PARTNER_PROMOTION_ID_TYPE_INCOMPATIBLE. Она возникает, если интеграция ожидает числовой идентификатор, а API получает строку, или наоборот. Это важная деталь: тип ID определяется не удобством разработчика, а контрактом подключённой системы погашения.

В официальной документации есть разница в маркировке версии. Release notes относят добавление к v26.1, а руководство по assets формулирует доступность как «starting in v26». Для production-интеграции безопаснее ориентироваться на актуальные proto-файлы, версию клиентской библиотеки и фактическую схему ответа конкретного аккаунта, а не только на текст одного раздела справки.

Какую задачу решает внешний идентификатор акции

Обычный promotion asset сообщает пользователю скидку, товар или услугу, период действия, код и условия. Но у рекламной платформы и кассовой системы могут быть разные идентификаторы одной и той же акции. Если связь хранится только в таблице маркетолога, аудит быстро ломается: код переименовали, asset пересоздали, а POS продолжает использовать старый внутренний ID.

partner_promotion_id фиксирует ключ внешней записи непосредственно в структуре рекламного asset. Это помогает:

сопоставлять рекламную настройку и акцию в POS без ручного справочника;
разделять одноразовые и многоразовые коды ещё на этапе создания;
контролировать источник кода — рекламодатель или Google;
находить assets с отсутствующими либо несовместимыми данными;
строить технический журнал изменений вокруг создания новой акции.

При этом поле само по себе не доказывает продажу и не заменяет импорт конверсий. Оно описывает интеграционную связь. Факт погашения, выручка, возвраты и дедупликация по-прежнему должны обрабатываться системой, которая принимает код и передаёт согласованные данные дальше.

Как устроены типы кода и partner_promotion_id

Для code_type предусмотрены два рабочих значения. SINGLE_USE_PROMOTION_CODE означает код, который должен погашаться один раз. MULTI_USE_PROMOTION_CODE — код, допускающий повторное применение по правилам акции. Выбирать значение нужно по реальной логике кассы, а не по желаемому рекламному сценарию.

code_source разделяет CUSTOMER_UPLOADED и GOOGLE_GENERATED. Когда код генерирует Google, partner_promotion_id обязателен. Он представлен как oneof: можно передать либо int_value, либо string_value, но не оба варианта одновременно. Для строкового ID документация указывает длину от 1 до 50 символов.

Пример: внутренняя система сети хранит акцию как число 48217. Тогда интеграция может ожидать int_value. Если в другом POS ключ выглядит как KZ-BF-2026-07, нужен string_value. Простое преобразование числа в строку не гарантирует совместимость: API сверяет вариант с требованиями подключённой интеграции.

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

Все вложенные поля external_redeem_info имеют режим immutable или create-only. Их можно задать при создании PromotionAsset, но попытка изменить или очистить их через update приводит к RequestError.IMMUTABLE_FIELD.

Из этого следует важное правило эксплуатации: ошибочный внешний ID нельзя «подправить» в существующем asset. Нужно создать новый корректный asset, привязать его на нужном уровне и только после проверки убрать старую связь. Массовое обновление существующих промоакций через update-маску здесь не подходит.

До создания стоит валидировать:

наличие интеграции погашения у аккаунта;
допустимый вариант partner ID — integer или string;
соответствие single-use или multi-use реальным правилам POS;
источник кодов и обязательность внешнего ID;
даты показа, даты погашения и условия акции;
уникальность технического ключа внутри собственного реестра.

Такой preflight дешевле, чем пересоздание assets после запуска, особенно если одна акция уже привязана к нескольким кампаниям или группам объявлений.

Как проверить данные через Google Ads Query Language

Все четыре конечных поля доступны для выборки, фильтрации и сортировки в отчёте по asset. Проверочный запрос может возвращать resource name, ID, название, цель промоакции, источник и тип кода, а также числовой или строковый partner ID.

Поскольку partner_promotion_id — это oneof, у конкретного asset заполнен только один вариант. Второй возвращается как null. Это удобно для автоматического контроля: система может помечать строку ошибочной, если заполнены оба значения, отсутствует ожидаемый вариант или тип не совпадает с настройкой партнёра.

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

Чек-лист безопасного внедрения

Практический rollout лучше провести на одной акции и одном аккаунте:

Проверить доступ. Уточнить, поддерживает ли аккаунт внешнее погашение и какой POS-партнёр подключён.
Зафиксировать контракт данных. Определить формат partner ID, тип кода, источник и правила уникальности.
Обновить клиент. Использовать версию библиотеки и proto, где поле доступно, затем прогнать запрос в тестовом окружении.
Создать новый asset. Передать external_redeem_info только после локальной валидации.
Прочитать asset обратно. Сверить все четыре конечных поля через GAQL.
Провести тестовое погашение. Проверить путь кода от объявления до POS и внутреннего отчёта.
Настроить журнал. Хранить resource name Google Ads, partner promotion ID, даты и версию интеграционного контракта.

Если API возвращает PARTNER_PROMOTION_ID_TYPE_INCOMPATIBLE, не стоит перебирать форматы на production. Нужно сверить требования интеграции и заново создать asset с правильным вариантом ID. Если возвращается IMMUTABLE_FIELD, значит код пытается обновить create-only данные вместо создания новой сущности.

Что остаётся обязательным для самого promotion asset

Новая интеграционная информация не отменяет правила показа промоакций. В поле promo code должен находиться именно код, а не телефон, описание товара или рекламная фраза. Для локальных промоакций Google рекомендует явно указывать срок действия, способ погашения и ограничения, а при наличии — ссылку на полные условия.

QR- и штрихкоды имеют отдельные ограничения по инвентарю: справка Google указывает, что они не показываются в Search, Shorts и In-stream video, а доступны на Maps. Поэтому выбор формата должен учитывать не только возможности POS, но и место, где пользователь увидит объявление.

Также важно различать рекламный promotion asset и промокредит Google Ads для оплаты рекламных расходов. Это разные механики. external_redeem_info относится к акции рекламодателя для клиента, а не к купону на баланс рекламного кабинета.

Что учитывать бизнесу Казахстана

Для казахстанского бизнеса обновление полезно не географией, а архитектурой омниканальной акции. Если сеть выдаёт коды через Google Ads, принимает их в физических точках и уже имеет совместимую систему погашения, единый partner ID уменьшает риск ручных расхождений.

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

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

Если бизнес использует обычный статический промокод без партнёрской интеграции, внедрять новый объект только ради отчётности не нужно. Сначала стоит наладить базовое измерение рекламных заявок и продаж. Команда PIUN Marketing помогает настроить ведение Google Рекламы, связать кампании с аналитикой и определить, где API-автоматизация действительно оправдана.