API 기본 사항

API나 SDK를 쓰기 전에 알아 둘 공통 규칙입니다. 처음이라면 시작하기부터 보십시오.

API	베이스 URL
관리 API	`https://api.sayren.app/v1`
스토어프론트 API	`https://api.sayren.app/storefront/v1`

인증 개요

관리 API는 Sayren 계정 토큰으로 부릅니다. Authorization: Bearer {계정 토큰}에 더해 부를 상점을 X-Store-Id 헤더로 지정합니다. 토큰은 계정에 발급되어 소속된 여러 상점에 쓸 수 있으므로 경로에는 storeId가 없습니다.

호출 주체	받는 방법
스크립트·CI·서버	Sayren 계정 › 액세스 토큰에서 만든 액세스 토큰
사람(상점 플랫폼·CLI·원격 MCP·연동 앱)	Sayren 계정 로그인과 권한 허용(OAuth 2.1 authorization code + PKCE)으로 받는 로그인 토큰

토큰 종류, 스코프, 오류 코드는 인증과 계정 토큰에 있습니다. 상점 API 토큰(sy_pat_…)과 storeToken은 더 이상 받지 않습니다(401 TOKEN_TYPE_RETIRED).

스토어프론트 API는 요청마다 상점을 지정합니다. 회원 기능(/me/**)만 구매자 Access Token이 필요합니다(구매자 인증).

상점 지정

관리 API는 X-Store-Id 헤더로 상점을 정합니다. 빠뜨리면 400 STORE_ID_REQUIRED, 토큰의 상점 범위 밖이면 403 STORE_NOT_GRANTED입니다. 상점 id는 GET /v1/me/stores로 봅니다.

스토어프론트 API는 아래 순서로 정합니다.

순서	값	설명
1	`X-Store-Code` 헤더	SDK의 `storeCode` 옵션이 이 헤더를 붙입니다
2	요청 호스트의 첫 레이블	헤더가 없을 때만 봅니다. `my-shop.example.com`이면 `my-shop`

api.sayren.app을 호출할 때는 항상 X-Store-Code를 보내십시오. 빠뜨리면 첫 레이블 api로 찾아 404 STORE_NOT_FOUND입니다. 닫은 상점은 410 STORE_CLOSED, 정지된 상점은 503 STORE_SUSPENDED입니다.

상점 코드는 설정 › 상점 정보의 기본 정보 카드에 있습니다. 예제의 {상점 코드}를 이 값으로 바꿔 쓰십시오.

자격 증명 준비

호출할 API	필요한 값	받는 곳
관리 API	액세스 토큰과 상점 id	Sayren 계정 › 액세스 토큰, 상점 플랫폼 개발자 › 개요
스토어프론트 API (카탈로그·장바구니)	상점 코드	설정 › 상점 정보
스토어프론트 API (회원 기능)	위에 더해 구매자 Access Token	`POST /storefront/v1/auth/login`

액세스 토큰은 Sayren 계정(accounts.sayren.app)에서 만듭니다. 상점 플랫폼의 개발자 › 자격 증명 › 액세스 토큰을 눌러도 이동합니다.

토큰 만들기를 누릅니다.
토큰 이름, 필요한 권한, 상점 범위, 만료를 고릅니다.
토큰은 만든 직후 한 번만 보이니 바로 복사합니다.

첫 API 호출

# 관리 API — 내 상품 목록
curl https://api.sayren.app/v1/products \
  -H "Authorization: Bearer {액세스 토큰}" \
  -H "X-Store-Id: {storeId}"

# 스토어프론트 API — 인증 없음, 상점 코드 필수
curl https://api.sayren.app/storefront/v1/products \
  -H "X-Store-Code: {상점 코드}"

상품이 없으면 contents가 빈 배열입니다(상품·옵션·재고 관리).

데모 상점으로 응답 미리 보기

상점을 만들기 전에는 데모 상점 코드 rk6dzy3b49k0으로 카탈로그(/products, /products/{productId})를 조회해 응답 형태를 봅니다. 데모 데이터는 예고 없이 바뀝니다. 상품 등록·결제·테스트 주문은 내 상점에서 합니다.

표준 응답 구조

모든 응답은 같은 엔벨로프입니다. 성공이면 data, 실패면 error가 채워집니다.

{
  "meta": { "status": 409, "code": "INSUFFICIENT_STOCK", "message": "재고가 부족합니다", "isSuccess": false },
  "data": null,
  "error": {
    "code": "INSUFFICIENT_STOCK",
    "message": "재고가 부족합니다",
    "traceId": "...",
    "docs": "https://docs.sayren.app/guides/products#3-재고-변경"
  }
}

필드	뜻
`meta.status` · `meta.isSuccess`	HTTP 상태 코드, 성공 여부
`meta.code`	성공은 `OK`, 실패는 도메인 에러 코드
`error.code`	분기 기준. `error.message`는 바뀔 수 있으니 분기에 쓰지 마십시오
`error.traceId`	문의할 때 전달하는 추적 ID
`error.fieldErrors` · `error.details`	입력 검증 필드 오류, 코드별 보조 데이터(선택). 모르는 키는 무시합니다
`error.docs`	그 코드의 문서 주소(선택). SDK에서는 `ApiError.docs`

204 No Content는 본문이 없습니다. /.well-known/* 메타데이터는 엔벨로프 없는 평면 JSON입니다.

공통 규칙

페이지네이션 — page·size 쿼리. data는 { page, size, totalElements, totalPages, contents }입니다.
일시 — ISO 8601이고 시간대가 붙습니다. 요청에는 Z나 +09:00을 붙여 보냅니다. 날짜만 받는 쿼리는 KST 기준 YYYY-MM-DD입니다.
멱등성 — 발주 확인·발송 같은 POST는 Idempotency-Key를 받습니다. 같은 키로 다시 부르면 첫 응답을 돌려줍니다.
일괄 처리 — 최대 100건, { succeeded, failed } 부분 성공입니다.

인증 개요

상점 지정

자격 증명 준비

첫 API 호출

데모 상점으로 응답 미리 보기

표준 응답 구조

공통 규칙

다음 단계

Storefront SDK

Store SDK

관리 API 레퍼런스

스토어프론트 API 레퍼런스

이 페이지 목차