시작하기

베이스 URL

인증 개요

관리(Store) API는 OAuth 2.1을 따릅니다.

• 사람: GET /v1/oauth2/authorize(authorization_code + PKCE) → 외부 IdP 로그인 → userToken → token-exchange grant로 storeToken(스토어 스코프) 교환
• 서버(M2M): client_credentials grant(Basic 인증) → 스토어에 바인딩된 클라이언트라 storeToken이 곧바로 발급

셀러 계정 인증은 외부 IdP가 담당합니다. authorize로 보내면 IdP 로그인 화면이 뜨고, 인증이 끝나면 redirect_uri로 code가 돌아옵니다. 가입·이메일 인증·계정 잠금도 IdP 화면에서 처리됩니다. 호출하는 엔드포인트와 순서는 그대로입니다.

이후 상품/주문 등 모든 스토어 리소스는 Authorization: Bearer {storeToken}으로 호출합니다. storeToken이 테넌트를 결정하므로 경로에 storeId가 필요 없습니다.

스토어프론트 API는 X-Store-Code 헤더로 스토어를 지정합니다(없으면 mystore 스토어). 카탈로그·장바구니는 인증 없이 사용할 수 있고, 회원 전용 기능(/me/**)은 POST /storefront/v1/auth/login으로 받은 Access Token(Bearer)이 필요합니다.

데모 계정

mystore 스토어에 데모 데이터가 준비되어 있습니다. 데모 데이터는 주기적으로 초기화될 수 있습니다.

셀러 로그인은 외부 IdP 계정을 쓰므로 별도 데모 자격증명이 없습니다.

첫 API 호출

# 1) M2M 클라이언트로 storeToken 발급 (client_credentials, Basic 인증)
curl -u demo-client:demo-secret-key \
  https://api.sayren.app/v1/oauth2/token \
  -d "grant_type=client_credentials"

# 2) 발급받은 storeToken으로 관리 API 호출
curl https://api.sayren.app/v1/products \
  -H "Authorization: Bearer {access_token}"

# 3) 스토어프론트 상품 목록 (mystore 스토어, 인증 불필요)
curl https://api.sayren.app/storefront/v1/products -H "X-Store-Code: mystore"

표준 응답 구조

모든 응답(성공/실패)은 같은 엔벨로프로 반환됩니다.

{
  "meta": { "status": 200, "code": "OK", "message": "OK", "isSuccess": true },
  "data": { "...": "성공 데이터" },
  "error": null
}

실패 시에는 data가 null이고 error에 상세가 담깁니다.

{
  "meta": { "status": 409, "code": "INSUFFICIENT_STOCK", "message": "재고가 부족합니다", "isSuccess": false },
  "data": null,
  "error": { "code": "INSUFFICIENT_STOCK", "message": "재고가 부족합니다", "traceId": "..." }
}

• $.meta.status — HTTP 상태 코드, $.meta.isSuccess — 성공 여부
• $.meta.code — 성공 "OK", 실패 시 도메인 에러 코드(예: INSUFFICIENT_STOCK, TENANT_MISMATCH)
• $.error.traceId — 문의 시 전달용 추적 ID (fieldErrors가 포함될 수 있음)
• $.error.details — 일부 에러 코드에만 담기는 보조 데이터(선택). 없으면 필드가 빠지고, 모르는 키는 무시하면 됩니다
• $.error.message는 사람이 읽는 문구라 바뀔 수 있습니다. 분기는 code로 하세요
• 204 No Content 응답은 본문이 없습니다
• 예외: OAuth 토큰 엔드포인트(/v1/oauth2/*)는 RFC 6749 형식(평면 JSON, 실패 시 { "error", "error_description" })으로 응답합니다

공통 규칙

• 페이지네이션 — 목록 조회는 page/size 쿼리를 받고 $.data에 { page, size, totalElements, totalPages, contents }가 담깁니다.
• 일시 — ISO 8601, KST 오프셋 포함 (예: 2026-07-01T00:00:00+09:00)
• 멱등성 — 중복에 민감한 POST(발주 확인, 발송 등)는 Idempotency-Key 헤더를 지원합니다. 같은 키로 재호출하면 최초 응답이 재생됩니다.
• 일괄 처리 — 최대 100건, { succeeded, failed } 부분 성공으로 응답합니다.

다음 단계