公共 API

1. API 使用范围

a. API 支持的功能

公共 API 支持与 Wholesale 应用的主要功能交互，包括：

• 核心功能： Wholesale Pricing、Volume Pricing、Registration form、Quick Order Form、Quick Buy Collection、Quick Buy Variant
• 附加功能： Order Limit、Shipping Rate、Extra Fee、Payment Term（即将推出）

b. 支持的方法

API 通过以下 HTTP 方法支持完整的 CRUD 操作：

• GET – 获取数据
• POST – 创建新数据
• PUT – 更新现有数据
• DELETE – 删除数据

API 密钥可授予以下权限级别：Read Only/Write Only、Read & Write

支持的操作包括：Get list - Get item - Create item - Update item - Delete item

c. 支持的 Shopify 套餐：

满足以下要求的 Shopify 商店可使用 Wholesale 应用的公共 API：

• 必须是正式商店（不适用于开发商店或测试商店）
• 必须订阅 Gold 套餐

---

2. 身份验证

所有 API 请求在处理前都必须通过正确的身份验证。

a. 必填参数

每个 API 请求都必须包含以下必填参数：

参数	说明
shop	Shopify 商店域名（例如 mystore.myshopify.com）
api_key	在 Wholesale 应用中生成的 API 密钥

如果缺少其中任何一个参数，请求将被拒绝。

b. API 密钥管理

API 密钥直接在 Wholesale 应用的管理界面中创建和管理。
商店所有者可以为每个 API 密钥配置特定权限：Read only/Write only、Read & Write

---

3. API 结构与响应格式

a. API 端点

所有 API 请求都应使用以下基础 URL：

https://wholesale.samita.io/v1/

b. 各功能的专用端点

每个功能组都有各自的端点。例如：

• Wholesale 功能：

  https://wholesale.samita.io/v1/wholesale/

• Volume Pricing 功能：

  https://wholesale.samita.io/v1/volume/

（实际端点可能因具体功能而异。）

c. 支持的查询参数

API 支持多个通用查询参数：

参数	说明
status	记录的状态
page	分页的页码
limit	每页的记录数
sort	排序条件
query	搜索或筛选条件

请求示例：

GET /wholesale?page=1&limit=20&sort=created_at

---

4. 响应代码

每个 API 请求都会返回以下状态码之一：

a. 常见错误响应

401 – Unauthorized

可能的原因：

• 缺少商店 URL
• 缺少 API 密钥
• 商店 URL 无效
• API 密钥无效
• API 密钥与商店不匹配

---

403 – This action is unauthorized

• API 密钥无权执行所请求的操作
• View / Create / Update / Delete 权限不足

---

429 – Too Many Requests

• 已超出请求限制
• API 调用频率超出允许的速率限制

---

b. 成功响应

200 – Success

• 请求有效
• API 操作已成功执行
• 数据以正确的格式返回

---

5. 速率限制

为确保系统性能和稳定性，API 使用受每日请求限制约束。不再有针对单次请求或短时间间隔的限流，只要不超出您套餐的每日配额，就可以随时调用 API。

每日限制取决于商店的定价套餐：

套餐	每日请求限制
Free	每天 5 次请求
Starter	每天 50 次请求
Growth	每天 250 次请求
Enterprise	每天 500 次请求

每日计数器每天在午夜（服务器时间）重置。

如果超出每日限制，系统将返回：

429 – Too Many Requests

{
  "message": "Daily request limit exceeded (X requests/day)."
}