订单管理

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后必须验证签名：

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

验证流程:

解析 Signature-Input → keyid="key-2026-04"
获取商家JWK → /.well-known/ucp → signing_keys[kid="key-2026-04"]
验证 Content-Digest → SHA-256(body) == Content-Digest值
构造签名基础字符串 → 按Signature-Input中的组件顺序拼接
验证 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工具、四种传输机制和数据格式

UCP OAuth 2.0身份关联机制 UCP商品数据格式与四种传输机制

开始

学习路径

AI代理商务入门

OTR 开放信任协议

UCP 通用商务协议

ACP 代理商务协议

MCP 模型上下文协议

AI时代的SEO

ORBEXA 一体化方案

模板与提示词

术语词典

UCP订单管理与履约事件通知

订单管理

4.1 能力标识

4.2 行项目状态 (Line Item Status)

4.3 履约事件 (Fulfillment Events)

4.4 调整操作 (Adjustments)

退货/退款请求

4.5 查询订单

查询订单列表

4.6 Webhook通知

Webhook请求格式

Webhook签名验证

Webhook事件类型

4.7 订单生命周期总览

​订单管理

​4.1 能力标识

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

​4.3 履约事件 (Fulfillment Events)

​4.4 调整操作 (Adjustments)

​退货/退款请求

​4.5 查询订单

​查询订单列表

​4.6 Webhook通知

​Webhook请求格式

​Webhook签名验证

​Webhook事件类型

​4.7 订单生命周期总览

订单管理

4.1 能力标识

4.2 行项目状态 (Line Item Status)

4.3 履约事件 (Fulfillment Events)

4.4 调整操作 (Adjustments)

退货/退款请求

4.5 查询订单

查询订单列表

4.6 Webhook通知

Webhook请求格式

Webhook签名验证

Webhook事件类型

4.7 订单生命周期总览