변경 이력
관리 API·스토어프론트 API·SDK의 공개 변경 사항
연동에 영향을 주는 변경을 날짜순(최신이 위)으로 정리합니다. 호환되지 않는 변경에는 호환성 변경을 표시합니다.
2026-09-24
구매자 관리와 비회원 주문 설정
- 추가: Store API
GET /customers(검색·가입일·마케팅 수신·정렬),GET /customers/{customerId},GET /customers/{customerId}/orders(전체 기간),POST /customers/{customerId}/withdraw(탈퇴 처리). 새 스코프customer:r(OWNER·ADMIN·STAFF)·customer:rw(OWNER·ADMIN). - 추가:
PATCH /store·GET /store의guestCheckoutEnabled.false면 비회원의 주문서 생성·결제 요청이403 GUEST_CHECKOUT_DISABLED입니다. - 추가: Storefront API
GET /store스토어 공개 설정(guestCheckout포함). - 셀러 콘솔: 고객 › 구매자(목록·상세·탈퇴 처리), 설정 › 스토어 정보 › 비회원 주문.
@sayren/store-sdk0.4.0(customers.*),@sayren/storefront-sdk0.5.0(store.get).
구매자 인증
- 추가:
POST /auth/withdraw구매자 탈퇴. 비밀번호로 본인 확인을 하고 계정·배송지·위시리스트·장바구니·적립금을 지웁니다. 주문·클레임·리뷰·문의 기록은 남습니다. 진행 중인 주문·클레임·결제가 있으면409 WITHDRAWAL_BLOCKED입니다.@sayren/storefront-sdk0.4.0에auth.withdraw가 추가됐습니다. - 추가:
POST /auth/anonymous비회원 세션 발급({ cartToken, expiresAt }). - 변경: 비회원 장바구니 토큰(
X-Cart-Token)이 비회원 세션이 됐습니다. 마지막 활동 후 30일이 지나면 만료되고 장바구니도 지워집니다. 담은 적 없는 세션은 하루 뒤 지워집니다. 로그인으로 회원 장바구니에 합친 토큰은 더는 쓸 수 없고, 만료·종료된 토큰으로 장바구니를 부르면 새 토큰이 발급됩니다. - 추가:
POST /auth/signup의cartToken. 가입과 함께 비회원 장바구니를 합칩니다. @sayren/storefront-sdk0.3.0에@sayren/storefront-sdk/auth(createStorefrontAuth:anonymous·session·signUp·refresh·signOut)와auth.anonymous가 추가됐습니다. 사용법은 구매자 인증을 보세요.
셀러 콘솔 메뉴
- 메뉴 순서가 대시보드 → 상품 → 판매 → 고객 → 분석으로 바뀌었습니다. 매출 리포트·결제 내역은 분석 섹션으로 옮겼습니다.
- 애널리틱스는 메뉴 한 항목(분석 › 애널리틱스)이 되고, 개요·전환 퍼널·상품 분석·유입 경로는 화면 안 탭으로 오갑니다. 주소(
/analytics/funnel등)는 그대로입니다.
방문 분석 수집 도메인 제한
- 추가:
PATCH /store의analyticsAllowedOrigins, 응답analyticsAllowedOrigins. 목록을 정하면 그 오리진에서 보낸 방문 분석 수집만 받고, 목록 밖은403 ORIGIN_NOT_ALLOWED입니다. 비우면(기본) 이전처럼 모두 받습니다. - store-sdk에
store.update가 추가됐습니다. - MCP
verify_storefront가 방문 분석 시작(analytics-start)과 서버 API 클라이언트의 방문 식별자(analytics-ids)를 검사합니다.
방문 분석 수집
- 쿼리만 다른 페이지(페이지 넘기기·검색어·필터 변경)를 서로 다른 페이지뷰로 셉니다. 이전에는 같은 경로를 10초 안에 다시 보면 한 번으로 셌습니다.
- 수집 한도가 방문자당 분당 120개로 늘었습니다.
@sayren/storefront-sdk0.2.1은 전체 분당 100개까지만 보내고, 상한으로 버린 페이지뷰의 상품 조회·체류는 보내지 않습니다.
2026-09-23
방문 분석 통계 조회
- 추가:
GET /analytics/overview·GET /analytics/products·GET /analytics/sources. 스토어프런트에서 수집한 방문을 날짜별로 집계해 개요·퍼널·상품·유입 통계를 돌려줍니다. 방문 분석 참고. - 새 스코프
analytics:r. 콘솔 로그인에서는 OWNER·ADMIN이 가집니다. API 토큰·앱에는 발급할 때 지정합니다. - store-sdk에
analytics.overview·analytics.products·analytics.sources가 추가됐습니다.
방문 분석
- 스토어프론트 SDK에 방문 분석 모듈
@sayren/storefront-sdk/analytics가 추가됐습니다. 페이지뷰·상품 조회·목록 노출·검색·체류 시간을 수집합니다. 방문 분석 참고. - 추가:
POST /storefront/v1/events(수집), SDKanalyticsIdsFromCookie,createStorefrontClient의visitorId·sessionId옵션. - 스토어프론트 API 요청에
x-sayren-visitor·x-sayren-session헤더를 실으면 장바구니 담기·빼기, 결제 시작, 구매가 서버에서 그 방문에 이어 기록됩니다.
문서 주소
- 문서가
https://docs.sayren.app/(루트)로 옮겨졌습니다. 예를 들어 웹훅 가이드는https://docs.sayren.app/guides/webhooks입니다. 옛 주소https://docs.sayren.app/docs/…는 새 주소로 영구 리다이렉트(301)합니다.
OpenAPI 문서 주소
- OpenAPI 문서 주소가 바뀌었습니다. 관리 API는
https://api.sayren.app/openapi/store.json, 스토어프론트 API는https://api.sayren.app/openapi/storefront.json입니다(YAML은 확장자만.yaml). 옛 주소/docs/admin.json·/docs/storefront.json은 새 주소로 리다이렉트(308)합니다. - 모든 오퍼레이션에 요청 본문·응답 스키마가 실립니다. 오퍼레이션별 필요 스코프는
x-required-scopes, 셀러 콘솔 로그인이 필요한 오퍼레이션은x-console-only: true로 표시됩니다. 멱등키를 받는 오퍼레이션에는Idempotency-Key헤더가 문서화됐습니다. GET /products의status쿼리가 문서에 추가됐습니다.
MCP로 스토어 운영
- MCP에 관리 API 도구 4개(
list_operations·describe_operation·call_api_read·call_api_write)가 추가됐습니다. 대화로 스토어를 조회하고 바꿀 수 있습니다. 스토어프론트 만들기 (MCP) 참고. get_store_context의productCount는 등록된 상품 전체 수입니다. 구매자에게 보이는 수는publicProductCount입니다.npx @sayren/mcp create <폴더>로 스토어프론트 템플릿을 한 번에 받습니다.
2026-09-19
결제(PG) 연결
- 셀러가 직접 계약한 토스페이먼츠·포트원으로 결제를 받습니다. 결제 대금은 PG가 셀러에게 바로 정산합니다. 결제 설정 참고.
- PG마다 테스트 키와 라이브 키를 따로 등록하고, 샌드박스 모드(기본 켜짐)로 어느 키로 결제할지 정합니다. 샌드박스 모드를 끄려면 라이브 전환 조건 5개를 채워야 합니다. 샌드박스에서 라이브로 전환하기 참고.
- 추가:
GET·PUT /store/payment-settings,PUT /store/payment-providers/tosspayments,PUT /store/payment-providers/portone,PATCH·DELETE /store/payment-providers/{provider},DELETE /store/payment-providers/{provider}/credentials/{environment},POST /store/payment-providers/{provider}/verify. 콘솔에 로그인한 OWNER만 호출할 수 있습니다. 새 에러409 LIVE_GATE_NOT_MET·LIVE_PAYMENTS_DISABLED(error.details.conditions에 조건별 충족 여부),409 PAYMENT_PROVIDER_VERIFICATION_FAILED·PAYMENT_CREDENTIAL_ACTIVE·PAYMENT_CREDENTIAL_CHANGED·PAYMENT_PROVIDER_CHANGED,404 PAYMENT_CREDENTIAL_NOT_FOUND. 토스페이먼츠 결제위젯 키는400 VALIDATION_FAILED로 거부되고fieldErrors에credentials.clientKey·credentials.secretKey가 담깁니다. GET /store/payment-settings응답의candidates·environment로 지금 결제에 쓰는 PG와 결제 환경을,providers[].routingExclusion으로 후보에서 빠진 사유를 확인합니다.- 가맹점을 바꾸거나 연결을 해제해도 이전 키는 보관돼 그 가맹점으로 받은 결제의 취소·환불에 계속 쓰입니다.
- 두 PG를 모두 쓰면 라우팅 방식으로
AUTO_FAILOVER(기본) 또는PRIORITY_DISPLAY를 고릅니다. - 샌드박스 모드에서 받은 결제는 테스트 결제입니다. 관리 API
GET /orders·GET /orders/{orderId}·GET /order-items와 주문상품 처리 응답, 스토어프론트 API 내 주문·비회원 주문 조회 응답에testPayment가 추가됐습니다.GET /orders·GET /order-items는 쿼리testPayment=true|false로 거를 수 있습니다. 세 주문 조회 API가 API 레퍼런스에 문서화됐습니다. - 웹훅
ORDER.*·CLAIM.*의data에testPayment가 추가됐습니다. 수신 측에서data를 모르는 필드를 거부하는 방식(strict)으로 검증한다면 이 필드를 허용하도록 바꿔야 합니다. 웹훅 참고. - 테스트 결제 주문에는 리뷰를 쓸 수 없습니다. 작성 가능 목록에서 빠지고, 작성하면
409 REVIEW_NOT_ALLOWED_FOR_TEST_ORDER입니다. - 결제 요청
POST /storefront/v1/checkout/{checkoutId}/payment에 새 에러409 PAYMENT_NOT_CONFIGURED,503 PAYMENT_PROVIDER_UNAVAILABLE이 추가됐습니다.pgProvider는tosspayments또는portone입니다. 주문서 생성과 결제 요청 응답에testPayment가 추가됐습니다. - 호환성 변경
pgParams에서successUrl·failUrl을 제거하고attemptId·provider·mock·environment를 추가했습니다.popupUrl만 쓰는 연동은 영향이 없습니다. - 추가:
GET /storefront/v1/payments/{paymentId}. 결제 상태(status)·주문번호·테스트 결제 여부·만료 시각을 인증 없이 조회합니다. 팝업의 결과 메시지를 받지 못했을 때 쓰세요. 결제 플로우 참고. - 결제 승인
POST /storefront/v1/payments/{paymentId}/confirm본문에 선택 필드attemptId가 추가됐습니다. 새 에러402 PAYMENT_NOT_APPROVED,409 PAYMENT_RESULT_UNKNOWN·ATTEMPT_NOT_CURRENT·INVALID_ATTEMPT_STATE·PAYMENT_SESSION_OUTDATED·PG_AMOUNT_MISMATCH·PG_ENVIRONMENT_MISMATCH·LATE_APPROVAL_CANCELED,502 PG_REQUEST_FAILED,503 PG_CREDENTIALS_UNAVAILABLE·PG_MERCHANT_MISMATCH. 응답별 처리는 결제 플로우를 참고하세요. - 호환성 변경 카드 거절처럼 승인되지 않은 것이 확정되면 결제 세션이
failed가 아니라pending으로 남습니다. 같은 세션에서 다른 결제사나 같은 결제사로 다시 결제할 수 있습니다. - 호환성 변경 결제수단의 뜻이 요청한 결제수단에서 실제 결제수단으로 바뀌었습니다. 실제 결제수단은 PG가 알려 준 수단이고,
알려 주지 않으면 요청한 수단입니다. 카드로 요청하고 결제창에서 간편결제로 결제하면 두 값이 다릅니다. 필드 형태와 값 목록은 그대로입니다.
GET /sales-report:method쿼리 필터와rows[].method. 카드였던 행 일부가EASY_PAY등으로 옮겨 갈 수 있습니다.GET /orders/{orderId}의payment.method. 관리 API 결제수단에는 간편결제가 없어 간편결제는 종전처럼CARD로 나갑니다. 실제 결제수단을 그대로 보려면 새로 추가한payment.approvedMethod를 쓰세요(추가). 결제 기록이 없는 오래된 주문은null입니다.- 스토어프론트
GET /me/orders,GET /me/orders/{orderId},POST /guest/orders/{orderId}의payment.method.EASY_PAY가 그대로 나갑니다. - 주문 응답은 새 주문부터 적용되고, 기존 주문은 요청한 결제수단 그대로입니다. 웹훅과 결제 요청·주문서의
paymentMethod는 바뀌지 않았습니다.
- 호환성 변경 새로 만드는 결제 id(
paymentId)가 길어졌습니다(pay_뒤 32자). 이미 만든 결제는 그대로입니다. id의 형식이나 길이를 가정해 저장·검증했다면 바꿔야 합니다. - 결제 시작과 결제 승인의 에러 응답이 API 레퍼런스에 문서화됐습니다.
- 결제 관련 에러 메시지(
error.message)의 문구를 바꿨습니다. 에러 코드는 그대로이니 분기는error.code로 하세요. - Storefront SDK:
checkout.confirmPayment의 세 번째 인자{ attemptId },payments.getStatus, 상태 값 목록PAYMENT_STATUS_VALUES를 추가했습니다. - Store SDK:
paymentSettings.*,liveGateErrorDetailsSchema,PAYMENT_ROUTING_EXCLUSION_CODES, 주문 목록testPayment인자를 추가했습니다. 토스페이먼츠 결제위젯 키는 요청 전 검증에서ZodError로 거부됩니다.
매출 리포트
- 추가:
GET /sales-report. 기간·PG·결제수단별 결제·환불·순매출을 집계하며settlement:r스코프가 필요합니다. 테스트 결제는 기본으로 빠지고includeTest=true로 포함합니다. 매출 리포트 참고. - 호환성 변경 구매확정 때 정산 내역을 쌓지 않습니다. 플랫폼 수수료를 공제하는 정산은 폐기됐고, 기존 정산 내역은 그대로 조회됩니다.
GET /settlements,GET /settlements/{settlementId}는 폐기 예정입니다. 응답에Deprecation: true와Link: </v1/sales-report>; rel="successor-version"헤더가 붙습니다.- Store SDK:
salesReport.get을 추가했고settlements.*는 폐기 예정입니다. - 셀러 콘솔 정산 › 정산 내역은 매출 › 매출 리포트로 바뀌었습니다.
스토어프론트 만들기 (MCP)
- 추가: sayren MCP 서버(
npx @sayren/mcp). 코딩 도구에 붙이면 스토어 컨텍스트·검증된 템플릿·생성 규칙· 결과 검증을 도구로 제공합니다. 스토어프론트 만들기 참고. - 템플릿은 React Router(SSR) 기반이고 구매 흐름 전체(홈·목록·상세·장바구니·주문서·결제·주문 내역)를 담습니다.
- 셀러 콘솔 개발자 › 스토어프론트 만들기에서 연결 설정과 프롬프트를 복사할 수 있습니다.
결제 내역
- 추가:
GET /payments,GET /payments/{paymentId}. 결제 건 단위 조회이고settlement:r스코프가 필요합니다. 주문이 만들어지지 않은 결제(카드 거절·결제창 이탈·승인 결과 확인 중)도 나오고, 상세에는 시도 이력과 환불 이력이 함께 담깁니다. 실패한 환불 요청도 남습니다. 결제 내역 참고. - 기간 기준은 결제 시작 시각이고 최대 92일입니다. 생략하면 최근 30일이며, 테스트 결제는
includeTest=true일 때만 포함합니다. - Store SDK:
payments.list·payments.get을 추가했습니다. - 셀러 콘솔 매출 › 결제 내역을 추가했습니다.
공통
- 에러 엔벨로프
$.error에 선택 필드details를 추가했습니다. 일부 에러 코드에만 보조 데이터가 담기며, 없으면 필드가 빠집니다.
웹훅 전송
- 등록한 주소로 이벤트를 실제로 전송합니다. 요청 형식, 헤더, 이벤트별
data는 웹훅을 참고하세요.ORDER.DELIVERED,ORDER.ADDRESS_CHANGE_REQUESTED, 교환 클레임의CLAIM.COMPLETED는 아직 발송되지 않습니다. Sayren-Signature헤더로 서명합니다(t=<unix 초>,v1=<HMAC-SHA256 hex>). 시크릿 교체 후 24시간 동안은 새 시크릿과 기존 시크릿 서명을 함께 싣습니다.- 실패하면 1분·5분·30분·2시간 뒤에 재시도합니다. 첫 실패부터 24시간 이상 성공 없이 실패가 이어지면 구독이
SUSPENDED로 바뀝니다. - 추가:
POST /webhooks/{webhookId}/resume,POST /webhooks/{webhookId}/deliveries/{deliveryId}/redeliver,POST /webhooks/{webhookId}/deliveries/redeliver-failed. 재전송은 원본 기록당 한 번입니다. 새 에러 코드WEBHOOK_DELIVERY_NOT_FOUND(404),DELIVERY_NOT_FAILED·DELIVERY_ALREADY_REDELIVERED·WEBHOOK_SUSPENDED(409). GET /webhooks/{webhookId}/deliveries가 실제 전송 기록을 반환합니다(최근 30일).status·limit쿼리를 받습니다. 응답에status: PENDING과url·errorCode·attemptCount·attemptedAt·nextAttemptAt·responseBodyExcerpt·redeliveryOf·redeliveredAs필드가 추가됐습니다.POST /webhooks/{webhookId}/test가 등록한 주소로 실제 요청을 보내고 측정한 응답 코드와 응답 시간을 반환합니다. 응답에errorCode가 추가됐습니다.- 웹훅 응답에
suspendedAt이 추가됐고,createdAt등 일시 필드가 ISO 8601 형식으로 통일됐습니다. PUT /webhooks/{webhookId}는 정지를 해제하면서 연속 실패 기록도 초기화합니다.DELETE /webhooks/{webhookId}는 전송 기록도 함께 삭제합니다.- 호환성 변경 등록·수정 때 구독 주소를 검사합니다. 내부 대역으로 해석되는 호스트나 사용자 정보(
user:pass@)가 들어간 주소는400 VALIDATION_FAILED로 거부됩니다. - Store SDK:
webhooks.resume·webhooks.redeliver·webhooks.redeliverFailed,listDeliveries의status·limit인자, 요청 본문 스키마webhookEventSchema, 서명 검증verifyWebhookSignature(@sayren/store-sdk/server)를 추가했습니다.
API 로그
- 스토어로 들어온 관리 API 요청을 7일간 기록하고 셀러 콘솔에서 조회할 수 있습니다. API 로그 참고.
앱 관리
- 추가:
GET /store/api-clients,GET /store/api-clients/{clientId},POST /store/api-clients/{clientId}/rotate-secret,POST /store/api-clients/{clientId}/deactivate - 비활성화한 앱이 발급한 토큰과, 그 토큰을 교환해 받은 storeToken은 즉시
401로 거부됩니다. - 호환성 변경 앱 토큰의 권한은 사용자 역할, 토큰 scope, 앱 등록 scope가 모두 허용하는 범위로 제한됩니다.
X-Store-Id직접 호출과 token-exchange에 모두 적용됩니다. - 호환성 변경 API 토큰 발급, 클라이언트 등록(DCR), 앱 관리는 셀러 콘솔에서 로그인한 OWNER·ADMIN만 할 수 있습니다.
- 웹훅 시크릿을 교체하면 기존 시크릿이 24시간 동안 함께 유효합니다. 유효한 시크릿은 최대 2개입니다.
2026-09-18
- 호환성 변경 상품 옵션을 옵션 축(
optionGroups) × 값 → 판매 단위(variants) 구조로 바꿨습니다. 재고는 판매 단위별로 관리하고, 상품의stockQuantity는 판매 가능한 판매 단위의 재고 합계입니다. GET·PUT /products/{productId}/options가 옵션 모델 전체를 다룹니다.PUT에서 판매 단위의stockQuantity를 생략하면 기존 재고를 유지합니다.- 재고 변경 경로가
PATCH /products/{productId}/variants/{variantId}/stock으로 바뀌었습니다. - 판매 단위에
sku·barcode·costPrice·weightGram이 추가됐습니다. - 장바구니·주문·클레임·리뷰의
optionId는 판매 단위의variantId와 같은 값입니다. ID 형식은 고정되어 있지 않으니 접두어로 판별하지 마세요. - 스토어프론트 상품 상세가
options대신optionGroups·variants를 반환합니다.
2026-09-17
- 셀러 로그인이 외부 IdP로 일원화됐습니다.
GET /oauth2/authorize는 IdP 로그인 화면으로 이동하고, 인증이 끝나면 이전과 같이redirect_uri로 code를 돌려줍니다. 토큰 발급·교환 방식은 바뀌지 않았습니다.
2026-07-19
- 1:1 문의 API를 추가했습니다. 셀러용
/customer-inquiries, 구매자용/storefront/v1/me/customer-inquiries.
2026-07-16
- Store SDK·Storefront SDK: 로그인 세션 관리
createStoreSession·createStorefrontSession을 추가했습니다. 토큰 저장, refresh token 회전, 무음 갱신을 SDK가 처리합니다.
2026-07-14
userToken과X-Store-Id헤더로 token-exchange 없이 스토어 리소스를 호출할 수 있습니다.- 카테고리에 표시 상태, PC·모바일 노출, 상품 진열, SEO 설정 필드가 추가됐습니다.
2026-07-11
- 클레임 승인과 셀러 직권취소가 결제 취소(환불)까지 처리합니다.
2026-07-10
- 카테고리 관리 API(
/categories, 트리·검색·생성·수정·이동·삭제)와category:r|rw스코프를 추가했습니다.
2026-07-09
- 호환성 변경 모든 응답이 표준 엔벨로프
{ meta, data, error }를 따릅니다. OAuth 엔드포인트는 예외입니다. - 호환성 변경 관리 API 인증을 OAuth 2.1로 바꿨습니다. authorization_code + PKCE, refresh token 회전,
client_credentials, token-exchange(
audience={storeId})를 지원합니다.passwordgrant는 제거했습니다. - API 토큰(
/store/api-tokens), 클라이언트 등록(POST /oauth2/register), 구매자 위임 토큰 발급을 추가했습니다. - 토큰 서명을 RS256으로 바꾸고
/.well-known/jwks.json,/.well-known/oauth-authorization-server를 제공합니다. - 호환성 변경 스토어 생성·폐쇄·양도와 초대 수락을 관리 API에서 제거했습니다. 셀러 콘솔에서 처리합니다.