跳转到主要内容

商品数据与传输

5.1 商品数据结构

UCP使用JSON格式描述商品,所有金额遵循ISO 4217最小货币单位:
{
  "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 必填与可选字段

字段类型必填说明
idstring商品唯一标识
namestring商品名称
price.amountinteger价格(ISO 4217最小货币单位)
price.currency_codestringISO 4217货币代码
availabilitystringin_stock / out_of_stock / preorder
imagesarray至少一张商品图片
descriptionstring商品描述
brandstring品牌名称
categorystring商品分类
skustring库存单位编号
gtinstring全球贸易项目代码
variantsarray变体列表(多规格商品)
compare_at_priceobject原价/划线价
urlstring商品页面URL

5.3 变体管理

有多个规格(颜色、尺码、材质等)的商品使用 variants 数组:
  • 每个变体有独立的 idskupriceavailability
  • 变体的 attributes 对象定义规格属性(key-value格式)
  • AI代理展示商品时可以列出所有可选规格
  • 变体可以有不同的价格(如大码加价)

5.4 四种传输机制

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

REST传输 (OpenAPI 3.x)

最传统的服务端到服务端集成方式。商家提供符合OpenAPI 3.x规范的REST API:
GET /ucp/catalog/products?query=跑步鞋&category=运动鞋&limit=10&offset=0
Accept: application/json
Authorization: Bearer {api_key}
GET /ucp/catalog/products/{product_id}
Accept: application/json
REST传输适合已有API基础设施的商家和平台。

MCP传输 (OpenRPC / JSON-RPC 2.0)

面向AI应用的传输方式。UCP通过MCP协议暴露商品目录工具,使用OpenRPC schema定义。提供三个标准工具: search_catalog — 搜索商品目录
{
  "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精确查找
{
  "jsonrpc": "2.0",
  "method": "lookup_catalog",
  "params": {
    "sku": "SHOE-001",
    "gtin": "1234567890123"
  },
  "id": 2
}
get_product — 获取单个商品详情
{
  "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格式认证方式适用场景实现复杂度
RESTOpenAPI 3.xAPI Key / OAuth服务端集成、平台对接
MCPOpenRPC (JSON-RPC 2.0)MCP认证AI应用直接对接
A2AAgent Card Spec代理间认证多代理协作
EmbeddedOpenRPC schema页面内认证嵌入式AI助手

5.6 价格格式规范

UCP使用整数表示价格(ISO 4217最小货币单位),避免浮点数精度问题:
货币currency_code指数299元的表示
人民币CNY229900
美元USD229900
日元JPY0299
科威特第纳尔KWD3299000
实现建议: 始终从ISO 4217的exponent表查询货币的小数位数,不要硬编码。

5.7 搜索与过滤

UCP定义了标准化的搜索和过滤参数:
参数类型说明
querystring全文搜索关键词
categorystring分类筛选
price_mininteger最低价格(最小货币单位)
price_maxinteger最高价格(最小货币单位)
availabilitystring库存状态筛选
brandstring品牌筛选
limitinteger每页数量(建议最大50)
offsetinteger偏移量
sortstring排序方式(price_asc, price_desc, relevance

下一章: 安全与认证 — RFC 9421签名、JWK密钥、mTLS和Content-Digest