따라하기 가이드Business 플랜부터구매 후 권한·전달 처리
사용량 측정 — 처음부터 판매까지
API 호출이나 문서 건수를 측정하는 방식입니다. 포함량을 넘으면 차단하거나 알릴 수 있으며 초과분 자동 청구는 제공하지 않습니다.
시작 전에 준비하세요
- 판매할 상품과 제공할 내용을 정합니다.
- 상품 등록에서 전달 방식을 선택합니다. 여러 방식을 함께 설정할 수 있습니다.
- 이 가이드에 따라 설정한 뒤 다른 계정으로 전달 결과를 확인합니다.
화면 예시·전달 방식·판매 조건 자세히 보기
아래 화면 예시는 실제 새몰 화면과 동일한 구성으로 재현한 것입니다. 내 계정에서는 상품 등록과 상품 수정 페이지의 연동 정보 카드에서 같은 화면을 만나게 됩니다.
한눈에 보기
1구매자새몰결제 → API Key 자동 발급
2구매자판매자API Key로 서비스 사용
3판매자새몰사용할 때마다 reportUsage로 집계
4새몰판매자포함량 초과 시 usage.threshold_exceeded 웹훅 + 정책 적용
측정 단위·포함량·초과 정책을 상품에 설정해 두면, 집계와 잔여량 계산·임계치 판단을 새몰이 처리합니다.
따라하기
1
상품 등록 — 측정 단위와 초과 정책
saemol.com/products/new
전달 방식 *
사용량 측정사용량을 집계하고 한도를 넘으면 차단하거나 알립니다.
API 상품결제 즉시 API Key를 발급합니다.
측정 단위 *
문서 변환 건
플랜 포함 사용량 (선택)
10,000
임계치 초과 처리 *
차단 (초과 시 사용 불가)
2
결제 → API Key 자동 발급
구매자는 주문 상세·보관함에서 mfk_… 키를 받습니다. 내 서비스는 이 키로 사용자를 식별합니다.
saemol.com/orders/… (구매자 화면)
전달 정보
API Key
mfk_5f2a…c81d사용량 측정 방식입니다. 측정 단위: 문서 변환 건, 포함 사용량: 10,000
3
사용량 리포팅 구현
사용 이벤트마다(또는 배치로) 리포팅하고, 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는 업무별로 저장한 idempotencyKey를 지정하면 자동 재시도합니다. 응답 유실 후 같은 키·수량을 사용하고, 키를 생략한 요청은 자동 재시도하지 않습니다. 잔여량만 조회할 때는 verifyEntitlement 응답의 usage를 쓰면 됩니다.4
임계치 초과 통지 받기
포함량을 처음 초과하는 순간 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 호출"보다 "문서 변환 건")
- 테스트 키로 리포팅 → 초과 → 차단/알림 정책 동작까지 확인했다
- 초과분 자동 청구가 없다는 점과 초과 시 차단/알림 정책을 상품 설명에 명시했다