> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brama.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Merchant Center

> Стан товарного фіду та керування товарами через AI-агента – service-account (Bring-Your-Own).

<Note>
  **Status: live.** Read-tools для стану фіду + draft → confirm write-tools (товари, залишки, промо, доставка, регіони).
</Note>

## Як це працює

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** у картці підтвердження.

<Note>
  **Merchant API.** Інтеграція працює на новому Google **Merchant API**. У формі підключення згадка про Content API for Shopping – legacy-формулювання; актуальний флоу нижче.
</Note>

## Підключення

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

1. У [Google Cloud Console](https://console.cloud.google.com/) створи (або обери) проєкт.
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`](https://app.brama.work) → **Integrations → Google Merchant Center** → заповни:

| Поле                            | Що вставити                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------ |
| **Service account JSON key**    | весь вміст `.json`-файлу з кроку 2                                             |
| **Merchant Center ID**          | числовий ID акаунта з URL Merchant Center (вгорі праворуч, біля назви акаунта) |
| **Merchant Center admin email** | **людський** Google-акаунт, який адмініструє цей Merchant Center               |

→ **Connect**. Зберігається зашифрованим; Brama ніколи не показує креди назад (лише статус «active»).

<Note>
  **Навіщо admin email.** При підключенні Brama виконує **одноразову developer-реєстрацію** Google Cloud-проєкту твого service account у твоєму Merchant Center – автоматично. Google **не** дозволяє service account зареєструвати себе самостійно, тому потрібен людський admin-акаунт. Реєстрація – **per-tenant, одноразова та ідемпотентна**: повторне підключення безпечне. Admin email використовується лише для цього кроку – він **не** зберігається.
</Note>

### 5. Запит

У своєму MCP клієнті (Claude Desktop, Gemini CLI чи будь-який інший – див. [Connect a client](/connect)):

> Які товари у мене відхилені в Merchant Center і чому?

Агент викличе `brama_gmerchant_products_list` / `brama_gmerchant_issues_render_product` і поверне статуси та причини відхилень.

## MCP tools (live)

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

<Card title="brama_gmerchant_accounts_get" icon="building-storefront">
  Деталі підключеного Merchant Center акаунта: ID, назва бізнесу, часовий пояс, мова, ознаки test / adult.

  **Параметри:** немає.

  Use: підтвердити який акаунт підключено перед іншими діями.
</Card>

<Card title="brama_gmerchant_products_list" icon="list">
  Сторінка товарів акаунта: назва, доступність, статус апруву (approved / pending / disapproved) + причини відхилень.

  **Параметри:** пагінація (default 25, max 100; page token для наступної сторінки).

  Use: огляд стану фіду, пошук відхилених товарів.
</Card>

<Card title="brama_gmerchant_products_get" icon="tag">
  Один товар за повним ідентифікатором (`accounts/{account}/products/{productId}`): назва, доступність, condition, бренд, ціна, статус апруву та item-level issues.

  **Параметри:** ідентифікатор товару *(required)*.
</Card>

<Card title="brama_gmerchant_issues_list_aggregate_product_statuses" icon="chart-bar">
  Зведення: скільки товарів active / pending / disapproved / expiring – у розрізі каналу (Shopping ads, free listings) і країни.

  **Параметри:** фільтри channel / country *(optional)*.

  Use: швидко побачити який канал чи країна має найбільше відхилень.
</Card>

<Card title="brama_gmerchant_issues_render_account" icon="triangle-exclamation">
  Issues рівня акаунта простою мовою: проблеми верифікації, порушення політик, відсутня бізнес-інформація + рекомендовані кроки.

  **Параметри:** немає.

  Use: діагностувати проблеми, що стосуються всього акаунта, а не окремого товару.
</Card>

<Card title="brama_gmerchant_issues_render_product" icon="circle-exclamation">
  Issues одного товару простою мовою – часто з вказівкою на конкретний атрибут, який треба виправити.

  **Параметри:** ідентифікатор товару *(required)*.

  Use: після того як список товарів виявив відхилений товар.
</Card>

### Зміни (draft → confirm)

<Note>
  Усі write-tools нижче – **draft**: вони готують зміну і показують у MCP клієнті картку підтвердження з **Confirm / Cancel**. Нічого не змінюється, поки ти не натиснеш **Confirm**. Прямого «apply без підтвердження» tool'а навмисно немає. Upsert **замінює весь об'єкт** значеннями, що ти передаєш – щоб змінити одне поле, спершу прочитай поточний об'єкт, зміни поле і відправ повний об'єкт назад.
</Note>

<Card title="brama_gmerchant_products_upsert_draft" icon="pen">
  Додати або оновити товар. Замінює товар цілком.
</Card>

<Card title="brama_gmerchant_products_delete_draft" icon="trash">
  Назавжди видалити товар. Незворотно.
</Card>

<Card title="brama_gmerchant_inventory_upsert_local_draft" icon="store">
  Локальні (in-store) залишки товару – ціна й доступність по `storeCode`. Замінює запис цілком.
</Card>

<Card title="brama_gmerchant_inventory_delete_local_draft" icon="trash">
  Видалити локальний (in-store) запис залишків. Незворотно.
</Card>

<Card title="brama_gmerchant_inventory_upsert_regional_draft" icon="globe">
  Регіональні залишки – override ціни й доступності по region. Замінює запис цілком.
</Card>

<Card title="brama_gmerchant_inventory_delete_regional_draft" icon="trash">
  Видалити регіональний запис залишків. Незворотно.
</Card>

<Card title="brama_gmerchant_promotions_upsert_draft" icon="percent">
  Додати або оновити промо (знижка, безкоштовна доставка, спецоффер). Замінює промо цілком. Окремого delete немає – щоб зняти промо, вистав end ефективного періоду в минуле.
</Card>

<Card title="brama_gmerchant_shipping_update_draft" icon="truck">
  Замінити налаштування доставки (служби доставки + склади). Замінює конфігурацію **цілком** – передавай повні налаштування з актуальним `etag`.
</Card>

<Card title="brama_gmerchant_regions_upsert_draft" icon="map">
  Додати або оновити регіон (іменована географічна зона для служб доставки / регіональних залишків). Update замінює регіон цілком.
</Card>

<Card title="brama_gmerchant_regions_delete_draft" icon="trash">
  Видалити регіон. Незворотно; будь-яка служба доставки чи регіональні залишки, що на нього посилаються, зламаються.
</Card>

<Card title="brama_gmerchant_regions_batch_upsert_draft" icon="map">
  Додати / оновити кілька регіонів за раз (до 100) як одну підтверджену дію.
</Card>

<Card title="brama_gmerchant_regions_batch_delete_draft" icon="trash">
  Видалити кілька регіонів за раз (до 100) як одну підтверджену дію. Незворотно.
</Card>

<Card title="brama_gmerchant_confirm_action" icon="circle-check">
  Виконує зміну, яку підготував будь-який draft вище (збереження або видалення товару, локальних / регіональних залишків, промо, налаштувань доставки чи регіонів). Це крок **Confirm** із картки.

  **Параметри:** `confirm_token` *(required – з draft)* + ті самі деталі, що показав draft (для збереження); для одиничного видалення – лише токен.

  Одноразовий: не повторювати після успіху. На клієнтах, що рендерять картку, викликається **лише** кнопкою Confirm – модель не може підтвердити сама.
</Card>

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

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

## Troubleshooting

| Симптом                                                                          | Що зробити                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"This Merchant Center isn't fully set up yet"** / помилка `GCP_NOT_REGISTERED` | Перепідключи інтеграцію в Brama admin – це повторно запустить одноразову developer-реєстрацію (ідемпотентно). Переконайся, що email service account доданий як користувач у Merchant Center, і що admin email справді адмініструє цей акаунт. |
| Реєстрація каже **not authorized**                                               | Service account ще не є користувачем Merchant Center, **або** admin email не адмініструє цей акаунт. Додай service account як користувача (крок 3) і вкажи коректний admin email (крок 4).                                                    |
| **Tools відсутні** у клієнті                                                     | Інтеграція не підключена / креди не збережені. Підключи в [`app.brama.work`](https://app.brama.work) → **Integrations → Google Merchant Center**.                                                                                             |

## Безпека

* 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`.