사용량·크레딧 API로 비용 모니터링하기: 잔액, 이력, 그룹 사용량

curl -X GET "https://studio-gateway.zerocall.kr/payment/credit/summary" \
  -H "x-api-key: $KAT_API_KEY"

{
  "creditBalance": 50000,
  "billingStatus": "ACTIVE",
  "autoRechargeThreshold": 10000,
  "autoRechargeAmount": 50000,
  "costMap": { "sms": 15, "lms": 40, "mms": 100, "call": 2 },
  "billingAnchorAt": "2026-01-01T00:00:00.000Z"
}

curl -G "https://studio-gateway.zerocall.kr/payment/credit/history" \
  -H "x-api-key: $KAT_API_KEY" \
  --data-urlencode "startDate=2026-10-01" \
  --data-urlencode "endDate=2026-10-28" \
  --data-urlencode "groupBy=week" \
  --data-urlencode "fillEmptyBuckets=true"

{
  "effectiveStartDate": "2026-03-01T00:00:00+09:00",
  "effectiveEndDate": "2026-03-31T23:59:59+09:00",
  "totalCount": 50,
  "totalAmount": -15000,
  "summary": [
    {
      "periodStart": "2026-03-05",
      "periodEnd": "2026-03-05",
      "count": 5,
      "totalAmount": -500,
      "startBalance": 50000,
      "endBalance": 49500,
      "amountByType": { "CALL": -300, "MESSAGE": -200 },
      "amountByUsageCategory": { "CALL": -300, "MESSAGE": -200 }
    }
  ],
  "details": [
    {
      "id": 1,
      "type": "CALL",
      "amount": -100,
      "absAmount": 100,
      "direction": "DEBIT",
      "sourceType": "CALL",
      "usageCategory": "CALL",
      "balanceBefore": 50000,
      "balanceAfter": 49900,
      "chatId": null,
      "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
      "campaignId": null,
      "appliedPaymentHistoryId": null,
      "description": "통화 사용",
      "createdAt": "2026-03-05T10:30:00.000Z"
    }
  ],
  "hasMoreDetails": true
}

curl -X GET "https://studio-gateway.zerocall.kr/payment/group/1/usage" \
  -H "x-api-key: $KAT_API_KEY"

import os
from datetime import datetime, timedelta, timezone

import requests

BASE_URL = "https://studio-gateway.zerocall.kr"
KST = timezone(timedelta(hours=9))
USAGE_WARN_RATIO = 0.8  # 기본 제공량의 80%를 넘으면 경고

session = requests.Session()
session.headers.update({"x-api-key": os.environ["KAT_API_KEY"]})


def get(path, params=None):
    resp = session.get(BASE_URL + path, params=params, timeout=15)
    resp.raise_for_status()
    body = resp.json()
    return body["result"] if isinstance(body, dict) and "result" in body else body


def ratio(used, initial):
    return used / initial if initial else 0.0


def check():
    alerts = []

    credit = get("/payment/credit/summary")
    if credit["billingStatus"] != "ACTIVE":
        alerts.append(f"결제 상태가 {credit['billingStatus']}입니다.")
    threshold = credit.get("autoRechargeThreshold") or 0
    if credit["creditBalance"] <= threshold:
        alerts.append(f"크레딧 잔액 {credit['creditBalance']:,}이(가) 자동 충전 기준 이하입니다.")

    for group in get("/group"):
        u = get(f"/payment/group/{group['id']}/usage")
        call_r = ratio(u["useCallMinute"], u["initialCallMinute"])
        msg_r = ratio(u["useTotalMessageCount"], u["initialMessageCount"])
        if call_r >= USAGE_WARN_RATIO:
            alerts.append(f"{group['title']}: 통화 {u['useCallMinute']}/{u['initialCallMinute']}분 ({call_r:.0%})")
        if msg_r >= USAGE_WARN_RATIO:
            alerts.append(f"{group['title']}: 문자 {u['useTotalMessageCount']}/{u['initialMessageCount']}건 ({msg_r:.0%})")

    yesterday = (datetime.now(KST) - timedelta(days=1)).strftime("%Y-%m-%d")
    hist = get("/payment/credit/history", {
        "startDate": yesterday, "endDate": yesterday, "groupBy": "day",
    })
    for bucket in hist["summary"]:
        by_cat = bucket.get("amountByUsageCategory") or {}
        spent = -sum(v for v in by_cat.values() if v < 0)
        print(f"{bucket['periodStart']} 사용 합계 {spent:,} / 분류별 {by_cat}")

    return alerts


if __name__ == "__main__":
    for line in check() or ["이상 없음"]:
        print(line)