# API

{% embed url="<https://www.boxhero.io/en/blog/boxhero-open-api-integrate-inventory-data>" %}

***

## **API 参考**

有关详细的端点文档，请访问： <https://rest.boxhero.io/docs/api>

***

## 端点

所有 API 请求都应发送到以下基础 URL：\ <mark style="color:蓝色;"><https://rest.boxhero-app.com></mark>

## **身份验证**

所有 API 请求都必须包含一个 <mark style="color:蓝色;">**Authorization**</mark> 标头，带有一个 <mark style="color:蓝色;">**Bearer token**</mark>:

```
Authorization: Bearer {API_TOKEN}
```

要获取 API 令牌：

1. 在桌面端（Web）登录您的 BoxHero 账户。
2. 导航到 <mark style="color:蓝色;">**`设置`**</mark> > <mark style="color:蓝色;">**`集成`**</mark>.
3. 生成一个新的 API 令牌。

## **发起请求**

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

```bash
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 范围：服务器端错误。

**错误响应示例：**

```json
{
  "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*”。

### 常见错误类型

<table><thead><tr><th width="252">类型</th><th>描述</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>未找到请求的资源（例如，具有特定 ID 的项目不存在）。</td></tr><tr><td>/errors/invalid-request</td><td>请求中的参数无效。</td></tr><tr><td>/errors/invalid-team-mode</td><td>由于当前团队模式，无法处理所请求的查询（例如，在 <em>location</em> 查找 API 中使用 <em>基础模式</em>).</td></tr><tr><td>/errors/tokens/required</td><td>缺少 API 令牌。</td></tr><tr><td>/errors/tokens/invalid</td><td>无效的 API 令牌（例如，API 令牌已过期）。</td></tr><tr><td>/errors/too-many-requests</td><td>已超过速率限制。</td></tr><tr><td>/errors/unhandled</td><td>未解析的服务器端错误。</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>已达到使用上限。需要升级方案。</td></tr></tbody></table>

## 分页

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

{% hint style="info" %}
要确定是否需要分页，请检查 API 文档中该端点请求体中是否存在与分页相关的参数。
{% endhint %}

#### **分页参数**

* `has_more` ：一个布尔值，表示当前页面之外是否还有更多数据。
* `cursor` ：提供用于获取下一页的游标值。

#### **获取下一页**

* 检查 `has_more` 是否为 `true`。这表示还有另一页可用。
* 如果 `true`，请发送另一请求并在参数中包含 `cursor={received cursor value}` 。这将返回后续数据。
* 重复此过程直到 `has_more` 是否为 `false` ，以获取完整列表。

***

## 支持与反馈

如果您遇到问题或需要额外的 API 功能，请联系我们的 [支持团队](https://docs-en.boxhero.io/etc/contact)。我们欢迎您对 API 改进和新功能需求提出反馈。