관리 API 개요

셀러가 상점을 운영하는 멀티테넌트 API입니다. 베이스 URL은 https://api.sayren.io/v1입니다. TypeScript에서는 @sayren/store-sdk를 씁니다.

인증 — Sayren 계정 토큰

관리 API는 Sayren 계정(accounts.sayren.io)이 발급한 토큰으로 부릅니다. 토큰은 계정에 발급되므로 부를 상점을 요청마다 X-Store-Id 헤더로 고릅니다. 경로에는 storeId가 없습니다.

curl https://api.sayren.io/v1/products \
  -H "Authorization: Bearer {계정 토큰}" \
  -H "X-Store-Id: {storeId}"

토큰	받는 곳	쓰는 곳
액세스 토큰	Sayren 계정 › 액세스 토큰	스크립트·CI·서버 연동·로컬 MCP
로그인 토큰	Sayren 계정 로그인과 권한 허용(OAuth 2.1 authorization code + PKCE)	상점 플랫폼·CLI·원격 MCP·연동 앱

인가 서버 정보는 GET https://api.sayren.io/.well-known/oauth-protected-resource(RFC 9728)에 있고, 인가 서버는 Sayren 계정입니다.
소속 상점은 GET /me/stores(X-Store-Id 없이, 권한 stores:read)로 봅니다.
권한은 그 상점에서의 역할과 토큰에 허락한 스코프 중 좁은 쪽입니다.

코드	상황
`400 STORE_ID_REQUIRED`	`X-Store-Id` 없음
`401 UNAUTHORIZED` · `401 TOKEN_REVOKED`	토큰 없음·만료·형식 오류, 폐기된 토큰
`401 TOKEN_TYPE_RETIRED`	옛 토큰(상점 API 토큰 `sy_pat_…`, storeToken)
`410 TOKEN_TYPE_RETIRED`	없어진 경로(`/oauth2/*`, `/store/api-tokens`, `/store/api-clients`)
`403 STORE_NOT_GRANTED`	토큰의 상점 범위 밖
`403 INSUFFICIENT_ROLE` · `403 INSUFFICIENT_SCOPE`	역할·토큰 권한 부족
`403 TENANT_MISMATCH`	다른 상점의 리소스

토큰 만들기, 폐기, 연결된 앱, 옛 토큰에서 옮기는 순서는 인증과 계정 토큰에 있습니다.

구매자 위임 — 자체 회원 시스템이 있는 연동사가 서버에서 구매자 토큰을 받습니다.

curl -X POST https://api.sayren.io/v1/customers/delegations \
  -H "Authorization: Bearer {액세스 토큰}" \
  -H "X-Store-Id: {storeId}" \
  -H "Content-Type: application/json" \
  -d '{ "uid": "{사용자 id}", "email": "buyer@example.com", "name": "홍길동" }'

역할 스코프 customer:rw와 토큰의 member:delegate(구매자 위임)가 필요합니다. 액세스 토큰을 만들 때 구매자 위임을 켭니다.
계정 액세스 토큰과 Sayren 상점 플랫폼·CLI 로그인만 부를 수 있습니다. 다른 앱의 로그인 토큰과 AI 에이전트는 403 DELEGATION_NOT_ALLOWED입니다.
처음 보는 uid면 구매자를 만들고(email·name은 이때만 씀) 같은 uid는 늘 같은 구매자입니다. uid 없이 email만 보내면 이메일로 찾고, 없으면 만듭니다.
구매자 토큰은 30분이고 refresh token이 없어 만료되면 같은 요청으로 다시 받습니다. 서버에서만 부릅니다.
SDK 헬퍼는 자체 회원 연동에 있습니다.

스코프

형식은 {리소스}:{r|rw}이고 rw는 r을 포함합니다. 실제 권한은 역할의 스코프와 토큰에 허락한 스코프의 교집합입니다.

리소스	접근 수준	OWNER	ADMIN	STAFF
`product` `category` `order` `claim` `inquiry` `review`	`r` `rw`	`rw`	`rw`	`rw`
`customer` `promotion`	`r` `rw`	`rw`	`rw`	`r`
`webhook` `store` `member` `storefront`	`r` `rw`	`rw`	`rw`	—
`analytics` `audit`	`r`	`r`	`r`	—
`settlement`	`r`	`r`	—	—

settlement:r은 매출 리포트와 폐기 예정인 정산 API에 씁니다. 결제 설정 API는 store 스코프에 더해 상점 플랫폼에 로그인한 OWNER만 호출합니다.

웹훅

이벤트를 받을 HTTPS 주소를 /webhooks에 등록합니다. 상점당 10개, webhook:rw(조회는 webhook:r)입니다.

curl https://api.sayren.io/v1/webhooks \
  -H "Authorization: Bearer {계정 토큰}" \
  -H "X-Store-Id: {storeId}" \
  -d '{ "url": "https://example.com/hooks/sayren", "eventTypes": ["ORDER.PAID", "CLAIM.RETURN_REQUESTED"] }'

서명 시크릿(secret)은 등록 응답에만 나옵니다. 이후에는 secretPrefix만 보입니다.
POST /webhooks/{webhookId}/rotate-secret 뒤 이전 시크릿은 oldSecretExpiresAt(24시간)까지 함께 유효합니다. 유효한 시크릿은 최대 2개입니다.
24시간 동안 전송이 한 번도 성공하지 못하면 SUSPENDED입니다. POST /webhooks/{webhookId}/resume이나 PUT으로 수정하면 ACTIVE로 돌아갑니다.

페이로드·서명 검증·재시도는 웹훅 가이드에 있습니다.

결제 설정

PG 키·사용 여부·샌드박스 모드·간편결제·우선순위·결제 도메인은 /store/payment-settings·/store/payment-providers/*입니다. 상점 플랫폼에 로그인한 OWNER 토큰만 받고(그 밖은 403 INSUFFICIENT_ROLE) 비밀 값은 응답에 없습니다. 결제 설정·라이브 전환을 보십시오.

그 밖의 API

주제	요점	가이드
테스트 결제 주문	샌드박스 결제 주문은 `testPayment: true`. `GET /orders`·`/order-items`의 `testPayment` 쿼리로 거릅니다	주문 처리
주문 결제수단	실제 수단은 `payment.approvedMethod`. `payment.method`는 호환용이라 간편결제를 `CARD`로 표시합니다	`GET /orders/{orderId}`
매출 리포트	`GET /sales-report`(`settlement:r`). 테스트 결제는 `includeTest=true`일 때만. `/settlements`는 폐기 예정	매출 리포트
방문 분석	`GET /analytics/{overview,products,sources,devices,pages,search}` 날짜별 집계, `realtime` 최근 5분, `checkout` 결제 시도 분류(`analytics:r`)	방문 분석
API 로그	관리 API 요청을 7일 보관. 개발자 › 모니터링 › API 로그(소유자·관리자)	API 로그

공통 규칙

표준 엔벨로프 — meta(status·code·message·isSuccess) + 성공 data / 실패 error (표준 응답 구조)
리소스는 복수형 명사, 상태 전이는 서브리소스 POST
주문·발송·클레임은 OrderItem 단위 처리
page·size 페이지네이션, 일괄 처리 최대 100건 부분 성공, 중복에 민감한 POST는 Idempotency-Key

인증 — Sayren 계정 토큰

스코프

웹훅

결제 설정

그 밖의 API

공통 규칙

다음 단계

이 페이지 목차