shop24 Docs

Store API 개요

관리(셀러) API 레퍼런스

온라인쇼핑몰 멀티테넌트 관리 Open API입니다. 스토어 = 테넌트.

베이스 URL

https://shop.api.avarlabs.com/v1

인증 — OAuth 2.1

두 가지 진입 경로가 있으며, 최종적으로 모든 테넌트 리소스는 storeToken으로 호출합니다 (경로에 storeId 불필요 — 토큰이 테넌트를 결정).

사람(인터랙티브) — authorization_code + PKCE:

  1. GET /oauth2/authorize — PKCE(S256)·state 필수. 로그인 후 redirect_uri로 code 전달
  2. POST /oauth2/token (grant_type=authorization_code) → userToken (+offline_access scope 요청 시 refresh token, rotation 방식)
  3. GET /me/stores → 소속 스토어 목록
  4. POST /oauth2/token (grant_type=urn:ietf:params:oauth:grant-type:token-exchange, audience={storeId}) → storeToken (role→scopes 자동)

서버(M2M) — client_credentials:

curl -u {client_id}:{client_secret} https://shop.api.avarlabs.com/v1/oauth2/token \
  -d "grant_type=client_credentials&scope=product:r order:r"

클라이언트가 스토어에 바인딩되어 있어 storeToken이 곧바로 발급됩니다(scope로 다운스코프 가능). 데모 클라이언트: demo-client / demo-secret-key

API 토큰(PAT) — OAuth 클라이언트 등록 없이 쓰는 사전발급 Bearer(스크립트·CI·LLM 연동):

  • POST /store/api-tokens { name, scopes, expiresInDays? } — OWNER/ADMIN이 발급. 평문 토큰(s24_pat_…)은 생성 응답에서 한 번만 노출됩니다
  • 발급된 토큰은 storeToken과 동일하게 Authorization: Bearer로 사용합니다
  • GET /store/api-tokens(목록), DELETE /store/api-tokens/{tokenId}(즉시 폐기)
  • 스코프는 {리소스}:{r|rw} — 읽기 전용(product:r 등)으로 최소 권한 발급을 권장합니다

클라이언트 등록(DCR) — 자체 OAuth 클라이언트가 필요하면 직접 등록할 수 있습니다(RFC 7591):

curl https://shop.api.avarlabs.com/v1/oauth2/register \
  -H "Authorization: Bearer {storeToken}" \
  -d '{ "client_name": "내 연동 앱", "grant_types": ["client_credentials"], "scope": "product:r order:r" }'
  • OWNER/ADMIN의 storeToken으로만 등록할 수 있습니다 (API 토큰·M2M 토큰 불가)
  • token_endpoint_auth_method: "none"이면 public 클라이언트(시크릿 없음, PKCE 로그인용) — 이때 redirect_uris는 https(개발용 루프백 http 허용)여야 합니다
  • confidential 클라이언트는 등록한 스토어에 바인딩되며, client_secret은 등록 응답에서 한 번만 노출됩니다
  • 부여 scope는 등록자가 보유한 scope 이내로 제한되고, 토큰 발급은 등록한 grant_types로만 가능합니다

구매자 위임 — 자체 회원 시스템을 가진 연동사가 구매자용 토큰을 위임 발급받는 경로:

curl -u {client_id}:{client_secret} https://shop.api.avarlabs.com/v1/oauth2/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token_type=urn:shop24:params:oauth:token-type:member-ref" \
  -d "subject_token=buyer@example.com"
  • 스토어에 바인딩된 confidential 클라이언트 + member:delegate scope가 필요합니다
  • 구매자를 이메일로 지목하면 해당 스토어의 회원 토큰(30분)이 발급됩니다 — 미등록 이메일은 자동으로 회원이 생성됩니다
  • refresh token은 발급되지 않습니다 — 만료 시 서버가 같은 요청으로 재발급받으세요. 이 호출은 반드시 서버에서만 수행해야 합니다(클라이언트 시크릿 보호)

/oauth2/* 엔드포인트는 RFC 6749 형식(평면 JSON)으로 응답합니다 — 표준 엔벨로프의 예외. 실패는 { "error", "error_description" } 형식입니다.

크로스 테넌트 접근 시 403 TENANT_MISMATCH, 역할 권한 부족 시 403 INSUFFICIENT_ROLE.

TypeScript에서는 @shop24/store-sdk가 이 플로우를 캡슐화합니다.

공통 규칙

  • 모든 응답은 표준 엔벨로프 — $.meta(status/code/message/isSuccess) + 성공 $.data / 실패 $.error
  • 리소스는 복수형 명사, 상태 전이는 서브리소스 POST
  • 목록 조회: page/size 페이지네이션
  • 주문/발송/클레임은 OrderItem 단위 처리
  • 일시는 ISO 8601 (KST 오프셋 포함)
  • 일괄 처리 최대 100건, 부분 성공 응답
  • 중복에 민감한 POST는 Idempotency-Key 헤더 지원

List GET

Next Page

On this page

베이스 URL인증 — OAuth 2.1공통 규칙