> ## 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的完整分步集成教程，逐步讲解HTTPS下/.well-known/ucp Profile端点部署、结账与订单管理能力声明配置、ES256即P-256签名密钥对生成与OAuth授权服务器搭建，提供从仅商品发现到全能力支持的分阶段实施路径规划与生产上线检查清单

# 商家集成指南

## 7.1 接入前提

| 要求            | 说明                               | 必须/推荐 |
| ------------- | -------------------------------- | ----- |
| **HTTPS**     | 所有端点必须HTTPS，Profile端点不允许重定向(3xx) | 必须    |
| **域名**        | 拥有独立域名，能部署 `/.well-known/ucp`    | 必须    |
| **商品数据**      | 能以JSON格式返回商品数据                   | 必须    |
| **签名密钥**      | 生成ES256 (P-256) 密钥对用于Webhook签名   | 推荐    |
| **OAuth 2.0** | 如需身份关联，需要OAuth授权服务器              | 按需    |
| **支付处理器**     | 至少一个UCP兼容的支付处理器                  | 按需    |

## 7.2 第一步：部署UCP Profile

UCP Profile是AI代理发现你的能力的入口。部署在 `/.well-known/ucp` 路径：

### Profile要求

* **HTTPS only**: 必须通过HTTPS提供，HTTP请求应返回301到HTTPS
* **无重定向**: 对 `/.well-known/ucp` 的HTTPS请求不允许3xx重定向，必须直接返回200
* **Cache-Control**: 必须设置 `Cache-Control: public, max-age=N`，其中N至少60秒
* **Content-Type**: `application/json`

### 最简Profile（仅商品发现）

```json theme={null}
{
  "supported_versions": ["2026-04-08"],
  "services": {
    "dev.ucp.shopping": {
      "base_url": "https://mystore.com/ucp"
    }
  },
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08",
      "supported_operations": ["create", "get", "update", "complete", "cancel"]
    }
  },
  "signing_keys": []
}
```

### 完整Profile（全能力）

```json theme={null}
{
  "supported_versions": ["2026-04-08"],
  "services": {
    "dev.ucp.shopping": {
      "base_url": "https://mystore.com/ucp"
    },
    "dev.ucp.common": {
      "base_url": "https://mystore.com/ucp"
    }
  },
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08",
      "supported_operations": ["create", "get", "update", "complete", "cancel"]
    },
    "dev.ucp.common.identity_linking": {
      "version": "2026-04-08"
    },
    "dev.ucp.shopping.order": {
      "version": "2026-04-08"
    }
  },
  "payment_handlers": [
    "com.stripe.payment",
    "com.adyen.payment"
  ],
  "signing_keys": [
    {
      "kid": "key-2026-04",
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
```

## 7.3 生成签名密钥

使用OpenSSL生成ES256 (P-256)密钥对：

```bash theme={null}
# 生成私钥
openssl ecparam -genkey -name prime256v1 -noout -out ucp-signing-key.pem

# 提取公钥
openssl ec -in ucp-signing-key.pem -pubout -out ucp-signing-key-pub.pem

# 导出JWK格式的公钥（需要jose工具或编程实现）
# kid自定义，建议包含日期如 key-2026-04
```

**安全提醒**: 私钥 (`ucp-signing-key.pem`) 必须安全存储在服务器端，绝不能出现在Profile、代码仓库或日志中。只有公钥信息（`x`, `y` 坐标）发布在Profile的 `signing_keys` 中。

## 7.4 四阶段接入路径

### 阶段1：Profile + 商品目录（1天）

最小可用集成。部署 `/.well-known/ucp` Profile和商品搜索API：

```javascript theme={null}
const express = require("express");
const app = express();

// UCP Profile
app.get("/.well-known/ucp", (req, res) => {
  res.set("Cache-Control", "public, max-age=3600");
  res.json({
    supported_versions: ["2026-04-08"],
    services: {
      "dev.ucp.shopping": {
        base_url: "https://mystore.com/ucp"
      }
    },
    capabilities: {
      "dev.ucp.shopping.checkout": {
        version: "2026-04-08",
        supported_operations: ["create", "get", "update", "complete", "cancel"]
      }
    },
    signing_keys: []
  });
});

// 商品搜索
app.get("/ucp/catalog/products", async (req, res) => {
  const { query, category, limit = 10, offset = 0 } = req.query;

  const products = await db.products.search({
    query, category,
    limit: Math.min(parseInt(limit), 50),
    offset: parseInt(offset)
  });

  res.json({
    products: products.map(p => ({
      id: p.id,
      name: p.name,
      description: p.description,
      brand: p.brand,
      price: { amount: p.priceInCents, currency_code: "CNY" },
      availability: p.stock > 0 ? "in_stock" : "out_of_stock",
      images: [{ url: p.imageUrl, alt: p.name }],
      url: `https://mystore.com/product/${p.slug}`
    })),
    total: products.totalCount,
    limit: parseInt(limit),
    offset: parseInt(offset)
  });
});

app.listen(3000);
```

**这一步的价值**: AI代理可以发现你的UCP Profile，搜索和展示你的商品。

### 阶段2：结账能力（2-3天）

在阶段1基础上实现结账API——5种操作（Create/Get/Update/Complete/Cancel）和6个状态的状态机。需要对接支付处理器。

**关键实现**:

* 结账会话的CRUD端点
* 状态机流转逻辑
* 支付处理器集成（通过 `payment_handlers` 声明支持的处理器）
* ISO 4217金额处理

### 阶段3：身份关联（2-3天）

实现OAuth 2.0授权服务器：

* `/.well-known/oauth-authorization-server` 元数据端点
* 授权端点 (`/oauth/authorize`)
* 令牌端点 (`/oauth/token`)
* 撤销端点 (`/oauth/revoke`)，遵循RFC 7009
* PKCE (S256)支持

### 阶段4：订单管理 + Webhook（2-3天）

* 订单查询API
* 履约事件追踪
* 调整操作（退货/退款）
* Webhook通知，使用RFC 9421签名（需要在Profile中发布JWK签名密钥）

## 7.5 在UCP Profile中声明支付处理器

`payment_handlers` 数组列出你接受的支付处理器，使用反向DNS命名：

```json theme={null}
{
  "payment_handlers": [
    "com.stripe.payment",
    "com.adyen.payment",
    "com.paypal.payment",
    "com.alipay.payment"
  ]
}
```

AI代理通过能力协商确定双方共同支持的支付处理器，然后通过三步生命周期（协商、获取、完成）完成支付令牌交换。

## 7.6 HTTP响应头要求

UCP端点应返回以下HTTP头：

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=3600
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
```

对于Profile端点（`/.well-known/ucp`），`Cache-Control` 的 `max-age` 至少60秒，建议设置为3600秒（1小时）。

***

**下一章**: [平台集成指南](/zh/book-3/ch8-platform-integration) — 能力协商算法、扩展机制和多平台方案