REST API集成

SFTP负责每日全量快照，REST API则用于白天的实时增量更新。本章覆盖Product Feed REST API的完整参考。

4.1 认证

所有API请求必须在 Authorization header中携带Bearer token：

Authorization: Bearer api_key_123

API密钥在商家获得合作伙伴审批后由OpenAI分配。

4.2 必需的HTTP Header

每个API请求必须包含以下header：

Header	必填	说明	示例
`Authorization`	是	Bearer token认证	`Bearer api_key_123`
`Content-Type`	是	请求体格式	`application/json`
`Accept-Language`	是	响应语言偏好	`en-US`
`User-Agent`	是	客户端标识	`MyStore/1.0`
`API-Version`	是	API版本号	`2025-09-12`
`Timestamp`	是	请求时间（RFC 3339）	`2026-04-11T08:30:00Z`
`Idempotency-Key`	推荐	幂等性键	`req_abc123`
`Request-Id`	推荐	请求追踪ID	`trace_xyz789`

API版本: 当前使用 2025-09-12。版本号确保API行为的向前兼容性。 Timestamp格式: 必须使用RFC 3339格式，如 2026-04-11T08:30:00Z 或带时区偏移的格式。

4.3 Feeds端点

创建Feed

POST /product_feeds
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12

{
  "target_country": "US"
}

响应:

{
  "id": "feed_abc123",
  "target_country": "US",
  "updated_at": "2026-04-11T08:30:00Z"
}

查询Feed

GET /product_feeds/:id
Authorization: Bearer api_key_123
API-Version: 2025-09-12

响应: 返回Feed对象，包含 id、target_country、updated_at。

4.4 Products端点

列出商品

GET /product_feeds/:feed_id/products
Authorization: Bearer api_key_123
API-Version: 2025-09-12

返回该Feed下的所有商品列表。

Upsert商品

PATCH /product_feeds/:feed_id/products
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12
Idempotency-Key: upsert_20260411_batch1

{
  "products": [
    {
      "id": "prod_001",
      "title": "Wireless Earbuds Pro",
      "variants": [
        {
          "id": "var_001_black",
          "title": "Wireless Earbuds Pro - Black",
          "price": {
            "amount": 9999,
            "currency": "USD"
          },
          "availability": {
            "status": "in_stock"
          }
        }
      ]
    }
  ]
}

PATCH语义: 使用upsert逻辑。商品按 id 匹配：

如果ID已存在 — 更新该商品
如果ID不存在 — 创建新商品
未包含在请求中的商品 — 保持不变（不会被删除）

这与SFTP全量快照不同。API的PATCH不会删除未提及的商品，只影响请求中包含的商品。

4.5 Promotions端点

列出促销

GET /product_feeds/:feed_id/promotions
Authorization: Bearer api_key_123
API-Version: 2025-09-12

Upsert促销

PATCH /product_feeds/:feed_id/promotions
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12

{
  "promotions": [
    {
      "id": "promo_spring_2026",
      "title": "Spring Sale 20% Off",
      "status": "active",
      "benefits": [
        {
          "type": "percent_off",
          "percent_off": 20
        }
      ],
      "active_period": {
        "start_time": "2026-04-01T00:00:00Z",
        "end_time": "2026-04-30T23:59:59Z"
      }
    }
  ]
}

促销数据只能通过REST API提交，不支持SFTP文件上传。

4.6 错误处理

HTTP状态码	错误类型	说明
400	invalid_payload	请求体格式错误或缺少必填字段
404	not_found	Feed或商品不存在

400错误示例:

{
  "error": {
    "code": "invalid_payload",
    "message": "Missing required field: variants[0].id"
  }
}

404错误示例:

{
  "error": {
    "code": "not_found",
    "message": "Feed feed_nonexistent not found"
  }
}

4.7 幂等性

通过 Idempotency-Key header实现请求幂等性。同一个key的重复请求不会产生副作用。

PATCH /product_feeds/feed_abc123/products
Idempotency-Key: batch_20260411_001

使用建议:

为每个逻辑批次生成唯一的key
网络超时后可安全重试同一个key
key通常由业务标识 + 时间戳组合而成
不同批次必须使用不同的key

4.8 最佳实践

小批量验证优先

在全量自动化之前，先用约100条商品进行小批量测试：

创建Feed         → POST /product_feeds
上传约100个商品   → PATCH /product_feeds/:id/products
验证数据正确性    → GET /product_feeds/:id/products
确认无误后扩展到全量

API与SFTP的配合

场景	使用方式
每日全量同步	SFTP文件上传
价格实时变更	REST API PATCH
库存状态更新	REST API PATCH
新品即时上架	REST API PATCH
促销创建和管理	REST API PATCH（唯一方式）

每次API调用前确认以下header完整：

Authorization: Bearer your_api_key
Content-Type: application/json
Accept-Language: en-US
User-Agent: YourApp/1.0
API-Version: 2025-09-12
Timestamp: 2026-04-11T08:30:00Z
Idempotency-Key: unique_key_per_request
Request-Id: trace_id_for_debugging

下一章: 第5章：促销数据管理 — Promotion对象规范、折扣类型、生效周期

ACP商品数据SFTP文件上传指南 ACP促销对象与折扣规则配置

开始

学习路径

AI代理商务入门

OTR 开放信任协议

UCP 通用商务协议

ACP 代理商务协议

MCP 模型上下文协议

AI时代的SEO

ORBEXA 一体化方案

模板与提示词

术语词典

ACP Product Feed REST API参考

REST API集成

4.1 认证

4.2 必需的HTTP Header

4.3 Feeds端点

创建Feed

查询Feed

4.4 Products端点

列出商品

Upsert商品

4.5 Promotions端点

列出促销

Upsert促销

4.6 错误处理

4.7 幂等性

4.8 最佳实践

小批量验证优先

API与SFTP的配合

Header检查清单

​REST API集成

​4.1 认证

​4.2 必需的HTTP Header

​4.3 Feeds端点

​创建Feed

​查询Feed

​4.4 Products端点

​列出商品

​Upsert商品

​4.5 Promotions端点

​列出促销

​Upsert促销

​4.6 错误处理

​4.7 幂等性

​4.8 最佳实践

​小批量验证优先

​API与SFTP的配合

​Header检查清单

REST API集成

4.1 认证

4.2 必需的HTTP Header

4.3 Feeds端点

创建Feed

查询Feed

4.4 Products端点

列出商品

Upsert商品

4.5 Promotions端点

列出促销

Upsert促销

4.6 错误处理

4.7 幂等性

4.8 最佳实践

小批量验证优先

API与SFTP的配合

Header检查清单