충전 / 요금 API

imsend의 모든 발송 채널(SMS, 알림톡, MCP 등)은 하나의 포인트 잔액을 공유합니다.
충전은 TossPayments를 통해 처리되며, 발송 성공 시에만 포인트가 차감됩니다.

빌링 타입 조회

GET /api/v1/tenant/billing-type

가맹점의 빌링 타입(선불/후불)을 반환합니다. 잔액·단가 없이 가볍게 호출 가능하며, 프론트엔드가 충전 UI 표시 여부를 판단할 때 사용합니다.

GET /api/v1/tenant/billing-type
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "data": {
    "tenantId": "moonpd",
    "billingType": "PREPAID",
    "showRechargeUI": true
  }
}

• billingType: "PREPAID"(선불) 또는 "POSTPAID"(후불)
• showRechargeUI: billingType === "PREPAID" 일 때 true. 프론트 분기 단순화용

잔액 조회

GET /api/v1/sms/balance

현재 포인트 잔액과 채널별 단가를 반환합니다.

GET /api/v1/sms/balance
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "data": {
    "tenantId": "moonpd",
    "tenantName": "문피디",
    "balance": 4980,
    "billingType": "PREPAID",
    "creditLimit": 0,
    "available": 4980,
    "unit": "point",
    "priceSms": 12,
    "priceLms": 35,
    "priceMms": 85,
    "priceAlimtalk": 10,
    "priceEmail": 1.2
  }
}

• 응답은 data 객체로 감싸집니다. 잔액 단위는 "point"이며 포인트 ↔ 원(KRW) = 1:1입니다.
• available: 사용 가능 잔액. POSTPAID는 balance + creditLimit, PREPAID는 balance와 동일.

충전 페이지 열기

GET /charge?apiKey={키}&returnUrl={콜백URL}

TossPayments 결제 페이지를 포함한 imsend 충전 페이지 URL을 생성합니다.
팝업 또는 새 탭으로 열면 결제 완료 후 returnUrl로 리다이렉트됩니다.

URL 파라미터

예시

# 직접 URL 구성
https://imsend.kr/charge?apiKey=your_key&returnUrl=https%3A%2F%2Fmyapp.com%2Fcharge%2Fcomplete

# Java SDK
String url = client.payment().getChargePageUrl("https://myapp.com/charge/complete");
// 팝업으로 열기
window.open(url, '_blank', 'width=500,height=700');

충전 이력 조회

GET /api/v1/sms/point-history

GET /api/v1/sms/point-history?page=1&size=20
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "balance": 4980,
  "list": [
    {
      "ledger_seq": 1024,
      "tx_type": "CHARGE",
      "amount": 10000,
      "balance_after": 14980,
      "description": "TossPayments 충전",
      "reg_date": "2026-05-04T14:23:00"
    },
    {
      "ledger_seq": 1025,
      "tx_type": "USE",
      "amount": 12,
      "balance_after": 14968,
      "description": "SMS 발송 차감",
      "reg_date": "2026-05-04T14:25:30"
    }
  ],
  "total": 48,
  "payments": [
    {
      "payment_seq": 305,
      "pg_type": "TOSS",
      "amount": 10000,
      "status": "DONE",
      "order_id": "ORD-20260504-0001",
      "reg_date": "2026-05-04T14:22:58"
    }
  ]
}

• 필드명은 snake_case(ledger_seq, tx_type, balance_after, reg_date)입니다.
• tx_type: CHARGE(충전) / USE(선불 차감) / CREDIT_USED(후불 차감) / REFUND(환불).
• total은 포인트 원장 전체 건수입니다.
• payments[]는 im_payment의 실제 Toss 충전 레코드(DONE)를 함께 반환합니다.

월별 빌링 집계

GET /api/v1/sms/billing

연간 월별/분기별 발송 건수와 발송 비용(SUM(unit_price))을 집계하여 반환합니다.

GET /api/v1/sms/billing?year=2026
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "data": {
    "tenantId": "moonpd",
    "billingType": "PREPAID",
    "creditLimit": 0,
    "balance": 4980,
    "year": "2026",
    "months": [
      { "period": "2026-05", "total_count": 1100, "sms_count": 800, "lms_count": 300, "total_amount": 16520 },
      { "period": "2026-04", "total_count": 1900, "sms_count": 1500, "lms_count": 400, "total_amount": 28500 }
    ],
    "quarters": [
      { "period": "2026-Q2", "total_count": 3000, "total_amount": 45020 }
    ],
    "yearTotal": { "totalCount": 3000, "totalAmount": 45020 }
  }
}

• 응답은 data 객체로 감싸집니다. 월/분기 행의 식별자는 period입니다.
• 집계는 발송 비용(과금액) 합산만 제공합니다 — 충전 금액과의 분리(charge vs use) 항목은 없습니다.
• total_amount는 해당 기간 im_sms_log.unit_price 합계, sms_count/lms_count는 유형별 건수입니다.

채널별 단가

발송 성공(수신 확인) 시에만 차감됩니다. imsend는 3중 단가 체계로 운영되며, 발송 경로·가맹점에 따라 실제 적용 단가가 달라집니다. 내 계정에 실제 적용되는 단가는 항상 잔액 조회 API로 확인하세요.

📌 일반 API(X-API-Key) 발송은 ②가맹점별 협의 단가 → ①기본 단가 순으로 적용됩니다. AI 에이전트(MCP) 발송은 가맹점 단가와 무관하게 ③MCP 단가가 적용됩니다.

차감 정책

• 수신 확인(DELIVERED) 시 1회 차감 — 발송 시점에는 차감하지 않습니다. 결과 폴러(SmsResultScheduler)가 GT Agent 결과를 수신해 DELIVERED로 확정될 때 단 한 번 차감합니다.
• 실패 건 미차감 — FAILED 상태는 포인트 차감 없음
• TIMEOUT 자동 환불 — 결과 미수신(TIMEOUT/NO_RESULT)으로 5분이 경과하면 RecoveryScheduler가 실제 청구 단가(unit_price)를 환불(tx_type=REFUND)하고 result_code='TIMEOUT_REFUNDED'로 마킹해 중복 환불을 방지합니다.
• 과금 타입별 원장 기록 — 선불(PREPAID)은 tx_type=USE, 후불(POSTPAID)은 tx_type=CREDIT_USED로 기록됩니다.
• 잔액 부족 시 발송 차단 — 사전 잔액 확인 후 발송 요청

예정: MCP 직접 결제

카카오페이 가맹 완료 후 MCP charge_point 도구에서 직접 결제가 가능해집니다.

// 현재 (준비 중)
{ "tool": "charge_point", "amount": 10000 }
// → "충전 페이지: https://imsend.kr/Home/charge"

// 예정 (카카오페이 가맹 후)
{ "tool": "charge_point", "amount": 10000 }
// → 카카오페이 결제 링크 반환