API 레퍼런스
박스히어로 앱 외부에서 박스히어로 내의 데이터를 조회하는 목적으로 사용할 수 있는 공개 API입니다.
데이터 수정 및 삭제 API는 추후 출시 예정입니다.
https://rest.boxhero-app.comcurl -X 'GET' \
'https://rest.boxhero-app.com/v1/products?location_ids=12345&location_ids=34567&limit=100' \
-H 'accept: application/json' \
-H 'Authorization: Bearer test-api-token-123'
[결제 및 설정] - [외부 서비스 연동 & API] 메뉴에서 API 토큰을 생성하실 수 있습니다. 모든 API 요청의
Authorization 헤더에 Bearer {API토큰} 형태로 포함해 주세요.안정적인 서비스 제공을 위해 요청 횟수를 아래와 같이 제한합니다.
- Endpoint별 1초당 5회의 쿼리가 가능합니다.
요청 횟수 제한을 초과한 경우 에러 메세지와 함께 아래 응답 헤더를 반환합니다.
X-Ratelimit-Limit- 분당 최대 쿼리 횟수X-Ratelimit-Remaining- 잔여 쿼리 횟수X-Ratelimit-Reset- 잔여 횟수 초기화까지 남은 시간 (초 단위)
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 : 오류의 유형을 식별할 수 있는 URL 형태의 코드입니다.
- title : 오류의 내용을 사람이 읽을 수 있는 형태로 제공합니다.
- 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 | 처리되지 못한 서버측 에러가 발생한 경우입니다. |
API가 예상과 다르게 작동하거나 부적절한 동작이 발생하는 경우, 아래에 명시된 이메일 주소로 응답 내용을 첨부하여 전송해 주시면 저희가 검토 후 적절한 조치를 취하도록 하겠습니다.
또한, 추가적인 API 개발에 대한 요청이 있으시다면 동일한 이메일로 연락 주시기 바랍니다.
get
/v1/teams/linked
Retrieves the information of the team linked to the current API token.
Parameters
No parameters
Responses
200: OK
get
/v1/products
Retrieve the list of products.
Parameters
Query
product_ids
array
The list of identifiers for the products to be filtered.
location_ids
array
The ids of the locations to be used for quantity calculation.
cursor
integer
points to a specific spot in the items, allowing clients to request the next set of items.
limit
number
the maximum number of items to be returned in a single request
Responses
200: OK
get
/v1/products/{product_id}
Retrieve information about a specific product.
Parameters
Path
product_id*
integer
The id of the product to be queried
Query
location_ids
array
The ids of the locations to be used for quantity calculation.
Responses
200: OK
get
/v1/product-attrs
Retrieves the list of product attribute specifications used within the team.
Parameters
No parameters
Responses
200: OK
get
/v1/locations
Retrieve the list of locations.
Parameters
No parameters
Responses
200: OK
get
/v1/locations/{location_id}
Retrieve information about a specific location.
Parameters
Path
location_id*
integer
The id of the location to be queried
Responses
200: OK
Last modified 1mo ago