> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ORBEXA API参考与限速策略

> ORBEXA REST API完整参考文档与限速策略详细说明：包含全部端点清单与调用代码示例、三种认证方式详解（API密钥认证、OAuth授权和插件Header认证）、请求速率限制规则与分页排序查询参数，覆盖商品管理、订单处理和平台集成配置相关接口的请求与响应格式

# API参考与限速

## 认证方式

ORBEXA支持三种认证方式：

### API密钥认证

适用于MCP工具调用和API访问：

```
Authorization: Bearer <api_key>
```

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对所有端点实施分层限速，确保公平使用和平台稳定性：

| 端点类型        | 限速       | 说明          |
| ----------- | -------- | ----------- |
| UCP端点       | 100次/分钟  | AI代理的主要访问入口 |
| API端点       | 60次/分钟   | 通用API调用     |
| 认证端点        | 10次/分钟   | 登录/注册等敏感操作  |
| Webhook端点   | 200次/分钟  | 接收平台事件通知    |
| WordPress插件 | 3次/分钟/IP | 插件连接和状态查询   |

超过限速后，API返回HTTP 429状态码。客户端应实现指数退避重试策略。

## 错误处理

### 限速错误

当请求超过限速时，API返回HTTP 429状态码：

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "retry_after": 30
}
```

`retry_after`字段指示客户端应等待的秒数。

### 认证错误

| 状态码 | 错误             | 说明           |
| --- | -------------- | ------------ |
| 401 | `unauthorized` | 缺少或无效的认证凭据   |
| 403 | `forbidden`    | 凭据有效但无权访问该资源 |

### 通用错误

| 状态码 | 错误               | 说明       |
| --- | ---------------- | -------- |
| 400 | `bad_request`    | 请求参数格式错误 |
| 404 | `not_found`      | 资源不存在    |
| 500 | `internal_error` | 服务器内部错误  |

## 小结

ORBEXA提供完整的API端点体系，覆盖UCP/ACP/MCP三大协议、OTR信任查询、三种平台集成和发现端点。限速系统按端点类型分级保护，确保公平使用和平台稳定性。

***

下一章：[商家控制台](/zh/book-7/ch9-dashboard) — KPI监控、集成管理、数据质量和团队权限