Agentic Commerce Protocol(ACP)技术文档
API 参考

API 参考

ACP API 提供了完整的智能体商务功能接口，包括即时结账、支付委托、Webhooks 等核心功能。

🚀 API 概览

Base URL 

生产环境: https://api.acplib.com/v1
测试环境: https://sandbox-api.acplib.com/v1

认证方式 

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

📚 API 分类

结账 API
创建和管理即时结账会话，处理购物车和支付流程。
支付 API
支付委托创建、授权和执行的完整接口。
Webhook API
配置和管理实时事件通知接口。

🔑 快速开始

1. 获取 API 密钥 

# 注册开发者账户
curl -X POST https://api.acplib.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "company": "Your Company",
    "use_case": "e-commerce integration"
  }'

2. 测试连接 

# 验证 API 连接
curl -X GET https://api.acplib.com/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

3. 创建第一个结账会话 

curl -X POST https://api.acplib.com/v1/checkout/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "示例商品",
        "price": 2999,
        "currency": "cny",
        "quantity": 1
      }
    ],
    "success_url": "https://your-site.com/success",
    "cancel_url": "https://your-site.com/cancel"
  }'

📋 通用参数

请求头

参数类型必需描述
Authorizationstring✓Bearer token 格式的 API 密钥
Content-Typestring✓请求内容类型，通常为 application/json
X-Request-IDstring-请求唯一标识符，用于追踪和调试

响应格式

成功响应 

{
  "data": {
    // 响应数据
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

错误响应 

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter", 
    "message": "必需参数缺失",
    "param": "items"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

🔒 安全最佳实践

1. API 密钥管理

  • 使用环境变量存储 API 密钥
  • 定期轮换密钥
  • 不要在客户端代码中暴露密钥

2. 请求签名 

import hmac
import hashlib
import time

def sign_request(payload: str, secret: str) -> str:
    timestamp = str(int(time.time()))
    string_to_sign = f"{timestamp}.{payload}"
    
    signature = hmac.new(
        secret.encode(),
        string_to_sign.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return f"t={timestamp},v1={signature}"

3. 幂等性控制 

POST /v1/checkout/sessions
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: unique-key-123
Content-Type: application/json

{
  "items": [...]
}

📊 速率限制

限制类型限制值时间窗口
读取操作1000 次每小时
写入操作100 次每小时
Webhook 配置10 次每小时

速率限制头 

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642694400

🧪 测试环境

测试数据

使用以下测试数据进行开发：

{
  "test_cards": {
    "visa_success": "4242424242424242",
    "visa_decline": "4000000000000002",
    "mastercard_success": "5555555555554444"
  },
  "test_amounts": {
    "success": [100, 1000, 5000],
    "decline": [2000, 3000],
    "error": [4000]
  }
}

沙箱环境 

export ACP_API_BASE_URL="https://sandbox-api.acplib.com/v1"
export ACP_API_KEY="sk_test_..."

📞 支持和帮助

技术支持

开发资源

📝 更新日志

v1.2.0 (2025-01-15)

  • 新增支付委托 API
  • 优化错误响应格式
  • 增加请求重试机制

v1.1.0 (2024-12-01)

  • 新增 Webhook 配置 API
  • 支持批量操作
  • 性能优化

v1.0.0 (2024-10-01)

  • 初始版本发布
  • 基础结账 API
  • 支付处理功能

浏览左侧导航菜单，查看具体的 API 接口文档和使用示例。