> ## 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订单管理能力的技术实现，涵盖行项目级别状态追踪包括processing、partial、fulfilled和removed四种状态、履约事件实时推送通知、退款与取消等售后调整操作以及基于RFC 9421的Webhook消息签名验证机制，完整呈现从结账完成到交付退货的订单售后生命周期

# 订单管理

## 4.1 能力标识

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

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

UCP的订单管理是**行项目级别**的，每个商品有独立的状态追踪。这支持部分发货、部分退款等复杂场景：

| 状态           | 含义   | 说明                       |
| ------------ | ---- | ------------------------ |
| `processing` | 处理中  | 订单已确认，正在备货/等待发货          |
| `partial`    | 部分履约 | 行项目中的部分数量已发货（如订购3件，已发2件） |
| `fulfilled`  | 已履约  | 全部数量已交付                  |
| `removed`    | 已移除  | 该行项目已从订单中移除（取消或退货完成）     |

```json theme={null}
{
  "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` | 已退回发件人     |

每个履约事件包含时间戳、描述和可选的追踪信息：

```json theme={null}
{
  "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` | 价格调整（如价格保护） | 商家发起     |

### 退货/退款请求

```http theme={null}
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": "尺码偏小，需要换大一码或退款"
}
```

响应：

```json theme={null}
{
  "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 查询订单

```http theme={null}
GET /ucp/orders/{order_id}
Authorization: Bearer {access_token}
```

返回订单的完整状态，包括所有行项目、履约事件和调整历史。

### 查询订单列表

```http theme={null}
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请求格式

```http theme={null}
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分钟以内）

```text theme={null}
验证流程:

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 订单生命周期总览

```text theme={null}
结账完成
  │
  ▼
订单创建 (line items: processing)
  │
  ├─→ 部分发货 (partial) ──→ 全部发货 (fulfilled)
  │                              │
  │                              ├─→ 退货请求 (adjustment: return)
  │                              │     ├─→ 退款 (adjustment: refund)
  │                              │     └─→ 换货 (adjustment: exchange)
  │                              │
  │                              └─→ 完成 ✓
  │
  └─→ 取消 (removed)
```

***

**下一章**: [商品数据与传输](/zh/book-3/ch5-product-data) — MCP工具、四种传输机制和数据格式