Skip to main content
Status: live. Read-tools для стану фіду + draft → confirm write-tools (товари, залишки, промо, доставка, регіони, джерела даних, налаштування акаунта). Можна підключити кілька акаунтів.

Як це працює

Google Merchant Center інтеграція використовує Bring-Your-Own Service Account модель – не OAuth. Brama не є Google-застосунком: ти створюєш власний service account у Google Cloud, додаєш його як користувача у своєму Merchant Center і передаєш Brama його JSON-ключ. Креди зберігаються зашифрованими (ключі поза базою), на диск не пишуться, розшифровуються лише в пам’яті на час запиту. Після підключення AI-агент:
  • читає стан фіду – статуси товарів і акаунта, причини відхилень (read-only);
  • змінює дані – товари, залишки, промо, доставку, регіони – через draft → confirm флоу: жодна зміна не застосовується, поки ти не натиснеш Confirm у картці підтвердження.
Merchant API. Інтеграція працює на новому Google Merchant API. У формі підключення згадка про Content API for Shopping – legacy-формулювання; актуальний флоу нижче.

Підключення

1. Google Cloud – проєкт + Merchant API

  1. У Google Cloud Console створи (або обери) проєкт.
  2. APIs & Services → Library → Merchant API → Enable.

2. Service account + JSON-ключ

  1. IAM & Admin → Service Accounts → Create (GCP-ролі не потрібні – доступ дається через Merchant Center, не через IAM).
  2. У service account → Keys → Add key → Create new key → JSON → завантажиться *.json.
  3. Скопіюй email service account – поле client_email з JSON-ключа (виду name@project.iam.gserviceaccount.com).

3. Дай service account доступ у Merchant Center

Merchant Center → Settings → Users (Доступ до акаунта) → додай email service account (client_email з кроку 2) як користувача рівня Standard (Admin теж працює).

4. Підключити в Brama

app.brama.work → Integrations → Google Merchant Center → заповни: → Connect. Зберігається зашифрованим; Brama ніколи не показує креди назад (лише статус «active»).
Навіщо admin email. При підключенні Brama виконує одноразову developer-реєстрацію Google Cloud-проєкту твого service account у твоєму Merchant Center – автоматично. Google не дозволяє service account зареєструвати себе самостійно, тому потрібен людський admin-акаунт. Реєстрація – per-tenant, одноразова та ідемпотентна: повторне підключення безпечне. Admin email використовується лише для цього кроку – він не зберігається.

5. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI чи будь-який інший – див. Connect a client):
Які товари у мене відхилені в Merchant Center і чому?
Агент викличе brama_gmerchant_products_list / brama_gmerchant_issues_render_product і поверне статуси та причини відхилень.

Кілька акаунтів Merchant Center

До Brama можна підключити кілька акаунтів Merchant Center. brama_gmerchant_accounts_list показує їх усі. Коли підключено кілька, кожен тул Merchant Center приймає параметр merchant_id, тобто ID акаунта, з яким працювати. Якщо акаунт один, merchant_id можна не передавати. Якщо їх кілька, а merchant_id не вказано, тул поверне помилку зі списком акаунтів, щоб агент обрав потрібний, а не вгадував.

MCP tools (live)

Читання (read-only)

Усі тули нижче, крім accounts_list, приймають необов’язковий merchant_id (див. розділ «Кілька акаунтів Merchant Center» вище).

brama_gmerchant_accounts_list

Підключені до Brama акаунти Merchant Center: ID, назва і чи дозволено для кожного вносити зміни.Параметри: check (optional): якщо true, Brama ще й перевіряє в Google, чи працює збережений ключ кожного акаунта (повільніше).Use: перший виклик, коли підключено кілька акаунтів, щоб узяти merchant_id для решти тулів.

brama_gmerchant_accounts_get

Деталі підключеного Merchant Center акаунта: ID, назва бізнесу, часовий пояс, мова, ознаки test / adult.Параметри: merchant_id (optional).Use: підтвердити який акаунт підключено перед іншими діями.

brama_gmerchant_products_list

Сторінка товарів: назва, ціна, стан, наявність, статус схвалення, причини відхилення, shipping_label. Причини відхилення – це проблеми товару, які відхиляють або понижують його хоча б на одному каналі, кожна один раз у вигляді «опис (код)», наприклад Missing or incorrect shipping costs [shipping] (missing_shipping). З фільтрами status (approved / pending / disapproved), issue_code (наприклад missing_shipping) і channel Brama проходить каталог (до 2000 товарів) і повертає збіги з їх кількістю – «усі відхилені через missing_shipping» одним викликом.

brama_gmerchant_products_get

Один товар за повним ідентифікатором (accounts/{account}/products/{productId}): назва, доступність, condition, бренд, ціна, статус апруву по каналах та item-level issues.Google повертає кожну проблему окремо для кожного каналу. Brama зводить їх в один запис на код: severity (найгірша серед каналів: DISAPPROVED, DEMOTED або NOT_IMPACTED), reporting_contexts (канали, на яких проблема є), applicable_countries, а якщо канали оцінюють проблему по-різному, ще й severity_by_context.Параметри: ідентифікатор товару (required), merchant_id (optional).

brama_gmerchant_issues_list_aggregate_product_statuses

Зведення: скільки товарів active / pending / disapproved / expiring – у розрізі каналу (Shopping ads, free listings) і країни.Параметри: filter по каналу й країні (optional), наприклад reportingContext = "SHOPPING_ADS" AND country = "US"; page_size, page_token, merchant_id (optional).Буває, що Google віддає рядок без назви каналу. Такий рядок показано як REPORTING_CONTEXT_ENUM_UNSPECIFIED (<id рядка>), а в підсумку сказано, скільки таких рядків.Use: швидко побачити який канал чи країна має найбільше відхилень.

brama_gmerchant_issues_render_account

Issues рівня акаунта простою мовою: проблеми верифікації, порушення політик, відсутня бізнес-інформація + рекомендовані кроки.Параметри: language_code (наприклад uk-UA, за замовчуванням en-US), time_zone (наприклад Europe/Kyiv, за замовчуванням UTC), merchant_id – усі (optional).Поле content кожної проблеми – HTML-розмітка від Google, так само як у issues_render_product нижче.Use: діагностувати проблеми, що стосуються всього акаунта, а не окремого товару.

brama_gmerchant_issues_render_product

Issues одного товару простою мовою – часто з вказівкою на конкретний атрибут, який треба виправити.Параметри: ідентифікатор товару (required); language_code, time_zone, merchant_id (optional).Поле content кожної проблеми Brama передає як є: це HTML-розмітка, яку Google готує для показу в інтерфейсі (абзаци, списки, посилання на довідку). Агент читає її без перетворення; якщо показуєш текст людині поза чатом, рендери його як HTML. Коротка суть проблеми – у полях title та impact.Use: після того як список товарів виявив відхилений товар.

brama_gmerchant_shipping_get

Поточні налаштування доставки акаунта: кожна служба (активна чи ні, країни, валюта, транзит і обробка в днях, cutoff, групи тарифів зі shipping_label і ставками) та кожен склад – разом з etag, який потрібен для збереження. Обов’язковий перший крок перед будь-якою зміною доставки: візьми об’єкт звідси, зміни лише потрібне й передай назад у shipping_update_draft. Якщо налаштувань ще немає, каже про це й повертає etag порожнім рядком.

brama_gmerchant_datasources_list

Джерела даних акаунта: звідки беруться товари, залишки й акції. Для кожного – вид (primary / supplemental / inventory / promotions), спосіб подачі (API, файл, інтерфейс, автоматично), feed label, мова, країни, з якими джерелами воно пов’язане (правило primary в порядку пріоритету), файл і розклад для файлових.

brama_gmerchant_datasources_get

Одне джерело: правило за замовчуванням (з яких джерел беруться атрибути, перше в списку виграє) або primary, до яких прив’язане supplemental, а для файлових – результат останньої обробки (стан, час, кількість товарів, проблеми).

brama_gmerchant_promotions_list

Акції акаунта: id, назва, знижка, тип і код, країна, період, статус по каналах, коди проблем, джерело даних.

brama_gmerchant_promotions_get

Одна акція повністю – щоб відредагувати й повернути через promotions_upsert_draft.

brama_gmerchant_regions_list

Регіони: назва, зона (поштові індекси або геотаргети), чи придатний для тарифів доставки й регіональних залишків.

brama_gmerchant_regions_get

Один регіон повністю.

brama_gmerchant_inventory_local_list

Локальні (магазинні) залишки одного товару: ціна, акційна ціна, наявність, кількість, самовивіз по store code.

brama_gmerchant_inventory_regional_list

Регіональні залишки одного товару: ціна, акційна ціна, наявність по регіонах.

brama_gmerchant_return_policies_list

Політики повернення по країнах: термін, способи, стан товару, вартість зворотної доставки, обмін, строк відшкодування.

brama_gmerchant_return_policies_get

Одна політика повернення повністю, із сезонними винятками.

brama_gmerchant_business_info_get

Дані бізнесу: адреса, телефон і стан його перевірки, контакт служби підтримки. Їх відсутність – типова причина проблем на рівні акаунта.

brama_gmerchant_homepage_get

Сайт акаунта і чи підтверджено права на нього (claim). Без claim товари не показуються.

brama_gmerchant_programs_list

Програми (free listings, Shopping ads, local listings…): увімкнена / доступна, але вимкнена / недоступна, регіони, і що саме бракує для недоступних.

brama_gmerchant_automatic_improvements_get

Автоматичні покращення: чи дозволено Google самому виправляти ціну, наявність і стан товару за сторінкою, покращувати зображення й оцінки доставки.

brama_gmerchant_users_list

Користувачі акаунта з правами доступу. Лише читання.

brama_gmerchant_reports_search

Звіт мовою запитів Merchant Center: SELECT offer_id, title, clicks, impressions FROM product_performance_view WHERE date BETWEEN '2026-09-27' AND '2026-10-27' ORDER BY clicks DESC, порівняння цін з ринком (price_competitiveness_product_view), бестселери. Рядки – таблицею з обраними полями.

Зміни (draft → confirm)

Усі write-tools нижче – draft: вони готують зміну і показують у MCP клієнті картку підтвердження з Confirm / Cancel. Нічого не змінюється, поки ти не натиснеш Confirm. У клієнтах без картки (наприклад, Claude Code) зміну застосовує brama_gmerchant_apply_change, і лише після твоєї явної згоди в розмові. Прямого «apply без підтвердження» tool’а навмисно немає. Upsert замінює весь об’єкт значеннями, що ти передаєш – щоб змінити одне поле, спершу прочитай поточний об’єкт, зміни поле і відправ повний об’єкт назад.

brama_gmerchant_products_upsert_draft

Додати або оновити товар. Замінює товар цілком.

brama_gmerchant_products_delete_draft

Назавжди видалити товар. Незворотно.

brama_gmerchant_inventory_upsert_local_draft

Локальні (in-store) залишки товару – ціна й доступність по storeCode. Замінює запис цілком.

brama_gmerchant_inventory_delete_local_draft

Видалити локальний (in-store) запис залишків. Незворотно.

brama_gmerchant_inventory_upsert_regional_draft

Регіональні залишки – override ціни й доступності по region. Замінює запис цілком.

brama_gmerchant_inventory_delete_regional_draft

Видалити регіональний запис залишків. Незворотно.

brama_gmerchant_promotions_upsert_draft

Додати або оновити промо (знижка, безкоштовна доставка, спецоффер). Замінює промо цілком. Окремого delete немає – щоб зняти промо, вистав end ефективного періоду в минуле.

brama_gmerchant_shipping_service_upsert_draft

Додати або замінити одну службу доставки. Brama читає поточні налаштування, підставляє цю службу (за serviceName), решту служб, груп і складів не чіпає. Картка показує diff і покриття: скільки товарів отримають тариф.

brama_gmerchant_shipping_service_delete_draft

Прибрати одну службу доставки разом з її групами тарифів. Товари, які покривала лише вона, лишаться без тарифу.

brama_gmerchant_shipping_rate_group_upsert_draft

Додати або замінити одну групу тарифів у службі: applicableShippingLabels + ціна (flat, % від ціни, таблиця, carrier). Збіг за name або за набором міток. На картці – diff і покриття: скільки товарів мають ці мітки, скільки в службі без тарифу.

brama_gmerchant_shipping_warehouse_upsert_draft

Додати або замінити один склад (адреса, cutoff, дні обробки) за name.

brama_gmerchant_shipping_update_draft

Замінити налаштування доставки (служби доставки + склади) цілком – для однієї служби, групи чи складу є гранулярні тули вище. Якщо все ж потрібна повна заміна: спершу brama_gmerchant_shipping_get, зміни потрібну частину в об’єкті, який він повернув, і передай його назад з тим самим etag. Без etag чернетка відмовляє; якщо налаштування змінились після читання, Google відхиляє збереження – прочитай знову й повтори правку.

brama_gmerchant_datasources_fetch_draft

Перечитати файлове джерело зараз, не чекаючи розкладу – після виправлення фіду. Працює лише для файлів з URL або Google Sheet.

brama_gmerchant_datasources_create_supplemental_draft

Створити supplemental-джерело і одразу прив’язати його до primary. precedence: override (за замовчуванням) – значення supplemental переважають; fill – лише доповнює відсутнє. Brama читає поточне правило primary і зберігає наявні джерела, бо Google замінює правило цілком.

brama_gmerchant_products_upsert_supplemental_draft

Дописати кілька атрибутів наявному товару через supplemental-джерело: shippingLabel, shipping, вага й розміри, condition, customLabel0..4, productTypes, googleProductCategory. Ціна, наявність, назва й посилання не приймаються. Якщо вказане джерело не supplemental – відмова, primary-товар ніколи не перезаписується.

brama_gmerchant_return_policy_upsert_draft

Створити політику повернення (країни, посилання на політику, термін) або оновити наявну за name – змінюються лише передані поля.

brama_gmerchant_return_policy_delete_draft

Прибрати політику повернення. Країни без політики можуть втратити безкоштовні лістинги.

brama_gmerchant_business_info_update_draft

Оновити адресу, контакт служби підтримки або корейський реєстраційний номер. Телефон підтверджується в самому Merchant Center.

brama_gmerchant_homepage_update_draft

Змінити сайт акаунта. Після зміни сайт треба підтвердити і заявити права знову.

brama_gmerchant_homepage_claim_draft

Заявити права на сайт (overwrite – забрати в іншого акаунта) або зняти їх (unclaim). Сайт має бути вже підтверджений.

brama_gmerchant_programs_toggle_draft

Увімкнути чи вимкнути програму. Google вмикає лише коли вимоги виконані.

brama_gmerchant_automatic_improvements_update_draft

Змінити автоматичні покращення – лише передані частини.

brama_gmerchant_issues_trigger_action_draft

Виконати дію, яку Merchant Center пропонує на проблемі (наприклад, запит на повторну перевірку чи виправлення атрибута). action_context і потік беруться з результату issues_render_*.

brama_gmerchant_regions_upsert_draft

Додати або оновити регіон (іменована географічна зона для служб доставки / регіональних залишків). Update замінює регіон цілком.

brama_gmerchant_regions_delete_draft

Видалити регіон. Незворотно; будь-яка служба доставки чи регіональні залишки, що на нього посилаються, зламаються.

brama_gmerchant_regions_batch_upsert_draft

Додати / оновити кілька регіонів за раз (до 100) як одну підтверджену дію.

brama_gmerchant_regions_batch_delete_draft

Видалити кілька регіонів за раз (до 100) як одну підтверджену дію. Незворотно.

brama_gmerchant_apply_change

Застосовує зміну, яку підготував будь-який draft вище: товар, залишки, промо, доставку, регіони, джерела даних, налаштування акаунта. Призначений для клієнтів, які не показують картку підтвердження (наприклад, Claude Code). Агент викликає його лише після того, як показав тобі зміст draft і ти явно погодився в розмові; клієнт додатково питає дозволу перед кожним викликом.Параметри: confirm_token (required – з draft) + ті самі деталі, що показав draft: product_input, inventory, promotion, shipping_settings, region / regions / names, data_source_input, а для налаштувань акаунта (політика повернення, дані бізнесу, сайт, програми, автоматичні покращення) – change_input. Для видалення чи fetch – лише токен.Одноразовий, токен живе близько 5 хвилин: не повторювати після успіху. У клієнтах з карткою той самий крок виконує кнопка Confirm, а модель підтвердити сама не може.

Товари з Shopify: supplemental-джерело

У магазинів на Shopify товари потрапляють у Merchant Center через джерело застосунку Google & YouTube. API в це джерело не пише, а brama_gmerchant_products_upsert_draft працює лише з API-джерелами і замінює товар цілком. Тому атрибут, якого Shopify не передає (наприклад, shipping_label для групи тарифів або condition: used), додається через supplemental-джерело:
  1. brama_gmerchant_datasources_list – знайти primary-джерело застосунку.
  2. brama_gmerchant_datasources_create_supplemental_draft з link_to_primary – створити supplemental і прив’язати.
  3. brama_gmerchant_products_upsert_supplemental_draft – для кожного товару передати його offer_id, content_language, feed_label і лише потрібні атрибути.
  4. brama_gmerchant_shipping_rate_group_upsert_draft – у потрібній службі доставки додати групу тарифів з applicableShippingLabels = ця мітка; картка покаже, скільки товарів її отримають і скільки в службі лишається без тарифу.
Google об’єднує дані за правилом primary-джерела: атрибут береться з першого джерела в списку, яке його має. override ставить supplemental першим (його значення виграють), fill – останнім (лише доповнює). Сам товар лишається в джерелі застосунку й не дублюється; зміни видно в brama_gmerchant_products_get після наступної обробки.

Повторна перевірка після виправлення

API Merchant Center не має окремого «request review». Замість цього кожна проблема в brama_gmerchant_issues_render_product / _account повертає свої дії:
  • посилання на сторінку перевірки в Merchant Center (REVIEW_*_IN_MERCHANT_CENTER) – відкривається людиною;
  • вбудована форма (input), яку Brama може надіслати через brama_gmerchant_issues_trigger_action_draft з підтвердженням;
  • недоступні дії з причиною (наприклад, «уже на перевірці»).
Типовий шлях для missing_shipping: виправити доставку (shipping_label через supplemental-джерело + група тарифів), дочекатись переобробки товару, потім відкрити дії проблеми й надіслати на перевірку.

Приклади запитів агенту

  • “Які товари у мене відхилені в Merchant Center і чому?”
  • “Скільки товарів disapproved по країнах?”
  • “Які issues на рівні акаунта і як їх виправити?”
  • “Онови ціну товару X на 499 грн.” (агент підготує картку – підтверди вручну)
  • “Створи промо: безкоштовна доставка на тиждень.” (підтвердиш у картці)

Troubleshooting

Безпека

  • Brama не Google-OAuth-застосунок → CASA / Google verification не застосовується.
  • Service account JSON key – зашифровано at rest, ключі поза базою; на диск не пишеться, у пам’яті лише на час запиту.
  • Admin email використовується один раз для developer-реєстрації і не зберігається.
  • Усі зміни проходять через draft → confirm – нічого не застосовується без явного підтвердження у MCP клієнті.
  • Кожен tenant ізольований – твої Merchant Center дані недосяжні іншим tenant’ам.

Питання

Питання? Напиши viktor@brama.work.