跳转到主要内容

​
商家集成指南

​
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（仅商品发现）

{
  "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（全能力）

{
  "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)密钥对： 
# 生成私钥
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： 
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命名： 
{
  "payment_handlers": [
    "com.stripe.payment",
    "com.adyen.payment",
    "com.paypal.payment",
    "com.alipay.payment"
  ]
}
AI代理通过能力协商确定双方共同支持的支付处理器，然后通过三步生命周期（协商、获取、完成）完成支付令牌交换。

​
7.6 HTTP响应头要求

UCP端点应返回以下HTTP头： 
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小时）。
下一章: 平台集成指南 — 能力协商算法、扩展机制和多平台方案