# API

<figure><img src="/files/f7d3bb607334cb046206f2e5c368901c9c83b270" alt=""><figcaption></figcaption></figure>

***

## **API 参考**

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

***

## 端点

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

## **身份验证**

所有 API 请求都必须包含一个 **Authorization** **头** 以及一个 **Bearer** **令牌**:

```
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 改进和新功能需求提供反馈。

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/documentation/zh/ji-cheng/open-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.