따라하기 가이드Business 플랜부터결제 즉시 자동 발급

사용량 기반 — 처음부터 판매까지

API 호출이나 문서 건수처럼 쓴 만큼 받는 방식입니다. 사용량을 세고 한도를 넘었는지 판단하는 일은 새몰이 대신합니다.

아래 화면 예시는 실제 새몰 화면과 동일한 구성으로 재현한 것입니다. 내 계정에서는 상품 등록과 상품 수정 페이지의 연동 정보 카드에서 같은 화면을 만나게 됩니다.

전달 방식은 여러 개를 고를 수 있습니다. 이 가이드는 사용량 기반 하나를 기준으로 설명하지만, 다른 방식과 함께 체크해도 됩니다. 방식마다 설정과 발급이 따로 적용됩니다. 세 축(상품 종류·가격 방식·전달 방식)이 어떻게 맞물리는지는 판매 가이드에 정리해 두었습니다.
가격을 매기려면 사업자 인증이 필요합니다. 개인사업자나 법인으로 정산 정보를 등록하고 인증을 마쳐야 유료 요금제를 설정할 수 있습니다. 비사업자는 0원(무료) 상품만 등록됩니다. 인증과 상관없이 연동 자체는 지금 그대로 따라 할 수 있습니다.

한눈에 보기

1구매자새몰결제 → API Key 자동 발급

2구매자판매자API Key로 서비스 사용

3판매자새몰사용할 때마다 reportUsage로 집계

4새몰판매자포함량 초과 시 usage.threshold_exceeded 웹훅 + 정책 적용

측정 단위·포함량·초과 정책을 상품에 설정해 두면, 집계와 잔여량 계산·임계치 판단을 새몰이 처리합니다.

따라하기

상품 등록 — 측정 단위와 초과 정책

saemol.com/products/new

전달 방식 *

사용량 기반쓴 만큼 집계합니다. 정해 둔 한도를 넘으면 설정한 정책을 적용합니다.

API 상품결제 즉시 API Key를 발급합니다.

측정 단위 *

문서 변환 건

플랜 포함 사용량 (선택)

10,000

임계치 초과 처리 *

차단 (초과 시 사용 불가)

결제 → API Key 자동 발급

구매자는 주문 상세·보관함에서 mfk_… 키를 받습니다. 내 서비스는 이 키로 사용자를 식별합니다.

saemol.com/orders/… (구매자 화면)

전달 정보

API Key

mfk_5f2a…c81d

사용량 기반 상품입니다. 측정 단위: 문서 변환 건, 포함 사용량: 10,000

사용량 리포팅 구현

사용 이벤트마다(또는 배치로) 리포팅하고, allowed가 false면 차단합니다.

convert.ts — 사용 시점에 집계

const report = await saemol.reportUsage({
  apiKey: userApiKey,
  quantity: 1,
  metadata: { endpoint: '/convert' },   // 선택 — 이력에 저장
})

if (report.accepted && !report.allowed) {
  // 초과 정책이 '차단' — 사용 거부 + 업그레이드 안내
  return res.status(402).json({ error: 'quota_exceeded', usage: report.usage })
}
// report.usage → { unit: '문서 변환 건', used: 10001, limit: 10000, remaining: 0 }

reportUsage는 중복 집계를 막기 위해 SDK가 자동 재시도하지 않습니다 — 실패 시 재전송 여부는 호출자가 판단하세요. 잔여량만 조회할 때는 verifyEntitlement 응답의 usage를 쓰면 됩니다.

임계치 초과 통지 받기

포함량을 처음 초과하는 순간 usage.threshold_exceeded 웹훅이 발송됩니다. 구매자에게 업그레이드를 안내하기 좋은 시점입니다.

api.myservice.com/webhooks/saemol (판매자 서버)

{ "event": "usage.threshold_exceeded",
  "data": {
    "entitlement_id": "…", "plan_name": "Pro",
    "unit": "문서 변환 건", "used": 10001, "limit": 10000,
    "overage_policy": "block"
  } }

출시 전 체크리스트

측정 단위가 구매자 입장에서 이해되는 단위다 (예: "API 호출"보다 "문서 변환 건")
테스트 키로 리포팅 → 초과 → 차단/알림 정책 동작까지 확인했다
초과 정책이 "초과분 과금"이면 정산 방식을 상품 설명에 명시했다

다음으로 볼 문서

SDK 레퍼런스

reportUsage 응답 필드 전체

웹훅 가이드

서명 검증과 재발송