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

# ACP Product Feed REST API参考

> ACP Product Feed REST API参考文档，涵盖Feeds创建查询、Products商品Upsert更新和Promotions促销端点，详解Bearer Token认证、Idempotency-Key幂等性机制、错误处理规范及REST API与SFTP配合的双通道同步方案

# REST API集成

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

## 4.1 认证

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

```http theme={null}
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

```http theme={null}
POST /product_feeds
Content-Type: application/json
Authorization: Bearer api_key_123
API-Version: 2025-09-12

{
  "target_country": "US"
}
```

**响应**:

```json theme={null}
{
  "id": "feed_abc123",
  "target_country": "US",
  "updated_at": "2026-04-11T08:30:00Z"
}
```

### 查询Feed

```http theme={null}
GET /product_feeds/:id
Authorization: Bearer api_key_123
API-Version: 2025-09-12
```

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

## 4.4 Products端点

### 列出商品

```http theme={null}
GET /product_feeds/:feed_id/products
Authorization: Bearer api_key_123
API-Version: 2025-09-12
```

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

### Upsert商品

```http theme={null}
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端点

### 列出促销

```http theme={null}
GET /product_feeds/:feed_id/promotions
Authorization: Bearer api_key_123
API-Version: 2025-09-12
```

### Upsert促销

```http theme={null}
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"
      }
    }
  ]
}
```

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

## 4.6 错误处理

| HTTP状态码 | 错误类型             | 说明             |
| ------- | ---------------- | -------------- |
| 400     | invalid\_payload | 请求体格式错误或缺少必填字段 |
| 404     | not\_found       | Feed或商品不存在     |

**400错误示例**:

```json theme={null}
{
  "error": {
    "code": "invalid_payload",
    "message": "Missing required field: variants[0].id"
  }
}
```

**404错误示例**:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Feed feed_nonexistent not found"
  }
}
```

## 4.7 幂等性

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

```http theme={null}
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完整：

```http theme={null}
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章：促销数据管理](/zh/book-4/ch5-promotions) — Promotion对象规范、折扣类型、生效周期