API参考与限速
认证方式
ORBEXA支持三种认证方式：API密钥认证
适用于MCP工具调用和API访问：OAuth认证
适用于Shopify等平台集成，遵循标准OAuth 2.0流程。插件Header认证
适用于WordPress插件接入，需要携带必需Header：X-Plugin-Platform— 平台标识X-Plugin-Version— 插件版本号
完整端点清单
UCP端点
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
/.well-known/ucp | GET | 无 | UCP发现文档 |
/ucp/v1/products | GET | API密钥 | 商品列表（JSON/TSV） |
/ucp/v1/products/:id | GET | API密钥 | 商品详情（含变体） |
/ucp/v1/search | GET | API密钥 | 全文商品搜索 |
/ucp/v1/checkout-sessions | POST | API密钥 | 创建结账会话 |
/ucp/v1/manifest | GET | API密钥 | 商家能力声明 |
/ucp/acp-feed.json | GET | API密钥 | ACP格式商品Feed |
ACP端点 — JSON-RPC 2.0
| 方法 | 认证 | 描述 |
|---|---|---|
commerce.search | API密钥 | 商品搜索 |
commerce.product | API密钥 | 商品详情 |
commerce.checkout | API密钥 | 发起结账 |
commerce.order_status | API密钥 | 订单状态查询 |
commerce.capabilities | API密钥 | 能力声明 |
ACP端点 — REST
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
/acp/v1/products | GET | API密钥 | 商品列表 |
/acp/v1/checkout | POST | API密钥 | 结账操作 |
MCP端点
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
/api/mcp/tools | GET | API密钥 | 工具列表 |
/api/mcp/execute | POST | API密钥 | 执行工具 |
/api/mcp/resources | GET | API密钥 | 资源列表 |
/api/mcp/usage | GET | API密钥 | 用量统计 |
/api/mcp/prompts | GET | API密钥 | 提示词列表 |
发现端点
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
/.well-known/ucp | GET | 无 | UCP协议发现 |
/.well-known/acp | GET | 无 | ACP协议发现 |
/.well-known/mcp | GET | 无 | MCP协议发现 |
OTR端点
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
/api/otr/verify/:domain | GET | 无 | 查询域名信任评分 |
/.well-known/otr/verify | GET | 无 | 标准化信任查询端点 |
Shopify集成
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
| Shopify OAuth回调 | GET | OAuth | 处理Shopify授权回调 |
| Shopify Webhooks | POST | HMAC验签 | 接收Shopify事件通知 |
WooCommerce集成
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
/api/integrations/woocommerce/connect | POST | API密钥 | 连接商店 |
/api/integrations/woocommerce/test | POST | API密钥 | 测试连接 |
/api/integrations/woocommerce/sync/products | POST | API密钥 | 同步商品 |
/api/integrations/woocommerce/sync/orders | POST | API密钥 | 同步订单 |
/api/integrations/woocommerce/sync/inventory | POST | API密钥 | 同步库存 |
/api/integrations/woocommerce/webhooks/setup | POST | API密钥 | 注册Webhook |
/api/integrations/woocommerce/webhooks/handle | POST | 签名验证 | 处理Webhook事件 |
WordPress集成
| 端点 | 方法 | 认证 | 描述 |
|---|---|---|---|
/api/integrations/wordpress/connect | POST | Header认证 | 一键连接 |
/api/integrations/wordpress/status | POST | Header认证 | 查询状态 |
/api/integrations/wordpress/disconnect | POST | Header认证 | 断开连接 |
限速策略
总体架构
ORBEXA的限速系统基于Redis实现，内存作为降级方案。采用令牌桶算法配合指数退避策略：- 令牌桶：每个时间窗口分配固定数量的令牌，每次请求消耗一个令牌
- 指数退避：触发限速后，客户端应按指数增长的间隔重试
按端点类型的限速预设
| 端点类型 | 限速 | 说明 |
|---|---|---|
| UCP端点 | 100次/分钟 | AI代理的主要访问入口 |
| API端点 | 60次/分钟 | 通用API调用 |
| 认证端点 | 10次/分钟 | 登录/注册等敏感操作 |
| Webhook端点 | 200次/分钟 | 接收平台事件通知 |
| WordPress插件 | 3次/分钟/IP | 插件连接和状态查询 |
平台侧限速
ORBEXA对上游平台的调用也有限速控制，防止超过平台API限制：| 平台 | 限速 | 说明 |
|---|---|---|
| Shopify API | 2次/秒 | 遵守Shopify API限制 |
| WooCommerce API | 5次/秒 | 保护商家服务器 |
内部调用跳过限速
ORBEXA内部服务（如PDF报告生成时的自调用）通过X-OTR-Internal-KeyHeader认证跳过限速。这确保内部流程不被外部限速规则阻塞。
错误处理
限速错误
当请求超过限速时，API返回HTTP 429状态码：retry_after字段指示客户端应等待的秒数。
认证错误
| 状态码 | 错误 | 说明 |
|---|---|---|
| 401 | unauthorized | 缺少或无效的认证凭据 |
| 403 | forbidden | 凭据有效但无权访问该资源 |
通用错误
| 状态码 | 错误 | 说明 |
|---|---|---|
| 400 | bad_request | 请求参数格式错误 |
| 404 | not_found | 资源不存在 |
| 500 | internal_error | 服务器内部错误 |
小结
ORBEXA提供完整的API端点体系，覆盖UCP/ACP/MCP三大协议、OTR信任查询、三种平台集成和发现端点。Redis-backed限速系统通过令牌桶算法按端点类型分级保护，内部调用通过密钥认证跳过限速。返回：ORBEXA一体化解决方案