연동 시작하기
판매자 서버에서 새몰의 구매·사용 권한을 확인하는 방법을 안내합니다. SDK 설치뿐 아니라 서버 설정, 웹훅 처리, 실제 사용 테스트까지 순서대로 준비하세요.
판매 절차가 궁금하시다면 판매 가이드와 함께 보시면 더 쉬워요. 프로필 등록부터 상품 등록·정산까지 순서대로 안내합니다. 코드 없이 수동 전달로도 판매할 수 있어요. 이 문서는 구매 완료 후 권한 발급과 서비스 연결을 준비하는 판매자용입니다.
코드를 읽기 전에 따라 할 순서가 필요하다면 쉬운 결제 연결 가이드부터 보세요. 판매 방식을 고르고 새몰 설정을 준비한 뒤, AI 도구·사이트 제작자에게 전달할 요청문을 만들 수 있습니다.
연동 구조 한눈에 보기
자동 전달 방식의 구매가 완료되면 새몰이 설정에 따라 라이선스 키·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_…)로 권한 검증과 예제 웹훅을 확인할 수 있습니다. 웹훅은 설정한 주소로 전송되므로 판매자 서버에서도 테스트 요청을 구분해 처리하세요. 테스트 키만으로 실제 PG 결제·환불이 시험되지는 않습니다. 준비 순서는 개발 단계부터 연동을 보세요.