REST API

SubX REST API 엔드포인트 목록입니다. 모든 요청은 JSON 형식이며 인증이 필요합니다.

인증

두 가지 인증 방식을 지원합니다:

방식	헤더	용도
JWT 토큰	`Authorization: Bearer <token>`	대시보드 로그인 사용자
API 키	`X-API-Key: your_api_key`	서버 사이드 / SDK / MCP 연동

Base URL

https://api.subx.dev

인증

메서드	경로	설명
POST	`/auth/register`	회원가입
POST	`/auth/login`	로그인 (JWT 발급)
POST	`/auth/refresh`	JWT 토큰 갱신
GET	`/auth/me`	현재 사용자 정보 조회

프로젝트

메서드	경로	설명
GET	`/v1/projects`	프로젝트 목록 조회
POST	`/v1/projects`	프로젝트 생성
GET	`/v1/projects/:id`	프로젝트 상세 조회
PATCH	`/v1/projects/:id`	프로젝트 수정
DELETE	`/v1/projects/:id`	프로젝트 삭제
GET	`/v1/projects/:id/setup-status`	설정 진행 상태 조회

API 키

메서드	경로	설명
GET	`/v1/projects/:id/api-keys`	API 키 목록 조회
POST	`/v1/projects/:id/api-keys`	API 키 생성 (생성 직후에만 전체 키 확인 가능)
DELETE	`/v1/projects/:id/api-keys/:keyId`	API 키 삭제

앱

메서드	경로	설명
GET	`/v1/projects/:id/apps`	앱 목록 조회
POST	`/v1/projects/:id/apps`	앱 등록 (iOS/Android)
GET	`/v1/projects/:id/apps/:appId`	앱 상세 조회
PATCH	`/v1/projects/:id/apps/:appId`	앱 설정 변경
DELETE	`/v1/projects/:id/apps/:appId`	앱 삭제
POST	`/v1/projects/:id/apps/:appId/credentials/apple`	Apple 인증 정보 등록
POST	`/v1/projects/:id/apps/:appId/credentials/google`	Google 인증 정보 등록
GET	`/v1/projects/:id/apps/:appId/credentials/status`	인증 및 알림 상태 조회
DELETE	`/v1/projects/:id/apps/:appId/credentials`	인증 정보 삭제

앱 설정 항목

PATCH /v1/projects/:id/apps/:appId로 다음 설정을 변경할 수 있습니다:

필드	타입	설명
`notificationForwardingUrl`	`string \| null`	Apple/Google 스토어 알림을 이 URL로도 전달합니다
`refundPolicy`	`enum`	revoke_immediately(즉시 해제, 기본) 또는 keep_until_expiry(만료일까지 유지)
`appleSmallBusiness`	`boolean`	Apple 소규모 비즈니스 프로그램 (수수료 15%)

상품

메서드	경로	설명
GET	`/v1/projects/:id/products`	상품 목록 조회
POST	`/v1/projects/:id/products`	상품 생성
GET	`/v1/projects/:id/products/:pid`	상품 상세 조회
DELETE	`/v1/projects/:id/products/:pid`	상품 삭제
POST	`/v1/projects/:id/products/:pid/prices`	가격 추가
DELETE	`/v1/projects/:id/products/:pid/prices/:priceId`	가격 삭제

권한 (Entitlement)

메서드	경로	설명
GET	`/v1/projects/:id/entitlements`	권한 목록 조회
POST	`/v1/projects/:id/entitlements`	권한 생성
GET	`/v1/projects/:id/entitlements/:eid`	권한 상세 조회
PATCH	`/v1/projects/:id/entitlements/:eid`	권한 수정
DELETE	`/v1/projects/:id/entitlements/:eid`	권한 삭제
GET	`/v1/projects/:id/entitlements/:eid/products`	연결된 상품 조회
POST	`/v1/projects/:id/entitlements/:eid/products`	상품 연결
DELETE	`/v1/projects/:id/entitlements/:eid/products`	상품 연결 해제

오퍼링

메서드	경로	설명
GET	`/v1/projects/:id/offerings`	오퍼링 목록 조회
POST	`/v1/projects/:id/offerings`	오퍼링 생성
PATCH	`/v1/projects/:id/offerings/:oid`	오퍼링 수정
GET	`/v1/projects/:id/offerings/:oid/packages`	패키지 목록 조회
POST	`/v1/projects/:id/offerings/:oid/packages`	패키지 생성
DELETE	`/v1/projects/:id/offerings/:oid/packages/:pid`	패키지 삭제
POST	`/v1/projects/:id/offerings/:oid/packages/:pid/products`	패키지에 상품 연결
DELETE	`/v1/projects/:id/offerings/:oid/packages/:pid/products`	패키지에서 상품 해제

페이월

메서드	경로	설명
GET	`/v1/projects/:id/paywalls`	페이월 목록 조회
POST	`/v1/projects/:id/paywalls`	페이월 생성
GET	`/v1/projects/:id/paywalls/:pwid`	페이월 상세 조회
PATCH	`/v1/projects/:id/paywalls/:pwid`	페이월 수정
DELETE	`/v1/projects/:id/paywalls/:pwid`	페이월 삭제

고객

메서드	경로	설명
GET	`/v1/projects/:id/customers`	고객 목록 (검색, 페이지네이션)
GET	`/v1/projects/:id/customers/:cid`	고객 상세 (구독, 권한 포함)

웹훅

메서드	경로	설명
GET	`/v1/projects/:id/webhooks`	웹훅 목록 조회
POST	`/v1/projects/:id/webhooks`	웹훅 생성
GET	`/v1/projects/:id/webhooks/:wid`	웹훅 상세 조회
PATCH	`/v1/projects/:id/webhooks/:wid`	웹훅 수정
DELETE	`/v1/projects/:id/webhooks/:wid`	웹훅 삭제

실험 (A/B 테스트)

메서드	경로	설명
GET	`/v1/projects/:id/experiments`	실험 목록 조회
POST	`/v1/projects/:id/experiments`	실험 생성
GET	`/v1/projects/:id/experiments/:eid`	실험 상세 조회
PATCH	`/v1/projects/:id/experiments/:eid`	실험 수정
DELETE	`/v1/projects/:id/experiments/:eid`	실험 삭제
POST	`/v1/projects/:id/experiments/:eid/variants`	변형 추가
DELETE	`/v1/projects/:id/experiments/:eid/variants/:vid`	변형 삭제

지표 및 차트

메서드	경로	설명
GET	`/v1/projects/:id/metrics/overview`	대시보드 개요 지표
GET	`/v1/projects/:id/metrics/charts`	사용 가능한 차트 종류 (21종)
GET	`/v1/projects/:id/metrics/charts/:chartId`	차트 데이터 조회 (기간, 단위 지정)

구독자 (SDK)

메서드	경로	설명
GET	`/v1/subscribers/:appUserId`	구독자 정보 조회
POST	`/v1/subscribers/:appUserId`	구독자 생성/업데이트
POST	`/v1/subscribers/:appUserId/attributes`	커스텀 속성 설정
POST	`/v1/subscribers/:appUserId/entitlements`	프로모션 권한 부여
DELETE	`/v1/subscribers/:appUserId/entitlements/:eid`	프로모션 권한 해제
POST	`/v1/subscribers/:appUserId/receipts`	스토어 영수증 제출

SDK 오퍼링

메서드	경로	설명
GET	`/v1/offerings`	현재 오퍼링 조회 (API 키 인증)
GET	`/v1/offerings/:oid/paywalls`	오퍼링의 페이월 조회
GET	`/v1/subscribers/:appUserId/offerings`	구독자별 오퍼링 조회
POST	`/v1/events`	커스텀 이벤트 기록

스토어 알림

메서드	경로	설명
POST	`/v1/store/apple/:token`	Apple S2S 알림 수신 엔드포인트
POST	`/v1/store/google/:token`	Google S2S 알림 수신 엔드포인트

요청 예시

상품 생성

POST https://api.subx.dev/v1/projects/:projectId/products
Content-Type: application/json
X-API-Key: your_api_key

{
  "appId": "app_xyz789",
  "storeProductId": "com.example.pro.monthly",
  "displayName": "Pro Monthly",
  "type": "subscription"
}

앱 설정 변경

PATCH https://api.subx.dev/v1/projects/:projectId/apps/:appId
Content-Type: application/json
X-API-Key: your_api_key

{
  "notificationForwardingUrl": "https:1
  6: "keep_until_expiry",
  "appleSmallBusiness": true
}

에러 응답

모든 에러는 다음 형식으로 반환됩니다:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

상태 코드	설명
`400`	잘못된 요청 (필수 필드 누락, 유효성 검증 실패)
`401`	인증 실패 (토큰/API 키 누락 또는 만료)
`403`	권한 없음
`404`	리소스를 찾을 수 없음
`500`	서버 내부 오류

다음 단계

웹훅 — 서버에서 구독 이벤트를 수신합니다.
SDK 연동 — iOS/Android 앱에 SubX SDK를 연동합니다.
스토어 연동 — App Store Connect / Google Play Console 설정 방법을 확인합니다.