전달 방식별 연동
상품을 등록할 때 고른 전달 방식에 따라 받는 발급물과 연동 코드가 달라집니다. 전달 방식은 여러 개를 고를 수 있고, 고른 방식마다 아래 절이 따로 적용됩니다.
전달 방식 요약
| 방식 | 자동 발급 | 판매자가 받는 것 | 판매자가 구현할 것 |
|---|---|---|---|
| 수동 전달 | ✕ | 주문 알림 | 주문 확인 후 직접 전달 — 연동 코드 불필요 |
| 다운로드 | 다운로드 권한 | (웹훅 선택) | 파일 업로드만 — 서명 링크 발급·환불 시 차단은 새몰이 처리 |
| 구독형 | API Key + 라이선스 키 | entitlement.activated | 권한 확인(API Key) 또는 새몰 계정 로그인으로 구독·플랜 확인 |
| 1회성 라이선스 | 라이선스 키 | (웹훅 선택) | 제품에서 라이선스 검증, 디바이스 제한 자동 |
| 사용량 기반 | API Key | usage.threshold_exceeded | 사용량 리포팅, 임계치 정책 적용 |
| 인앱결제 | 활성화 토큰 + SKU | entitlement.activated (SKU 포함) | 웹훅/토큰 검증으로 인앱 활성화 |
| API 상품 | API Key | (웹훅 선택) | 요청마다 권한 확인으로 키·Rate Limit 검증 |
| 화이트라벨 | 접근 키 | tenant.provision_requested | 웹훅 수신 → 테넌트 생성 → 접속 정보 전달 |
따라하기 가이드 (방식별 화면 예시 포함)
처음 등록한다면 아래 따라하기 가이드를 추천합니다 — 실제 화면 예시와 함께 등록부터 판매까지 단계별로 안내합니다. 이 문서의 아래 절들은 코드 중심 요약입니다.
구독형 — 플랜별 기능 제한
인증 연동 방식이 API Key면 구매자에게 API Key가 발급됩니다 — 로그인·요청 시점에 권한을 확인하고 플랜에 따라 기능을 제한하세요. SSO/OAuth 2.0 방식(“새몰 계정으로 로그인”)의 전체 흐름·코드는 구독형 따라하기 가이드를 보세요.
const ent = await saemol.verifyEntitlement({ apiKey: userApiKey })
if (!ent.valid) return deny() // 만료·환불·정지 포함
if (ent.reason === undefined) {
ent.plan_name // 'Pro' 등 — 구매한 플랜
ent.plan_features // 상품 설정의 플랜별 기능 목록
ent.current_period_end // 구독 주기 종료 시각
}응답을 짧게(예: 1~5분) 캐시하면 요청마다 호출하지 않아도 됩니다. 회수·환불은 웹훅으로도 즉시 통지됩니다.
1회성 라이선스 — 키 활성화
구매자에게 라이선스 키가 발급됩니다. 제품 활성화 시점에 검증하고, 디바이스 제한은 플랫폼이 자동 관리합니다.
const result = await saemol.verifyLicense({
licenseKey: inputKey,
deviceId: machineId(), // 보내면 자동 등록 — 제한 초과 시 거부
version: APP_VERSION, // 상품에 허용 버전을 설정한 경우
})
if (!result.valid) {
switch (result.reason) {
case 'device_limit_exceeded': /* 다른 기기 해제 안내 */ break
case 'version_not_allowed': /* result.allowed_versions 안내 */ break
case 'expired': /* 만료 — result.expires_at */ break
default: /* revoked·suspended·키 미존재 */
}
}구매자는 마이페이지 라이선스 보관함에서 키 확인·디바이스 해제를 직접 할 수 있습니다.
사용량 기반 — 리포팅과 차단
사용 이벤트마다(또는 배치로) 사용량을 리포팅합니다. 포함량 초과 시의 동작은 상품 설정의 초과 정책을 따릅니다.
const report = await saemol.reportUsage({
apiKey: userApiKey,
quantity: 120,
metadata: { endpoint: '/convert' }, // 선택 — 이력에 저장
})
if (report.accepted && !report.allowed) {
// 초과 정책이 block — 판매자 서버에서 사용을 차단
}
// report.usage → { unit, used, limit, remaining }reportUsage는 중복 집계를 막기 위해 SDK가 자동 재시도하지 않습니다. 실패 시 재전송 여부는 호출자가 판단하세요. 포함량을 처음 초과하면 usage.threshold_exceeded 웹훅이 발송됩니다.인앱결제 — 활성화 토큰
결제 완료 시 활성화 토큰과 SKU가 발급되고 entitlement.activated 웹훅(SKU 포함)이 발송됩니다. 앱에서 토큰을 입력받아 검증하세요 — 응답의 sku로 어떤 인앱 상품인지 매핑합니다.
const result = await saemol.verifyLicense({ licenseKey: activationToken })
if (result.valid) unlock(result.sku) // 예: 'com.myapp.pro'API 상품 — 키·Rate Limit 검증
요청마다(권장: 캐시와 함께) 권한을 확인하고, 응답의 rate_limit_per_min으로 자체 Rate Limit을 적용합니다.
const ent = await saemol.verifyEntitlement({ apiKey: req.headers['x-api-key'] })
if (!ent.valid) return res.status(401).end()
if (ent.reason === undefined) applyRateLimit(ent.rate_limit_per_min)화이트라벨 — 테넌트 프로비저닝
결제 완료 시 tenant.provision_requested 웹훅이 발송됩니다. 웹훅을 수신해 테넌트를 생성하고 구매자에게 접속 정보를 전달하세요 — 수신·검증 방법은 웹훅 가이드 참고.