跳转到主要内容

​
订单管理

​
4.1 能力标识

订单管理的命名空间为 dev.ucp.shopping.order。它覆盖了从结账完成到最终交付（或退货退款）的完整售后生命周期。

​
4.2 行项目状态 (Line Item Status)

UCP的订单管理是行项目级别的，每个商品有独立的状态追踪。这支持部分发货、部分退款等复杂场景：
状态含义说明
processing处理中订单已确认，正在备货/等待发货
partial部分履约行项目中的部分数量已发货（如订购3件，已发2件）
fulfilled已履约全部数量已交付
removed已移除该行项目已从订单中移除（取消或退货完成）
{
  "order": {
    "id": "ord_20260411_xyz789",
    "status": "active",
    "line_items": [
      {
        "id": "li_001",
        "product_id": "prod_abc123",
        "name": "经典帆布运动鞋 - 白色 42码",
        "quantity": 2,
        "status": "partial",
        "fulfilled_quantity": 1,
        "unit_price": { "amount": 29900, "currency_code": "CNY" }
      },
      {
        "id": "li_002",
        "product_id": "prod_def456",
        "name": "运动袜三双装",
        "quantity": 1,
        "status": "fulfilled",
        "fulfilled_quantity": 1,
        "unit_price": { "amount": 4900, "currency_code": "CNY" }
      }
    ]
  }
}

​
4.3 履约事件 (Fulfillment Events)

UCP定义了标准化的履约事件类型，覆盖从发货到交付的全部物流节点：
事件类型含义
processing正在处理/备货
shipped已发货，已交给承运商
in_transit运输中
out_for_delivery正在派送
attempted_delivery尝试投递未成功
delivered已送达
ready_for_pickup已到达自提点
picked_up用户已自提
failed配送失败
returned_to_sender已退回发件人
每个履约事件包含时间戳、描述和可选的追踪信息： 
{
  "fulfillment": {
    "id": "ful_001",
    "line_item_ids": ["li_001"],
    "tracking": {
      "carrier": "SF Express",
      "tracking_number": "SF1234567890",
      "tracking_url": "https://www.sf-express.com/track/SF1234567890"
    },
    "events": [
      {
        "type": "delivered",
        "occurred_at": "2026-04-14T14:30:00Z",
        "description": "已签收，签收人：本人"
      },
      {
        "type": "out_for_delivery",
        "occurred_at": "2026-04-14T08:00:00Z",
        "description": "正在派送中"
      },
      {
        "type": "in_transit",
        "occurred_at": "2026-04-13T06:00:00Z",
        "description": "已到达北京分拨中心"
      },
      {
        "type": "shipped",
        "occurred_at": "2026-04-12T10:00:00Z",
        "description": "已揽收"
      }
    ]
  }
}

​
4.4 调整操作 (Adjustments)

订单完成后可能需要各种调整。UCP定义了标准化的调整类型：
调整类型含义触发方
refund退款商家或消费者发起
return退货消费者发起
credit信用额度/商店积分商家发起
exchange换货消费者发起
price_adjustment价格调整（如价格保护）商家发起

​
退货/退款请求

POST /ucp/orders/{order_id}/adjustments
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "type": "return",
  "line_items": [
    {
      "line_item_id": "li_001",
      "quantity": 1,
      "reason": "wrong_size"
    }
  ],
  "preferred_resolution": "refund",
  "notes": "尺码偏小，需要换大一码或退款"
}
响应： 
{
  "adjustment": {
    "id": "adj_001",
    "type": "return",
    "status": "pending_merchant_approval",
    "created_at": "2026-04-16T10:00:00Z",
    "line_items": [
      {
        "line_item_id": "li_001",
        "quantity": 1,
        "reason": "wrong_size"
      }
    ],
    "return_shipping": {
      "label_url": null,
      "instructions": "等待商家审批后提供退货标签"
    }
  }
}

​
4.5 查询订单

GET /ucp/orders/{order_id}
Authorization: Bearer {access_token}
返回订单的完整状态，包括所有行项目、履约事件和调整历史。

​
查询订单列表

GET /ucp/orders?limit=20&offset=0&status=active
Authorization: Bearer {access_token}

​
4.6 Webhook通知

当订单状态发生变化时，商家通过Webhook主动通知AI代理。UCP的Webhook使用 RFC 9421 HTTP Message Signatures 确保数据完整性和来源真实性。

​
Webhook请求格式

POST https://agent.example.com/webhooks/ucp
Content-Type: application/json
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04"
Signature: sig1=:MEUCIQDXsM...base64...=:

{
  "event_type": "order.fulfillment.updated",
  "event_id": "evt_20260414_001",
  "occurred_at": "2026-04-14T14:30:00Z",
  "order_id": "ord_20260411_xyz789",
  "data": {
    "fulfillment_id": "ful_001",
    "new_event": {
      "type": "delivered",
      "occurred_at": "2026-04-14T14:30:00Z",
      "description": "已签收"
    }
  }
}

​
Webhook签名验证

AI代理收到Webhook后必须验证签名：
  1. 从 Signature-Input 头解析签名参数（签名组件、创建时间、密钥ID）
  2. 从商家的 /.well-known/ucp Profile获取对应 kid 的签名公钥（JWK）
  3. 使用 Content-Digest 头验证请求体的SHA-256哈希
  4. 使用公钥验证 Signature 头中的ES256签名
  5. 检查 created 时间戳，拒绝过期的签名（建议窗口: 5分钟以内）
验证流程:

1. 解析 Signature-Input → keyid="key-2026-04"
2. 获取商家JWK → /.well-known/ucp → signing_keys[kid="key-2026-04"]
3. 验证 Content-Digest → SHA-256(body) == Content-Digest值
4. 构造签名基础字符串 → 按Signature-Input中的组件顺序拼接
5. 验证 ES256 签名

​
Webhook事件类型

事件触发条件
order.created结账完成，订单已创建
order.fulfillment.updated履约状态变化（发货、送达等）
order.adjustment.created新的调整请求已创建
order.adjustment.updated调整状态变化（审批、完成等）
order.canceled订单已取消

​
4.7 订单生命周期总览

结账完成
  │
  ▼
订单创建 (line items: processing)
  │
  ├─→ 部分发货 (partial) ──→ 全部发货 (fulfilled)
  │                              │
  │                              ├─→ 退货请求 (adjustment: return)
  │                              │     ├─→ 退款 (adjustment: refund)
  │                              │     └─→ 换货 (adjustment: exchange)
  │                              │
  │                              └─→ 完成 ✓
  │
  └─→ 取消 (removed)
下一章: 商品数据与传输 — MCP工具、四种传输机制和数据格式