Agentic Commerce Protocol(ACP)技术文档
快速上手

快速上手

🚀 快速开始指南

本指南将帮助您快速开始 Agentic Commerce Protocol (ACP) 的集成，从申请访问到完成基础实现。

第一步：申请访问权限

商户申请

  1. 访问 ChatGPT 商户申请页面
  2. 填写完整的商户信息：
    • 公司基本信息
    • 产品类别和规模
    • 现有电商平台信息
    • 技术实施计划

特殊情况

  • Etsy 商户: 美国地区自动符合条件
  • Shopify 商户: 平台商户无需额外申请
  • 其他商户: 通过申请流程逐步开放

第二步：准备产品数据

数据格式选择

支持多种格式：

  • TSV (推荐) - Tab分隔值
  • CSV - 逗号分隔值
  • XML - 可扩展标记语言
  • JSON - JavaScript对象表示法

必需字段 

{
  "id": "prod_12345",
  "title": "商品名称", 
  "description": "详细商品描述",
  "price": "29.99",
  "currency": "CNY",
  "availability": "in_stock",
  "image_url": "https://example.com/image.jpg"
}

推荐字段 

{
  "category": "分类路径",
  "brand": "品牌名称",
  "weight": "重量信息",
  "shipping_cost": "运费",
  "reviews": {
    "average_rating": 4.8,
    "review_count": 156
  }
}

第三步：实现核心 API

智能体结账端点

创建结账会话 

POST /checkout_sessions
Content-Type: application/json
Authorization: Bearer <token>
API-Version: 2025-09-29
Idempotency-Key: <unique-key>

{
  "items": [
    {
      "id": "prod_12345",
      "quantity": 1
    }
  ],
  "buyer": {
    "first_name": "张",
    "last_name": "三",
    "email": "[email protected]"
  },
  "fulfillment_address": {
    "name": "张三",
    "line_one": "北京市朝阳区建国路1号",
    "city": "北京",
    "state": "BJ",
    "country": "CN",
    "postal_code": "100001"
  }
}

响应格式 

{
  "id": "checkout_session_123",
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "cny",
  "line_items": [
    {
      "id": "line_item_456",
      "item": { "id": "prod_12345", "quantity": 1 },
      "base_amount": 2999,
      "discount": 0,
      "subtotal": 2999,
      "tax": 300,
      "total": 3299
    }
  ],
  "totals": [
    { "type": "subtotal", "display_text": "小计", "amount": 2999 },
    { "type": "tax", "display_text": "税费", "amount": 300 },
    { "type": "total", "display_text": "总计", "amount": 3299 }
  ]
}

订单状态查询 

GET /checkout_sessions/{checkout_session_id}
Authorization: Bearer <token>
API-Version: 2025-09-29

Response:
{
  "id": "checkout_session_123",
  "status": "completed",
  "order": {
    "id": "ord_xyz789",
    "checkout_session_id": "checkout_session_123",
    "permalink_url": "https://acplib.com/orders/ord_xyz789"
  }
}

第四步：集成支付处理

委托支付端点

创建支付委托令牌 

POST /agentic_commerce/delegate_payment
Content-Type: application/json
Authorization: Bearer <token>
API-Version: 2025-09-29
Idempotency-Key: <unique-key>
Signature: <base64url-signature>
Timestamp: 2025-09-29T11:00:00Z

{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "virtual": false,
    "number": "4242424242424242",
    "exp_month": "12",
    "exp_year": "2026",
    "name": "张三",
    "cvc": "123",
    "display_card_funding_type": "credit",
    "display_brand": "visa",
    "display_last4": "4242",
    "metadata": {}
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 3299,
    "currency": "cny",
    "checkout_session_id": "checkout_session_123",
    "merchant_id": "acplib",
    "expires_at": "2025-10-09T07:20:50.52Z"
  },
  "billing_address": {
    "name": "张三",
    "line_one": "北京市朝阳区建国路1号",
    "city": "北京",
    "state": "BJ",
    "country": "CN",
    "postal_code": "100001"
  },
  "risk_signals": [
    { "type": "card_testing", "score": 10, "action": "authorized" }
  ],
  "metadata": { "source": "chatgpt" }
}

响应格式 

{
  "id": "vt_01J8Z3WXYZ9ABC",
  "created": "2025-09-29T11:00:00Z",
  "metadata": {
    "source": "agent_checkout",
    "merchant_id": "acplib",
    "idempotency_key": "idem_abc123"
  }
}

第五步：设置 Webhook

Webhook 端点 

app.post('/acp/webhook', (req, res) => {
  // 验证HMAC签名
  const signature = req.headers['merchant-signature'];
  const payload = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  const { event_type, order_id, data } = req.body;
  
  switch (event_type) {
    case 'order_created':
      // 处理订单创建事件
      console.log('订单已创建:', order_id);
      break;
    case 'order_updated':
      // 处理订单更新事件
      console.log('订单已更新:', order_id, data.status);
      break;
    default:
      console.log('未知事件类型:', event_type);
  }
  
  res.status(200).send('OK');
});

事件类型

  • order_created - 订单创建
  • order_updated - 订单状态更新
    • 支付状态变更
    • 发货状态更新
    • 退款处理
    • 订单取消

第六步：测试验证

沙盒测试

基于OpenAI生产认证要求，完成以下端到端测试：

  1. 会话创建和地址处理

    • 创建带有和不带配送地址的结账会话
    • 验证提供有效地址后返回配送选项和税费总计

  2. 支付令牌化测试

    • 创建委托支付令牌
    • 验证规范JSON序列化和签名生成

  3. 订单完成流程

    • 使用令牌化支付完成订单
    • 确认响应包含completed状态的订单对象

  4. 错误场景处理

    • 测试缺少必需字段 (invalid_request/400)
    • 模拟库存不足 (out_of_stock)
    • 模拟支付拒绝 (payment_declined)

  5. 幂等性验证

    • 使用相同Idempotency-Key重复请求
    • 验证参数不匹配返回409冲突

验证清单

  • ✅ API版本头 API-Version: 2025-09-29
  • ✅ 所有货币金额使用整数最小单位
  • ✅ 实现幂等性语义和冲突检测
  • ✅ 返回权威购物车状态
  • ✅ HMAC签名验证Webhook事件
  • ✅ 错误响应使用扁平对象格式

第七步：生产部署

安全要求

  • TLS配置: 使用TLS 1.2+和有效公共证书
  • PCI合规: 确保支付数据处理符合PCI DSS
  • IP白名单: 将OpenAI IP地址加入白名单
  • 签名验证: 实施请求签名和Webhook HMAC验证

性能要求

  • 响应时间: API响应时间 < 2秒
  • 可用性: 99.9%+ 服务可用性
  • 并发处理: 支持高并发请求
  • 监控告警: 实时监控和告警机制

合规检查

  • 强制HTTPS和API版本控制
  • 返回权威购物车状态
  • 使用整数最小单位表示金额
  • 实现完整的CRUD操作
  • 发出订单生命周期Webhook事件
  • 处理幂等性和冲突检测

详细的生产部署指南请参考 生产部署文档。

🛠️ 开发工具

官方 SDK 

# Node.js
npm install @acp/commerce-sdk

# Python  
pip install acp-commerce

# PHP
composer require acp/commerce-sdk

测试工具

📞 获取帮助

技术支持

官方资源

社区资源

通过以上步骤，您就能快速上手 ACP 协议的集成，为用户提供创新的 AI 驱动购物体验！

核心概念即时结账指南