# 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>