연동 시작하기
판매자 서버와 새몰을 몇 줄의 코드로 연결합니다. 라이선스 검증·권한 확인·사용량 리포팅·웹훅 수신까지 이 문서 한 벌로 끝납니다.
판매 절차가 궁금하시다면 판매 가이드와 함께 보시면 더 쉬워요. 프로필 등록부터 상품 등록·정산까지 순서대로 안내합니다. 코드 없이 수동 전달로도 판매할 수 있어요. (이 연동 문서는 결제 즉시 자동 발급이 필요한 판매자용입니다.)
연동 구조 한눈에 보기
상품이 판매되면 새몰이 권한(라이선스 키·API Key)을 자동 발급하고, 판매자 서버는 두 방향으로 연동합니다.
- 판매자 서버 → 새몰 — 제품에서 키가 유효한지 확인 (SDK의
verifyLicense/verifyEntitlement/reportUsage) - 새몰 → 판매자 서버 — 발급·회수 등 이벤트를 웹훅으로 통지 (
verifyWebhook으로 서명 검증)
1. 연동 시크릿 확인
모든 API 호출에는 상품별 연동 시크릿이 필요합니다. 판매자 대시보드 → 내 상품 → 상품 수정 페이지의 연동 정보 카드에서 확인하세요.
연동 시크릿— API 호출 인증용 (X-Saemol-Secret헤더)웹훅 서명 키— 수신한 웹훅의 서명 검증용
시크릿은 서버 환경변수로만 보관하세요. 브라우저·모바일 앱 코드에 포함하면 안 됩니다 — 이 SDK는 Node.js 18+ 서버 전용입니다.
2. SDK 설치
terminal
npm install @saemol/sdk런타임 의존성이 없는 단일 패키지입니다 (Node.js 18+의 내장 fetch 사용). CommonJS·ESM 모두 지원합니다.
SDK 없이 연동하려면 SDK 레퍼런스의 HTTP API 명세를 참고해 직접 호출해도 됩니다 — SDK는 같은 API의 얇은 래퍼입니다.
3. 첫 호출
server.ts
import { Saemol } from '@saemol/sdk'
const saemol = new Saemol({ secret: process.env.SAEMOL_SECRET! })
// 연동 테스트 — 항상 여기서 시작하세요
await saemol.health()
// → { ok: true, service: 'saemol-api', version: 'v1', time: '…' }
// 라이선스 키 검증 (1회성 라이선스·인앱 활성화 토큰)
const result = await saemol.verifyLicense({
licenseKey: 'MF-XXXX-XXXX-XXXX-XXXX',
deviceId: 'machine-abc', // 선택 — 디바이스 제한 시
version: '2.0', // 선택 — 버전별 접근 제한 시
})
if (result.valid) {
// 활성 — result.plan_name, result.expires_at, result.devices
} else {
// 거부 — result.reason: 'revoked' | 'expired' | 'device_limit_exceeded' | …
}구독·API·사용량 상품은 verifyEntitlement(API Key)를, 사용량 집계는 reportUsage를 사용합니다 — 전달 방식별 흐름은 전달 방식별 연동을 보세요.
테스트 모드 (샌드박스)
아직 심사 전이거나 실결제 없이 연동을 검증하고 싶다면 테스트 키를 쓰세요. 연동 정보 카드의 test_ 시크릿과 테스트 키(MF-TEST-… / mfk_test_…)로 verify·웹훅까지 전 구간이 동작하며, 정산·매출·분석에는 일절 집계되지 않습니다. 개발 시작부터 출시까지의 전체 워크플로는 개발 단계부터 연동을 보세요.