跳转到主要内容

​
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推荐请求追踪IDtrace_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状态码错误类型说明
400invalid_payload请求体格式错误或缺少必填字段
404not_foundFeed或商品不存在
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条商品进行小批量测试： 
1. 创建Feed         → POST /product_feeds
2. 上传约100个商品   → PATCH /product_feeds/:id/products
3. 验证数据正确性    → GET /product_feeds/:id/products
4. 确认无误后扩展到全量

​
API与SFTP的配合

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

​
Header检查清单

每次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对象规范、折扣类型、生效周期