API

박스히어로 공개 API를 활용하면 외부 서비스에서도 박스히어로 데이터를 조회하고 관리할 수 있습니다.

---

---

API Token 발급

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

API 레퍼런스

BoxHero Open APIrest.boxhero.io

Endpoint

https://rest.boxhero-app.comrest.boxhero-app.com

요청 예시

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

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

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

Rate limits

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

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

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

• X-Ratelimit-Limit : 분당 최대 쿼리 횟수

• X-Ratelimit-Remaining : 잔여 쿼리 횟수

• X-Ratelimit-Reset : 잔여 횟수 초기화까지 남은 시간 (초 단위)

Response

성공

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

실패

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

• 400 범위 내의 상태 코드는 요청에 포함된 정보의 문제로 처리가 실패한 경우를 의미합니다. (예: 필수 매개변수의 누락)

• 500 범위 내의 상태 코드는 서버 문제로 요청이 처리되지 못했음을 의미합니다.

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

{
  "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"
}

id	오류를 식별할 수 있는 고유한 ID입니다.
type	오류의 내용을 사람이 읽을 수 있는 형태로 제공합니다.
correlation_id	해당 오류와 연관된 요청의 ID를 가리킵니다.
기타	예시에 등장한 'given'과 같이 부가 정보를 제공하기 위해 추가적인 필드가 포함될 수 있습니다.

대표적인 오류 유형

Type	Description
/errors/not-found	요청한 자원을 찾을 수 없는 경우 발생합니다. (예: 특정 ID의 제품이 존재하지 않음)
/errors/invalid-request	요청과 함께 제공된 매개변수 등에 오류가 있음을 의미합니다. (응답 중 'errors' 필드에 매개변수별 오류들이 포함됩니다.)
/errors/invalid-team-mode	요청한 쿼리가 현재 팀 모드에서 처리될 수 없는 경우 발생합니다. (예: 기본 모드에서 위치 조회 API를 사용함)
/errors/tokens/required	요청을 처리하는 데 API 토큰이 필요한데, 토큰이 제공되지 않은 경우 발생합니다.
/errors/tokens/invalid	제공된 API 토큰이 잘못된 경우 발생합니다. (예: API 토큰이 만료됨)
/errors/too-many-requests	Rate limit을 초과한 요청이 발생한 경우입니다.
/errors/unhandled	처리되지 못한 서버측 에러가 발생한 경우입니다.
/errors/core/usage-limit-exceeded	사용량이 초과되어 요청을 처리할 수 없는 경우를 의미합니다. 해당 팀의 플랜을 업그레이드해주세요.

오류 보고 및 문의

API가 예상과 다르게 작동하거나 부적절한 동작이 발생하는 경우, 응답 내용을 첨부해 고객센터로 문의해 주세요.

Webhook

Webhook | BoxHero User Guidewww.boxhero.io

---

FAQ

박스히어로 API에 대해 자주 묻는 질문은 아래에서 확인하실 수 있습니다.

API

---