介绍
# Google Merchant Center
通过托管的 OAuth 身份验证访问 Google Merchant Center API。管理 Google Shopping 的商品、库存、促销、数据源和报告。
## 快速开始
```bash # List products in your Merchant Center account python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-merchant/products/v1/accounts/{accountId}/products') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## Base URL
``` https://gateway.maton.ai/google-merchant/{sub-api}/{version}/accounts/{accountId}/{resource} ```
Merchant API 使用模块化子 API 结构。请替换： - `{sub-api}` 为服务名称：`products`、`accounts`、`datasources`、`reports`、`promotions`、`inventories`、`notifications`、`conversions`、`lfp` - `{version}` 为 `v1`（稳定版）或 `v1beta` - `{accountId}` 为您的 Merchant Center 账户 ID
网关将请求代理到 `merchantapi.googleapis.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization header 中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
### 查找您的 Merchant Center 账户 ID
您的 Merchant Center 账户 ID 是一个数字标识符，可在 Merchant Center 界面 URL 或账户设置中找到。所有 API 调用都需要此 ID。
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Google Merchant OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-merchant&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-merchant'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "00726960-095e-47e2-92e6-6e9cdf3e40a1", "status": "ACTIVE", "creation_time": "2026-02-07T06:41:22.751289Z", "last_updated_time": "2026-02-07T06:42:29.411979Z", "url": "https://connect.maton.ai/?session_token=...", "app": "google-merchant", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Google Merchant 连接，请使用 `Maton-Connection` header 指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-merchant/products/v1/accounts/123456/products') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '00726960-095e-47e2-92e6-6e9cdf3e40a1') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认的（最旧的）活动连接。
## API 参考
### 子 API 结构
Merchant API 组织为多个子 API，每个子 API 都有自己的版本：
| Sub-API | 用途 | 稳定版 | |---------|---------|----------------| | `products` | 商品目录管理 | v1 | | `accounts` | 账户设置和用户 | v1 | | `datasources` | 数据源配置 | v1 | | `reports` | 分析和报告 | v1 | | `promotions` | 促销优惠 | v1 | | `inventories` | 本地和区域库存 | v1 | | `notifications` | Webhook 订阅 | v1 | | `conversions` | 转化跟踪 | v1 | | `lfp` | 本地履行合作伙伴 | v1beta |
### Products
#### 列出商品
```bash GET /google-merchant/products/v1/accounts/{accountId}/products ```
查询参数： - `pageSize` (整数)：每页最大结果数 - `pageToken` (字符串)：分页令牌
#### 获取商品
```bash GET /google-merchant/products/v1/accounts/{accountId}/products/{productId} ```
商品 ID 格式：`contentLanguage~feedLabel~offerId`（例如 `en~US~sku123`）
#### 插入商品输入
```bash POST /google-merchant/products/v1/accounts/{accountId}/productInputs:insert?dataSource=accounts/{accountId}/dataSources/{dataSourceId} Content-Type: application/json
{ "offerId": "sku123", "contentLanguage": "en", "feedLabel": "US", "attributes": { "title": "Product Title", "description": "Product description", "link": "https://example.com/product", "imageLink": "https://example.com/image.jpg", "availability": "in_stock", "price": { "amountMicros": "19990000", "currencyCode": "USD" }, "condition": "new" } } ```
#### 删除商品输入
```bash DELETE /google-merchant/products/v1/accounts/{accountId}/productInputs/{productId}?dataSource=accounts/{accountId}/dataSources/{dataSourceId} ```
### Inventories
#### 列出本地库存
```bash GET /google-merchant/inventories/v1/accounts/{accountId}/products/{productId}/localInventories ```
#### 插入本地库存
```bash POST /google-merchant/inventories/v1/accounts/{accountId}/products/{productId}/localInventories:insert Content-Type: application/json
{ "storeCode": "store123", "availability": "in_stock", "quantity": 10, "price": { "amountMicros": "19990000", "currencyCode": "USD" } } ```
#### 列出区域库存
```bash GET /google-merchant/inventories/v1/accounts/{accountId}/products/{productId}/regionalInventories ```
### Data Sources
#### 列出数据源
```bash GET /google-merchant/datasources/v1/accounts/{accountId}/dataSources ```
#### 获取数据源
```bash GET /google-merchant/datasources/v1/accounts/{accountId}/dataSources/{dataSourceId} ```
#### 创建数据源
```bash POST /google-merchant/datasources/v1/accounts/{accountId}/dataSources Content-Type: application/json
{ "displayName": "API Data Source", "primaryProductDataSource": { "channel": "ONLINE_PRODUCTS", "feedLabel": "US", "contentLanguage": "en" } } ```
#### 获取数据源（触发立即刷新）
```bash POST /google-merchant/datasources/v1/accounts/{accountId}/dataSources/{dataSourceId}:fetch ```
### Reports
#### 搜索报告
```bash POST /google-merchant/reports/v1/accounts/{accountId}/reports:search Content-Type: application/json
{ "query": "SELECT offer_id, title, clicks, impressions FROM product_performance_view WHERE date BETWEEN '2026-01-01' AND '2026-01-31'" } ```
可用报告表： - `product_performance_view` - 商品的点击量、展示量、点击率 (CTR) - `product_view` - 当前库存及其属性和问题 - `price_competitiveness_product_view` - 与竞争对手的价格对比 - `price_insights_product_view` - 建议定价 - `best_sellers_product_cluster_view` - 各类别的热销商品 - `competitive_visibility_competitor_view` - 竞争对手的可见度
### Promotions
#### 列出促销
```bash GET /google-merchant/promotions/v1/accounts/{accountId}/promotions ```
#### 获取促销
```bash GET /google-merchant/promotions/v1/accounts/{accountId}/promotions/{promotionId} ```
#### 插入促销
```bash POST /google-merchant/promotions/v1/accounts/{accountId}/promotions:insert Content-Type: application/json
{ "promotionId": "promo123", "contentLanguage": "en", "targetCountry": "US", "redemptionChannel": ["ONLINE"], "attributes": { "longTitle": "20% off all products", "promotionEffectiveDates": "2026-02-01T00:00:00Z/2026-02-28T23:59:59Z" } } ```
### Accounts
#### 获取账户
```bash GET /google-merchant/accounts/v1/accounts/{accountId} ```
#### 列出子账户
```bash GET /google-merchant/accounts/v1/accounts/{accountId}:listSubaccounts ```
#### 获取业务信息
```bash GET /google-merchant/accounts/v1/accounts/{accountId}/businessInfo ```
#### 获取配送设置
```bash GET /google-merchant/accounts/v1/accounts/{accountId}/shippingSettings ```
#### 列出用户
```bash GET /google-merchant/accounts/v1/accounts/{accountId}/users ```
#### 列出项目
```bash GET /google-merchant/accounts/v1/accounts/{accountId}/programs ```
#### 列出区域
```bash GET /google-merchant/accounts/v1/accounts/{accountId}/regions ```
#### 列出在线退货政策
```bash GET /google-merchant/accounts/v1/accounts/{accountId}/onlineReturnPolicies ```
### Notifications
#### 列出通知订阅
```bash GET /google-merchant/notifications/v1/accounts/{accountId}/notificationsubscriptions ```
#### 创建通知订阅
```bash POST /google-merchant/notifications/v1/accounts/{accountId}/notificationsubscriptions Content-Type: application/json
{ "registeredEvent": "PRODUCT_STATUS_CHANGE", "callBackUri": "https://example.com/webhook" } ```
### Conversion Sources
#### 列出转化来源
```bash GET /google-merchant/conversions/v1/accounts/{accountId}/conversionSources ```
## 分页
API 使用基于令牌的分页：
```bash GET /google-merchant/products/v1/accounts/{accountId}/products?pageSize=50 ```
当存在更多结果时，响应包含 `nextPageToken`：
```json { "products": [...], "nextPageToken": "CAE..." } ```
使用该令牌获取下一页：
```bash GET /google-merchant/products/v1/accounts/{accountId}/products?pageSize=50&pageToken=CAE... ```
## 代码示例
### JavaScript
```javascript const accountId = '123456789'; const response = await fetch( `https://gateway.maton.ai/google-merchant/products/v1/accounts/${accountId}/products`, { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
account_id = '123456789' response = requests.get( f'https://gateway.maton.ai/google-merchant/products/v1/accounts/{account_id}/products', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
## 注意事项
- 商品 ID 使用格式 `contentLanguage~feedLabel~offerId`（例如 `en~US~sku123`） - 商品只能在类型为 `API` 的数据源中插入/更新/删除 - 插入/更新商品后，处理后的商品可能需要几分钟才会显示 - 货币值使用微单位（除以 1,000,000 获得实际值） - API 使用子 API 版本控制 - 优先使用 `v1` 稳定版而非 `v1beta` - 重要：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，像 `$MATON_API_KEY` 这样的环境变量在某些 shell 环境中可能无法正确展开
## 错误处理
| Status | 含义 | |--------|---------| | 400 | 缺少 Google Merchant 连接 | | 401 | Maton API 密钥无效或缺失，或无权访问指定账户 | | 403 | 请求的操作权限被拒绝 | | 404 | 资源未找到 | | 429 | 速率受限 | | 4xx/5xx | 来自 Google Merchant API 的透传错误 |
### 常见错误
**"The caller does not have access to the accounts"**：您的 OAuth 凭据无法访问指定的账户 ID。请验证您是否有权访问该 Merchant Center 账户。
**"GCP project is not registered"**：v1 稳定版 API 需要 GCP 项目注册。请使用 v1beta 或注册您的项目。
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：无效的应用名称
1. 确保您的 URL 路径以 `google-merchant` 开头。例如：
- 正确：`https://gateway.maton.ai/google-merchant/products/v1/accounts/{accountId}/products` - 错误：`https://gateway.maton.ai/products/v1/accounts/{accountId}/products`
## 资源
- [Merchant API 概述](https://developers.google.com/merchant/api/overview) - [Merchant API 参考](https://developers.google.com/merchant/api/reference/rest) - [商品指南](https://developers.google.com/merchant/api/guides/products/overview) - [数据源指南](https://developers.google.com/merchant/api/guides/datasources) - [报告指南](https://developers.google.com/merchant/api/guides/reports) - [商品数据规范](https://support.google.com/merchants/answer/7052112) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])