API 参考文档

API 参考文档

基于OpenAPI 3.1规范的ACP协议完整API参考文档。

🔗 基础信息

API版本: 2025-09-29
协议: HTTPS
认证: Bearer Token
内容类型: application/json

🔐 认证

所有API请求必须包含有效的Bearer token：

Authorization: Bearer <your-api-token>

📋 通用头部

必需头部

Authorization: Bearer <token> - API认证令牌
API-Version: 2025-09-29 - API版本标识
Content-Type: application/json - 请求内容类型

可选头部 (安全增强)

Signature: <base64url-signature> - 请求签名
Timestamp: <RFC3339-timestamp> - 请求时间戳

🛒 智能体结账 API

创建结账会话

创建新的结账会话，初始化购物车状态。

POST /checkout_sessions

请求体:

{
  "items": [
    {
      "id": "prod_12345",
      "quantity": 2
    }
  ],
  "buyer": {
    "first_name": "张",
    "last_name": "三",
    "email": "[email protected]",
    "phone_number": "+86-138-0013-8000"
  },
  "fulfillment_address": {
    "name": "张三",
    "line_one": "北京市朝阳区建国路1号",
    "line_two": "国贸大厦A座",
    "city": "北京",
    "state": "BJ",
    "country": "CN",
    "postal_code": "100001"
  }
}

响应 (201 Created):

{
  "id": "checkout_session_abc123",
  "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": 2
      },
      "base_amount": 5998,
      "discount": 600,
      "subtotal": 5398,
      "tax": 540,
      "total": 5938
    }
  ],
  "fulfillment_address": {
    "name": "张三",
    "line_one": "北京市朝阳区建国路1号",
    "line_two": "国贸大厦A座",
    "city": "北京",
    "state": "BJ",
    "country": "CN",
    "postal_code": "100001"
  },
  "fulfillment_option_id": "standard_shipping",
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "standard_shipping",
      "title": "标准配送",
      "subtitle": "3-5个工作日",
      "carrier": "顺丰速运",
      "earliest_delivery_time": "2025-10-12T09:00:00Z",
      "latest_delivery_time": "2025-10-15T18:00:00Z",
      "subtotal": 1500,
      "tax": 0,
      "total": 1500
    },
    {
      "type": "shipping", 
      "id": "express_shipping",
      "title": "次日达",
      "subtitle": "1个工作日",
      "carrier": "顺丰速运",
      "earliest_delivery_time": "2025-10-10T09:00:00Z",
      "latest_delivery_time": "2025-10-10T18:00:00Z",
      "subtotal": 3000,
      "tax": 0,
      "total": 3000
    }
  ],
  "totals": [
    {
      "type": "items_base_amount",
      "display_text": "商品总计",
      "amount": 5998
    },
    {
      "type": "items_discount",
      "display_text": "商品优惠",
      "amount": -600
    },
    {
      "type": "subtotal",
      "display_text": "小计",
      "amount": 5398
    },
    {
      "type": "fulfillment",
      "display_text": "配送费",
      "amount": 1500
    },
    {
      "type": "tax",
      "display_text": "税费",
      "amount": 540
    },
    {
      "type": "total",
      "display_text": "总计",
      "amount": 7438
    }
  ],
  "messages": [],
  "links": [
    {
      "type": "terms_of_use",
      "url": "https://acplib.com/legal/terms"
    },
    {
      "type": "privacy_policy", 
      "url": "https://acplib.com/legal/privacy"
    }
  ]
}

更新结账会话

更新现有结账会话的商品、地址或配送选项。

POST /checkout_sessions/{checkout_session_id}

请求体示例 (更新配送选项):

{
  "fulfillment_option_id": "express_shipping"
}

请求体示例 (更新商品):

{
  "items": [
    {
      "id": "prod_12345",
      "quantity": 3
    },
    {
      "id": "prod_67890", 
      "quantity": 1
    }
  ]
}

响应 (200 OK): 返回更新后的完整会话对象

检索结账会话

获取结账会话的当前状态。

GET /checkout_sessions/{checkout_session_id}

响应 (200 OK): 返回完整的会话对象

完成结账会话

使用支付信息完成结账，创建订单。

POST /checkout_sessions/{checkout_session_id}/complete

请求体:

{
  "buyer": {
    "first_name": "张",
    "last_name": "三", 
    "email": "[email protected]",
    "phone_number": "+86-138-0013-8000"
  },
  "payment_data": {
    "token": "vt_01J8Z3WXYZ9ABC",
    "provider": "stripe",
    "billing_address": {
      "name": "张三",
      "line_one": "北京市朝阳区建国路1号",
      "city": "北京",
      "state": "BJ",
      "country": "CN",
      "postal_code": "100001"
    }
  }
}

响应 (200 OK):

{
  "id": "checkout_session_abc123",
  "status": "completed",
  "order": {
    "id": "ord_xyz789",
    "checkout_session_id": "checkout_session_abc123",
    "permalink_url": "https://acplib.com/orders/ord_xyz789"
  },
  "currency": "cny",
  "line_items": [...],
  "totals": [...],
  "messages": [
    {
      "type": "info",
      "content_type": "plain",
      "content": "订单已成功创建，我们将尽快为您发货。"
    }
  ]
}

取消结账会话

取消未完成的结账会话。

POST /checkout_sessions/{checkout_session_id}/cancel

响应 (200 OK):

{
  "id": "checkout_session_abc123",
  "status": "canceled",
  "messages": [
    {
      "type": "info",
      "content_type": "plain", 
      "content": "结账会话已取消。"
    }
  ]
}

💳 支付委托 API

创建支付委托令牌

为支付凭证创建委托令牌，用于后续的支付处理。

POST /agentic_commerce/delegate_payment

请求体:

{
  "payment_method": {
    "type": "card",
    "card_number_type": "fpan",
    "virtual": false,
    "number": "4242424242424242",
    "exp_month": "12",
    "exp_year": "2026",
    "name": "张三",
    "cvc": "123",
    "checks_performed": ["avs", "cvv"],
    "iin": "424242",
    "display_card_funding_type": "credit",
    "display_wallet_type": null,
    "display_brand": "visa",
    "display_last4": "4242",
    "metadata": {
      "issuing_bank": "招商银行"
    }
  },
  "allowance": {
    "reason": "one_time",
    "max_amount": 7438,
    "currency": "cny",
    "checkout_session_id": "checkout_session_abc123",
    "merchant_id": "acplib_merchant",
    "expires_at": "2025-10-09T15:30:00Z"
  },
  "billing_address": {
    "name": "张三",
    "line_one": "北京市朝阳区建国路1号",
    "line_two": "国贸大厦A座",
    "city": "北京",
    "state": "BJ",
    "country": "CN",
    "postal_code": "100001"
  },
  "risk_signals": [
    {
      "type": "card_testing",
      "score": 15,
      "action": "authorized"
    }
  ],
  "metadata": {
    "source": "chatgpt",
    "session_id": "chat_session_123",
    "user_agent": "Mozilla/5.0..."
  }
}

响应 (201 Created):

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

📊 数据模型

CheckoutSession 对象

字段	类型	描述
`id`	string	会话唯一标识符
`status`	enum	会话状态: `not_ready_for_payment`, `ready_for_payment`, `completed`, `canceled`, `in_progress`
`currency`	string	ISO 4217货币代码 (小写)
`line_items`	LineItem[]	订单行项目列表
`fulfillment_address`	Address	配送地址
`fulfillment_options`	FulfillmentOption[]	可用配送选项
`fulfillment_option_id`	string	选定的配送选项ID
`totals`	Total[]	金额汇总列表
`payment_provider`	PaymentProvider	支付服务提供商信息
`buyer`	Buyer	买方信息
`messages`	Message[]	消息列表
`links`	Link[]	相关链接
`order`	Order	订单信息 (仅完成状态)

LineItem 对象

字段	类型	描述
`id`	string	行项目唯一标识符
`item`	Item	商品信息
`base_amount`	integer	基础金额 (最小单位)
`discount`	integer	折扣金额 (最小单位)
`subtotal`	integer	小计金额 (最小单位)
`tax`	integer	税费金额 (最小单位)
`total`	integer	总计金额 (最小单位)

PaymentMethod 对象

字段	类型	必需	描述
`type`	string	✅	支付方式类型 (目前仅支持 “card”)
`card_number_type`	enum	✅	卡号类型: `fpan`, `network_token`
`virtual`	boolean	✅	是否为虚拟卡
`number`	string	✅	卡号/令牌
`exp_month`	string	❌	到期月份 (01-12)
`exp_year`	string	❌	到期年份 (四位数)
`name`	string	❌	持卡人姓名
`cvc`	string	❌	安全码
`display_card_funding_type`	enum	✅	卡类型: `credit`, `debit`, `prepaid`
`display_brand`	string	❌	卡品牌 (如 “visa”, “mastercard”)
`display_last4`	string	❌	卡号后四位

⚠️ 错误处理

所有错误响应使用统一的扁平对象格式：

{
  "type": "invalid_request",
  "code": "missing_field",
  "message": "缺少必需字段 'items'",
  "param": "$.items"
}

错误类型

类型	HTTP状态码	描述
`invalid_request`	400	请求格式错误或缺少必需字段
`request_not_idempotent`	409	幂等性冲突
`processing_error`	422	业务逻辑处理错误
`rate_limit_exceeded`	429	请求频率超限
`service_unavailable`	503	服务暂时不可用

常见错误代码

代码	描述
`missing_field`	缺少必需字段
`invalid_field`	字段值无效
`out_of_stock`	商品库存不足
`payment_declined`	支付被拒绝
`idempotency_conflict`	幂等性密钥冲突
`session_not_found`	会话不存在
`session_already_completed`	会话已完成

🔄 幂等性

为确保操作的幂等性，建议在创建和完成操作中使用 Idempotency-Key 头部：

Idempotency-Key: unique-operation-key-123

相同密钥和相同参数的重复请求将返回相同结果
相同密钥但不同参数的请求将返回 409 冲突错误

📏 限制和约束

请求限制

最大请求体大小: 1MB
API调用频率: 每秒100次
超时时间: 30秒

数据限制

商品数量: 每个会话最多100个商品
地址长度: 各字段最大长度见Address对象定义
货币精度: 使用最小单位的整数表示

会话生命周期

会话有效期: 24小时
支付令牌有效期: 由allowance.expires_at指定
最大重试次数: 3次

通过遵循此API参考文档，您可以正确实施ACP协议的所有接口，确保与ChatGPT等AI智能体的无缝集成。

支付委托规范

🔗 基础信息

🔐 认证

📋 通用头部

必需头部

推荐头部

可选头部 (安全增强)

🛒 智能体结账 API

创建结账会话

更新结账会话

检索结账会话

完成结账会话

取消结账会话

💳 支付委托 API

创建支付委托令牌

📊 数据模型

CheckoutSession 对象

LineItem 对象

PaymentMethod 对象

⚠️ 错误处理

错误类型

常见错误代码

🔄 幂等性

📏 限制和约束

请求限制

数据限制

会话生命周期