> ## 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.

# UCP商品数据格式与四种传输机制

> 解析UCP商品数据JSON格式规范与四种传输机制的技术细节，包括REST/OpenAPI标准接口、MCP/OpenRPC目录工具集成、A2A Agent Card代理间通信和嵌入式传输方案，涵盖商品结构定义、ISO 4217价格处理与变体管理，为开发者提供AI代理商品发现与数据传输的完整实现路径

# 商品数据与传输

## 5.1 商品数据结构

UCP使用JSON格式描述商品，所有金额遵循ISO 4217最小货币单位：

```json theme={null}
{
  "product": {
    "id": "prod_abc123",
    "name": "经典帆布运动鞋",
    "description": "舒适透气的经典帆布鞋，适合日常穿着",
    "brand": "ExampleBrand",
    "category": "运动鞋 > 帆布鞋",
    "sku": "SHOE-001",
    "gtin": "1234567890123",
    "url": "https://store.example.com/product/shoe-001",
    "images": [
      { "url": "https://store.example.com/images/shoe-1.jpg", "alt": "正面图", "width": 800, "height": 800 },
      { "url": "https://store.example.com/images/shoe-2.jpg", "alt": "侧面图", "width": 800, "height": 800 }
    ],
    "price": {
      "amount": 29900,
      "currency_code": "CNY"
    },
    "compare_at_price": {
      "amount": 39900,
      "currency_code": "CNY"
    },
    "availability": "in_stock",
    "variants": [
      {
        "id": "var_001",
        "attributes": { "size": "40", "color": "白色" },
        "sku": "SHOE-001-40-W",
        "price": { "amount": 29900, "currency_code": "CNY" },
        "availability": "in_stock"
      },
      {
        "id": "var_002",
        "attributes": { "size": "41", "color": "白色" },
        "sku": "SHOE-001-41-W",
        "price": { "amount": 29900, "currency_code": "CNY" },
        "availability": "in_stock"
      },
      {
        "id": "var_003",
        "attributes": { "size": "42", "color": "黑色" },
        "sku": "SHOE-001-42-B",
        "price": { "amount": 29900, "currency_code": "CNY" },
        "availability": "out_of_stock"
      }
    ],
    "shipping": {
      "weight": { "value": 0.8, "unit": "kg" },
      "dimensions": { "length": 32, "width": 20, "height": 12, "unit": "cm" },
      "destinations": ["CN", "HK", "TW"],
      "free_shipping_threshold": { "amount": 19900, "currency_code": "CNY" }
    },
    "return_policy": {
      "returnable": true,
      "return_days": 30,
      "conditions": "未穿着，保留标签和原包装"
    }
  }
}
```

## 5.2 必填与可选字段

| 字段                    | 类型      | 必填 | 说明                                       |
| --------------------- | ------- | -- | ---------------------------------------- |
| `id`                  | string  | 是  | 商品唯一标识                                   |
| `name`                | string  | 是  | 商品名称                                     |
| `price.amount`        | integer | 是  | 价格（ISO 4217最小货币单位）                       |
| `price.currency_code` | string  | 是  | ISO 4217货币代码                             |
| `availability`        | string  | 是  | `in_stock` / `out_of_stock` / `preorder` |
| `images`              | array   | 是  | 至少一张商品图片                                 |
| `description`         | string  | 否  | 商品描述                                     |
| `brand`               | string  | 否  | 品牌名称                                     |
| `category`            | string  | 否  | 商品分类                                     |
| `sku`                 | string  | 否  | 库存单位编号                                   |
| `gtin`                | string  | 否  | 全球贸易项目代码                                 |
| `variants`            | array   | 否  | 变体列表（多规格商品）                              |
| `compare_at_price`    | object  | 否  | 原价/划线价                                   |
| `url`                 | string  | 否  | 商品页面URL                                  |

## 5.3 变体管理

有多个规格（颜色、尺码、材质等）的商品使用 `variants` 数组：

* 每个变体有独立的 `id`、`sku`、`price` 和 `availability`
* 变体的 `attributes` 对象定义规格属性（key-value格式）
* AI代理展示商品时可以列出所有可选规格
* 变体可以有不同的价格（如大码加价）

## 5.4 四种传输机制

UCP的商品数据可以通过四种传输方式提供给AI代理，每种方式适用于不同的集成场景。

### REST传输 (OpenAPI 3.x)

最传统的服务端到服务端集成方式。商家提供符合OpenAPI 3.x规范的REST API：

```http theme={null}
GET /ucp/catalog/products?query=跑步鞋&category=运动鞋&limit=10&offset=0
Accept: application/json
Authorization: Bearer {api_key}
```

```http theme={null}
GET /ucp/catalog/products/{product_id}
Accept: application/json
```

REST传输适合已有API基础设施的商家和平台。

### MCP传输 (OpenRPC / JSON-RPC 2.0)

面向AI应用的传输方式。UCP通过MCP协议暴露商品目录工具，使用OpenRPC schema定义。提供三个标准工具：

**search\_catalog** — 搜索商品目录

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "search_catalog",
  "params": {
    "query": "跑步鞋",
    "filters": {
      "category": "运动鞋",
      "price_min": 10000,
      "price_max": 50000,
      "availability": "in_stock"
    },
    "limit": 10,
    "offset": 0
  },
  "id": 1
}
```

**lookup\_catalog** — 按SKU/GTIN精确查找

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "lookup_catalog",
  "params": {
    "sku": "SHOE-001",
    "gtin": "1234567890123"
  },
  "id": 2
}
```

**get\_product** — 获取单个商品详情

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "get_product",
  "params": {
    "product_id": "prod_abc123"
  },
  "id": 3
}
```

MCP传输的优势是AI应用（如Claude、ChatGPT）可以直接将UCP商家作为MCP工具使用，无需额外的集成代码。AI代理可以自然语言理解工具定义，自动决定何时调用哪个工具。

### A2A传输 (Agent Card Specification)

面向多代理协作场景。商家发布Agent Card，让其他AI代理发现和对接。Agent Card遵循Google的Agent-to-Agent协议规范。

适用于：购物代理调用支付代理、比价代理同时查询多个商家代理等场景。

### Embedded传输 (OpenRPC schema)

嵌入式场景下的传输方式，仅使用OpenRPC schema（不通过完整的MCP协议）。适用于商家在自己的网页中嵌入AI购物助手。

## 5.5 各传输方式对比

| 传输方式         | Schema格式               | 认证方式            | 适用场景       | 实现复杂度 |
| ------------ | ---------------------- | --------------- | ---------- | ----- |
| **REST**     | OpenAPI 3.x            | API Key / OAuth | 服务端集成、平台对接 | 低     |
| **MCP**      | OpenRPC (JSON-RPC 2.0) | MCP认证           | AI应用直接对接   | 中     |
| **A2A**      | Agent Card Spec        | 代理间认证           | 多代理协作      | 中     |
| **Embedded** | OpenRPC schema         | 页面内认证           | 嵌入式AI助手    | 低     |

## 5.6 价格格式规范

UCP使用整数表示价格（ISO 4217最小货币单位），避免浮点数精度问题：

| 货币     | currency\_code | 指数 | 299元的表示  |
| ------ | -------------- | -- | -------- |
| 人民币    | `CNY`          | 2  | `29900`  |
| 美元     | `USD`          | 2  | `29900`  |
| 日元     | `JPY`          | 0  | `299`    |
| 科威特第纳尔 | `KWD`          | 3  | `299000` |

**实现建议**: 始终从ISO 4217的exponent表查询货币的小数位数，不要硬编码。

## 5.7 搜索与过滤

UCP定义了标准化的搜索和过滤参数：

| 参数             | 类型      | 说明                                           |
| -------------- | ------- | -------------------------------------------- |
| `query`        | string  | 全文搜索关键词                                      |
| `category`     | string  | 分类筛选                                         |
| `price_min`    | integer | 最低价格（最小货币单位）                                 |
| `price_max`    | integer | 最高价格（最小货币单位）                                 |
| `availability` | string  | 库存状态筛选                                       |
| `brand`        | string  | 品牌筛选                                         |
| `limit`        | integer | 每页数量（建议最大50）                                 |
| `offset`       | integer | 偏移量                                          |
| `sort`         | string  | 排序方式（`price_asc`, `price_desc`, `relevance`） |

***

**下一章**: [安全与认证](/zh/book-3/ch6-security) — RFC 9421签名、JWK密钥、mTLS和Content-Digest