인증

모든 Public API 요청에는 Bearer 토큰이 필요합니다. 채널 자격 증명과 창고 코드는 개발자 포털에서 관리하며, 클라이언트 앱에 절대 포함하지 마세요.

API 키 {#api-keys}

앱이 승인된 뒤 Developer Portal → API Keys에서 키를 생성합니다.

항목설명
형식Authorization: Bearer hio_live_…(프로덕션) 또는 포털에서 발급한 테스트 키
범위앱당 키 1개입니다. 쿼터와 채널 접근 권한은 앱의 구독 플랜을 따릅니다.
순환유출된 키는 즉시 폐기하세요. 프로덕션에서는 폐기 전에 대체 키를 먼저 생성합니다.
저장서버 측에만 저장합니다. 모바일 앱, 브라우저 JS, 공개 저장소에 키를 노출하지 마세요.

요청 예시

curl https://api.hiobuy.com/v1/products/detail \
  -H "Authorization: Bearer hio_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }'

채널 인증(사전 조건) {#channel-authorization}

API 키만으로는 충분하지 않습니다. 각 앱은 해당 마켓플레이스의 상품 또는 주문 API를 호출하기 전에 채널 인증을 완료해야 합니다.

모드설정 항목Gateway가 사용하는 항목
Self fulfillment포털의 채널별 OAuth 또는 토큰 JSON앱 + 채널별 저장 토큰
HIOBuy warehouse창고 개발자 코드 1개서버 측 코드 + 관리형 토큰, 구매/풀필먼트는 HIOBuy로 전달

포털 인증을 참고하세요. 채널이 인증되지 않은 경우 호출은 401 CHANNEL_NOT_AUTHORIZED를 반환합니다(Errors).

절대 보내지 말아야 할 값 {#what-not-to-send}

  • Taobao / 1688 / Weidian 액세스 토큰 또는 리프레시 토큰
  • 창고 개발자 코드(Gateway가 풀필먼트 라우트에 첨부)
  • Public API 호출의 포털 세션 JWT

요청 추적 {#tracing}

모든 응답에는 다음이 포함됩니다.

  • x-request-id 헤더 — JSON 본문의 request_id와 연결
  • 과금 대상 라우트의 선택적 쿼터 헤더 — Rate limits 참고

HIOBuy 지원팀에 문의할 때 x-request-id를 포함하세요.

일반적인 인증 오류 {#auth-errors}

HTTP코드의미
401INVALID_API_KEYBearer 토큰이 없거나, 폐기되었거나, 형식이 잘못됨
401CHANNEL_NOT_AUTHORIZED앱이 포털에서 요청 채널을 인증하지 않음
403INSUFFICIENT_SCOPE키 또는 앱에 작업 권한이 없음
403FULFILLMENT_MODE_NOT_SUPPORTED앱이 self-fulfillment 모드인데 Fulfillment API를 호출함