# 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トークン**</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'
```

## レート制限

システムの安定性を確保するため、以下のレート制限を設けています:

* 各エンドポイントにつき1秒あたり5件のクエリ。

レート制限に達すると、以下を含むエラーメッセージが表示されます:

* `X-Ratelimit-Limit` - 1分あたりの最大クエリ数
* `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>Basicモード</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がページネーションによって1回のリクエストで返されるアイテム数を制限します。カーソルベースのページネーションを使用しています:

{% hint style="info" %}
ページネーションが必要かどうかを判断するには、APIドキュメント内の該当エンドポイントのリクエスト本文にページネーション関連のパラメータがあるかを確認してください。
{% endhint %}

#### **ページネーションパラメータ**

* `has_more` ：現在のページを超えてさらにデータが存在するかどうかを示すブール値。
* `cursor` ：次のページを取得するためのカーソル値を提供します。

#### **次のページの取得**

* を確認します `has_more` が `true`であること。これは次のページが利用可能であることを意味します。
* もし `true`であれば、 `cursor={受け取ったカーソル値}` をパラメータに含めて再度リクエストを送信します。これにより次のデータが返されます。
* まで繰り返します `has_more` が `false` になれば、全件の一覧を取得できます。

***

## サポートとフィードバック

問題が発生した場合や追加のAPI機能が必要な場合は、 [サポートチーム](https://docs-en.boxhero.io/etc/contact)までご連絡ください。APIの改善や新機能のご要望もぜひお寄せください。