API

BoxHero 的 API 允许开发者将我们的库存管理能力与外部应用集成，以便高效获取数据并进行交互。

BoxHero’s API: A Simple Way to Integrate Your Inventory DataBoxHero Blog

---

API 参考

如需查看详细的端点文档，请访问： https://rest.boxhero-app.com/docs/api

---

端点

所有 API 请求都应发送到以下基础 URL： https://rest.boxhero-app.com

身份验证

所有 API 请求都必须包含一个 Authorization 请求头，携带 Bearer 令牌:

Authorization: Bearer {API_TOKEN}

要获取 API 令牌：

1. 在桌面端（Web）登录您的 BoxHero 账户。

2. 导航到 设置 > 集成.

3. 生成一个新的 API 令牌。

发起请求

以下是一个用于检索产品的 API 请求示例。

curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'

速率限制

为确保系统稳定，我们实施以下速率限制：

• 每个端点每秒 5 次查询。

一旦触发速率限制，您将看到以下错误信息：

• X-Ratelimit-Limit - 每分钟最大查询次数

• X-Ratelimit-Remaining - 剩余查询次数

• X-Ratelimit-Reset - 距离查询次数重置还剩的时间（秒）

---

响应

成功

HTTP 状态码在 200 范围内的响应表示 API 处理成功。

错误

状态码在 400 或 500 范围内表示 API 请求失败：

• 400 范围：由于请求中提供的信息导致的客户端错误（例如，缺少必需参数）。

• 500 范围：服务器端错误。

错误响应示例：

{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "身份验证令牌无效。请提供有效的令牌。",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}

• id： 用于唯一标识错误的 ID。

• type： 以 URL 形式表示的代码，用于标识错误类型。

• title： 以人类可读的形式提供错误内容。

• correlation_id： 指向与该错误相关联的请求 ID。

• 其他： 可能会包含其他字段以提供更多信息，例如示例中的“given”。

常见错误类型

类型	说明
/errors/not-found	未找到请求的资源（例如，不存在具有特定 ID 的条目）。
/errors/invalid-request	请求中的参数无效。
/errors/invalid-team-mode	在当前团队模式下无法处理所请求的查询（例如，在 库位 中使用 基础模式).
/errors/tokens/required	缺少 API 令牌。
/errors/tokens/invalid	API 令牌无效（例如，API 令牌已过期）。
/errors/too-many-requests	超过了速率限制。
/errors/unhandled	未解决的服务器端错误。
/errors/core/usage-limit-exceeded	已达到使用上限。需要升级方案。

分页

对于返回大量数据集的端点（例如，条目列表、交易列表），列表视图 API 通过分页限制单次请求返回的条目数量。我们使用基于游标的分页：

要判断是否需要分页，请查看 API 文档中该端点请求体里是否包含与分页相关的参数。

分页参数

• has_more ：一个布尔值，表示当前页之后是否还有更多数据。

• cursor ：提供用于获取下一页的游标值。

获取下一页

• 检查 has_more 是否 true。这表示还有下一页可用。

• 如果 true，发送另一条请求并包含 cursor={接收到的游标值} 作为参数。这将返回后续数据。

• 重复此操作直到 has_more 是否 false 以获取完整列表。

---

支持与反馈

如果您遇到问题或需要额外的 API 功能，请联系我们的 支持团队。我们欢迎您对 API 改进和新功能需求提供反馈。