API 레퍼런스

박스히어로 앱 외부에서 박스히어로 내의 데이터를 조회하는 목적으로 사용할 수 있는 공개 API입니다.

Endpoint

https://rest.boxhero-app.com

요청 예시

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

Authorization

[결제 및 설정] - [외부 서비스 연동 & API] 메뉴에서 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 : 오류의 유형을 식별할 수 있는 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

처리되지 못한 서버측 에러가 발생한 경우입니다.

/errors/core/usage-limit-exceeded

사용량이 초과되어 요청을 처리할 수 없는 경우를 의미합니다. 해당 팀의 플랜을 업그레이드해주세요.

오류 보고 및 추가 개발 요청

API가 예상과 다르게 작동하거나 부적절한 동작이 발생하는 경우, 고객센터로 응답 내용을 첨부하여 전송해 주시면 검토 후 적절한 조치를 취하도록 하겠습니다.

또한, 추가적인 API 개발에 대한 요청이 있으실 경우에도 고객센터로 연락해주세요.

자주 묻는 질문들

목록 조회 시 일부 항목만 조회되는 경우

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

페이지네이션이 필요한지에 대한 여부는 API 문서 중 해당 엔드포인트의 요청 본문에 페이지네이션 관련 매개변수들이(has_more, cursor) 존재하는지 여부로 판단해주시면 됩니다.

  1. 페이지네이션 정보 확인

    • 페이지네이션이 필요한 목록 조회 API 응답에는 has_more와 cursor 필드가 포함되어 있습니다. - has_more 필드는 현재 페이지 이후에도 추가 데이터가 있는지 여부를 boolean 값으로 나타냅니다. - cursor 필드는 다음 페이지를 요청할 때 필요한 커서 값을 제공합니다.

  2. 다음 페이지 조회

    • has_more 값이 true인 경우 추가 페이지가 존재하는 것으로, 다음 페이지를 조회하려면 기존 요청의 파라미터에 cursor={응답받은 커서값}을 추가하여 요청해 주세요. 이렇게 하면 후속 데이터를 반환받을 수 있습니다.

  3. 전체 목록 조회

    • 전체 목록을 조회하려면 위 과정을 has_more가 false가 될 때까지 반복해 주세요.

API 문서 보기

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

Last updated