Google Merchant Center

核心用法

该技能通过Maton网关代理访问Google Merchant Center API，采用托管OAuth方案免除开发者自行管理Google OAuth凭证的复杂度。用户需先获取Maton API Key并建立Google Merchant OAuth连接，随后即可调用涵盖8个子API的完整功能矩阵：Products（商品管理）、Accounts（账户设置）、Datasources（数据源配置）、Reports（分析报告）、Promotions（促销活动）、Inventories（本地/区域库存）、Notifications（Webhook订阅）及Conversions（转化追踪）。

API采用模块化URL结构gateway.maton.ai/google-merchant/{sub-api}/{version}/accounts/{accountId}/{resource}，强烈建议使用v1beta版本——v1版本需额外注册GCP项目，否则返回401错误。所有请求通过Authorization: Bearer $MATON_API_KEY头认证，支持通过Maton-Connection头指定多连接场景。

显著优点

1. 零OAuth运维成本：Maton托管OAuth全生命周期，开发者无需处理token刷新、密钥存储及权限变更
2. 版本兼容性保障：明确区分v1beta（免注册）与v1（需GCP绑定）的使用场景，降低接入门槛
3. 多语言示例完备：提供Python、JavaScript、bash/curl的完整调用示例，覆盖连接管理、CRUD操作及分页查询
4. 细粒度权限控制：支持多连接管理，可通过header指定特定Merchant Center连接
5. 实时数据能力：支持Notifications API订阅商品状态变更事件，实现Webhook驱动的自动化工作流

潜在缺点与局限性

• 供应商锁定风险：强依赖Maton服务可用性，API Key泄露将导致全部连接暴露
• 功能受限场景：Promotions API需账户预先注册促销计划；Local Inventory仅支持LOCAL渠道商品；Sub-accounts列表仅限多客户账户(MCA)调用
• 数据延迟：商品插入/更新后需数分钟处理才能在product_view中可见
• 货币单位复杂度：价格字段采用micros（百万分之一），增加计算转换负担
• 查询限制：product_view表强制要求SELECT语句包含id字段

适合人群

• 跨境电商运营团队：需批量管理Google Shopping商品feed、监控账户健康度
• SaaS电商工具开发者：构建基于Google Merchant数据的第三方分析或优化工具
• 性能营销分析师：通过Reports API获取点击、展示、价格竞争力等核心指标
• 多店铺管理者：利用MCA支持及多连接切换管理多个Merchant Center账户

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 认证失效 | OAuth连接过期或Maton API Key泄露 | 定期审查ctrl.maton.ai连接状态，密钥 rotation |

| 数据操作误删 | DELETE端点无二次确认 | 生产环境操作前验证accountId/productId |

| 费率限制 | 429状态码触发 | 实现指数退避重试，避免高峰期密集调用 |

| 合规风险 | 商品信息违反Google政策导致账户暂停 | 结合product_view的item_issues字段主动监控 |

| 版本混淆 | 误用v1导致"GCP project not registered"错误 | 统一使用v1beta路径，除非明确需要v1特性 |

核心用法

Google Merchant Skill 是面向电商场景的 API 集成工具，通过 Maton 托管网关代理调用 Google Merchant Center API。用户无需自建 GCP 项目或处理 OAuth 流程，仅需配置 MATON_API_KEY 环境变量即可使用。

主要功能模块：

• Products：产品目录的增删改查，支持 API 数据源实时推送
• Inventories：本地库存（Local）和区域库存（Regional）管理
• DataSources：数据源配置，支持 API/文件/UI 多种输入类型
• Reports：Shopping 表现分析，包括点击、展示、价格竞争力等维度
• Promotions：促销优惠管理（需账号 enrolled）
• Accounts：多账号管理、用户权限、运输设置等业务配置

快速接入路径：
1. 在 maton.ai 获取 API Key 并配置环境变量
2. 通过 ctrl.maton.ai 创建 Google Merchant OAuth 连接
3. 使用 gateway.maton.ai/google-merchant/{sub-api}/v1beta/accounts/{accountId}/{resource} 调用具体接口

显著优点

1. 零基础设施 OAuth：Maton 托管 OAuth 流程，用户无需注册 GCP 项目或配置 OAuth 客户端
2. v1beta 免注册策略：规避 GCP 项目注册要求，开箱即用
3. 模块化 API 设计：8 个独立子 API（products/accounts/reports 等），按需调用
4. 代码示例完备：提供 Python、JavaScript、bash curl 多语言示例，降低接入门槛
5. 连接管理灵活：支持多账号连接，通过 Maton-Connection Header 指定特定连接

潜在缺点与局限性

1. 第三方依赖锁定：核心功能完全依赖 Maton 网关服务，服务可用性受其 SLA 约束
2. 数据跨境传输：所有商户数据需经 Maton 美国服务器转发至 Google
3. API 密钥单一认证：仅支持 Bearer Token，无细粒度权限控制（如只读/读写分离）
4. 延迟与缓存：产品插入后需数分钟才能在 processed product 中可见
5. 功能限制：Promotions 需单独 enrolled；Local Inventory 仅限 LOCAL 渠道产品
6. MCA 限制：多客户账号（Multi-client Account）专属接口对标准商户返回 403

适合人群

• 独立站卖家：使用 Shopify/WooCommerce 等自建站，需同步商品至 Google Shopping
• 代运营服务商：管理多个 Merchant Center 账号，需批量操作和数据报表
• 电商数据分析师：需要程序化获取 Shopping Ads 表现数据
• 中小技术团队：无专职 DevOps，希望免运维 OAuth 和网关基础设施

常规风险

| 风险类型 | 具体表现 | 缓释建议 |

|---------|---------|---------|

| 密钥泄露 | `MATON_API_KEY` 泄露导致账号被滥用 | 使用 `.env` 或 Secret Manager，禁止硬编码 |

| 数据跨境合规 | 商户数据经美国传输 | 评估 GDPR/数据出境合规要求 |

| 供应商锁定 | Maton 服务中断导致业务停摆 | 保留直接接入 Google API 的备选方案 |

| 误操作风险 | DELETE 操作不可逆，批量删除造成损失 | 生产环境操作前在沙箱验证 |

| 费率限制 | 429 Rate Limited | 实现指数退避重试逻辑 |

特别提示：技能评分 A/78 分，属标准安全级别。纯文档型设计无可执行代码，但用户需自行确保 API Key 来源合法（maton.ai 官方渠道）及妥善保管。