Skip to main content

商家集成指南

7.1 接入前提

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(仅商品发现)

完整Profile(全能力)

7.3 生成签名密钥

使用OpenSSL生成ES256 (P-256)密钥对:
安全提醒: 私钥 (ucp-signing-key.pem) 必须安全存储在服务器端,绝不能出现在Profile、代码仓库或日志中。只有公钥信息(x, y 坐标)发布在Profile的 signing_keys 中。

7.4 四阶段接入路径

阶段1:Profile + 商品目录(1天)

最小可用集成。部署 /.well-known/ucp Profile和商品搜索API:
这一步的价值: 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命名:
AI代理通过能力协商确定双方共同支持的支付处理器,然后通过三步生命周期(协商、获取、完成)完成支付令牌交换。

7.6 HTTP响应头要求

UCP端点应返回以下HTTP头:
对于Profile端点(/.well-known/ucp),Cache-Controlmax-age 至少60秒,建议设置为3600秒(1小时)。
下一章: 平台集成指南 — 能力协商算法、扩展机制和多平台方案