# API

***

<figure><img src="https://3639913499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnmQcxJVYbkAeUq7yQCkF%2Fuploads%2Fgit-blob-febb93a660b525ae10c310553bdb1d7b4265d973%2Fimage%20(202).png?alt=media" alt="박스히어로 api 연동하기 대표 이미지"><figcaption></figcaption></figure>

***

## API 레퍼런스 <a href="#api-reference" id="api-reference"></a>

<https://rest.boxhero-app.com/docs/api>

## Endpoint <a href="#endpoint" id="endpoint"></a>

{% embed url="<https://rest.boxhero-app.com>" %}

#### 요청 예시 <a href="#eg-request" id="eg-request"></a>

```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'
```

## Authorization <a href="#authorization" id="authorization"></a>

`설정` > `연동 설정`에서 API 토큰을 생성할 수 있습니다.

모든 API 요청의 `Authorization` 헤더에 `Bearer {API토큰}` 형태로 포함해 주세요.

## Rate limits <a href="#rate-limits" id="rate-limits"></a>

안정적인 서비스 제공을 위해 요청 횟수를 아래와 같이 제한합니다.

* Endpoint별로 1초당 5회의 쿼리가 가능합니다.

요청 횟수 제한을 초과하면 오류메세지와 함께 아래 응답 헤더를 반환합니다.

* `X-Ratelimit-Limit` : 분당 최대 쿼리 횟수
* `X-Ratelimit-Remaining` : 잔여 쿼리 횟수
* `X-Ratelimit-Reset` : 잔여 횟수 초기화까지 남은 시간 (초 단위)

## Response <a href="#response" id="response"></a>

### 성공

HTTP 상태 코드가 200 범위인 경우, API 요청이 정상적으로 처리되었음을 의미합니다.

### 실패

HTTP 상태 코드가 400 혹은 500 범위 내에 있는 응답은 요청의 처리가 실패했음을 의미합니다.

* 400 범위 내의 상태 코드는 요청에 포함된 정보의 문제로 처리가 실패한 경우를 의미합니다. (예: 필수 매개변수의 누락)
* 500 범위 내의 상태 코드는 서버 문제로 요청이 처리되지 못했음을 의미합니다.

박스히어로 REST API에서 발생하는 모든 오류 응답은 아래 형식을 따릅니다.

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Authentication token is invalid. Please provide a valid token.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}
```

<table data-header-hidden><thead><tr><th width="166.5714111328125"></th><th></th></tr></thead><tbody><tr><td><strong>id</strong></td><td>오류를 식별할 수 있는 고유한 ID입니다.</td></tr><tr><td><strong>type</strong></td><td>오류의 내용을 사람이 읽을 수 있는 형태로 제공합니다.</td></tr><tr><td><strong>correlation_id</strong></td><td>해당 오류와 연관된 요청의 ID를 가리킵니다.</td></tr><tr><td><strong>기타</strong></td><td>예시에 등장한 'given'과 같이 부가 정보를 제공하기 위해 추가적인 필드가 포함될 수 있습니다.</td></tr></tbody></table>

### 대표적인 오류 유형 <a href="#common-error-types" id="common-error-types"></a>

<table><thead><tr><th width="252">Type</th><th>Description</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>요청한 자원을 찾을 수 없는 경우 발생합니다. (예: 특정 ID의 제품이 존재하지 않음)</td></tr><tr><td>/errors/invalid-request</td><td>요청과 함께 제공된 매개변수 등에 오류가 있음을 의미합니다. (응답 중 'errors' 필드에 매개변수별 오류들이 포함됩니다.)</td></tr><tr><td>/errors/invalid-team-mode</td><td>요청한 쿼리가 현재 팀 모드에서 처리될 수 없는 경우 발생합니다. (예: 기본 모드에서 위치 조회 API를 사용함)</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>Rate limit을 초과한 요청이 발생한 경우입니다.</td></tr><tr><td>/errors/unhandled</td><td>처리되지 못한 서버측 에러가 발생한 경우입니다.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>사용량이 초과되어 요청을 처리할 수 없는 경우를 의미합니다. 해당 팀의 플랜을 업그레이드해주세요.</td></tr></tbody></table>

## 오류 보고 및 문의 <a href="#pagination" id="pagination"></a>

API가 예상과 다르게 작동하거나 부적절한 동작이 발생하는 경우, 응답 내용을 첨부해 [**고객센터**](https://www.boxhero.io/docs/documentation/ko/contact)로 문의해 주세요.

***

## <mark style="color:$info;">FAQ</mark> <a href="#faq" id="faq"></a>

### <mark style="color:$info;">목록 조회 시 일부 항목만 조회되는 경우</mark> <a href="#pagination" id="pagination"></a>

<mark style="color:$info;">목록 조회 API는 대상 자원의 양이 많아질 수 있는 경우(예: 제품 목록, 트랜잭션 목록) 페이지네이션을 통해 한 번의 요청으로 반환되는 항목 수를 제한합니다. 저희 API는 커서 기반 페이지네이션 방식을 사용하고 있으며, 다음 페이지의 목록을 조회하려면 아래와 같은 방법을 참고해 주세요.</mark>

{% hint style="info" %} <mark style="color:$info;">페이지네이션 필요 여부는 API 문서 중 해당 엔드포인트의 요청 본문에 페이지네이션 관련 매개변수들이(has\_more, cursor) 존재하는지 여부로 판단해주시면 됩니다.</mark>
{% endhint %}

1. <mark style="color:$info;">**페이지네이션 정보 확인**</mark>
   * <mark style="color:$info;">페이지네이션이 필요한 목록 조회 API 응답에는</mark> <mark style="color:$info;">`has_more`</mark><mark style="color:$info;">와</mark> <mark style="color:$info;">`cursor`</mark> <mark style="color:$info;">필드가 포함되어 있습니다.</mark>\ <mark style="color:$info;">-</mark> <mark style="color:$info;">`has_more`</mark> <mark style="color:$info;">필드는 현재 페이지 이후에도 추가 데이터가 있는지 여부를 boolean 값으로 나타냅니다.</mark>\ <mark style="color:$info;">-</mark> <mark style="color:$info;">`cursor`</mark> <mark style="color:$info;">필드는 다음 페이지를 요청할 때 필요한 커서 값을 제공합니다.</mark>
2. <mark style="color:$info;">**다음 페이지 조회**</mark>
   * <mark style="color:$info;">`has_more`</mark> <mark style="color:$info;">값이</mark> <mark style="color:$info;">`true`</mark><mark style="color:$info;">인 경우 추가 페이지가 존재하는 것으로, 다음 페이지를 조회하려면 기존 요청의 파라미터에</mark> <mark style="color:$info;">`cursor={응답받은 커서값}`</mark><mark style="color:$info;">을 추가하여 요청해 주세요. 이렇게 하면 후속 데이터를 반환받을 수 있습니다.</mark>
3. <mark style="color:$info;">**전체 목록 조회**</mark>
   * <mark style="color:$info;">전체 목록을 조회하려면 위 과정을</mark> <mark style="color:$info;">`has_more`</mark><mark style="color:$info;">가 false가 될 때까지 반복해 주세요.</mark>


---

# 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/ko/etc/settings/integrations/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.