API 청구 및보고
1) API에 대한 자체 청구 이유
투명한 수익 창출: 사용 링크 → 수익.
확장 성 및 통제: 계획에 따른 할당량, 재정의, 대출, 가격대.
재무 정확성: 세금/부가가치세, 다중 요금, 행위 및 폐쇄 문서.
고객 신뢰: 자세한 사용 보고서, 웹 후크, 셀프 서비스 포털.
2) 청구 아키텍처 (고급)
생산자 (API 게이트웨이, 서비스) → 사용 이벤트 버스 (Kafka/Queue) → 계량 및 등급 → 청구 DB → 음성/세금 → 지불 (PSP) → DWH → 클라이언트 포털/웹 후크보고.
구성 요소:- 계량-사용량의 수집 및 정규화 (요청, 대출, 거래량).
- 등급-가격책/계획에 따른 이벤트 비용 추정.
- 목소리-해당 기간, 이익, 세금, 할인, 크레딧 집계.
- 결제-상각/상환, 데이트 (dunning).
- 보고-MRR/ARPU/LTV, 코호트 이탈, 서비스 비용.
- 감사-demmpotence, 변경되지 않은 로그.
3) 엔티티 및 식별자
계정 (테넌트), 계획, 자격, 사용 이벤트, 음성, 신용 메모, 세금 프로필.
중요한 것: demempotency _ key 사용/송장/지불, 소스 (게이트웨이/배치), 이벤트 스키마 버전.
4) 사용 이벤트: 참조 체계
json
{
"event_id": "use_01HXYZ...",
"idempotency_key": "key_6a2f-2025-11-03T18:02:09Z",
"occurred_at": "2025-11-03T18:02:05Z",
"ingested_at": "2025-11-03T18:02:09Z",
"tenant_id": "t_123",
"api_key_id": "k_456",
"plan_id": "pro-2025",
"endpoint": "POST /v1/reports/run",
"unit": "credit",
"quantity": 5,
"region": "eu-west-1",
"metadata": { "request_id": "r_789", "ip": "203. 0. 113. 5" },
"signature": "hmac_sha256_base64(...)",
"schema_version": 2
}규칙: 이벤트 만 추가됩니다. 편집 - '이벤트 _ id' 를 참조하여 수정 조정 이벤트를 통해.
5) 저장 및 집계 계층
5. 1 OLTP (청구 DB)
계획: '세입자', '계획', '플랜 _ 가격', '권한', '사용 _ 이벤트', '정격 _ 라인', '송장', '송장', '세금 _ 라인', '크레딧', '지불', '환불', '분쟁'.
5. 2 DWH (분석)
차이도: 'f _ usage', 'f _ billing', 'f _ payment'; 치수: 'd _ tenit', 'd _ plan', 'd _ endpoint', 'd _ region', 'd _ date'.
5. 3 SQL 집계 사용량 → 청구 라인의 예
sql
-- 1) Reduce usage per day by units create materialized view mv_daily_usage as select tenant_id, plan_id, endpoint, date_trunc ('day', occurred_at) d,
unit, sum(quantity) qty from usage_events where occurred_at >=:period_start and occurred_at <:period_end group by 1,2,3,4,5;
-- 2) Price book (tiered) applicable
select u. tenant_id, u. plan_id, u. d, u. unit, u. qty,
p. tier_from, p. tier_to, p. price_per_unit,
least(greatest(u. qty - p. tier_from + 1, 0), p. tier_to - p. tier_from + 1) as billable_units,
price_per_unit least(...) as amount from mv_daily_usage u join plan_prices p on p. plan_id = u. plan_id and p. unit = u. unit and u. qty >= p. tier_from;6) 가격 책과 등급 (등급)
지원 모델: 평면, 계층 형, 볼륨, 번들 크레딧, 종량제 및 재정의.
가격 책 예 (YAML):yaml plan_id: pro-2025 currency: USD units:
request:
tiers:
- { from: 1, to: 250_000, price_per_1k: 2. 5 }
- { from: 250_001, to: 1_000_000, price_per_1k: 2. 0 }
credit:
flat: { price_per_unit: 0. 001} # 1 credit = $0. 001 overage:
policy: "postpaid"
rounding: "ceil_1k"
minimum_commit: 99 # basic subscription/month7) 음성 표시: 계정 형성
단계:1. 컷오프 기간 (계정 로케일 별).
2. 업그레이드/다운 그레이드 계획에 따라 평가하십시오 (일별).
3. 사용 등급 + 수정 송장 라인.
4. 고객 위치 및 서비스 지점별 세금 (VAT/GST).
5. 크레딧/할인/쿠폰.
6. 서명 및 게시, 결제 보내기 (PSP), 웹 후크.
음성 라인 (예):json
{
"line_id": "invln_01",
"type": "usage",
"description": "API requests (first 250k)",
"unit": "request",
"quantity": 250000,
"unit_price": 0. 0025,
"amount": 625. 00,
"currency": "USD",
"tax_rate": "VAT20",
"amount_tax": 125. 00
}8) 세금 및 다중 요금
VAT/VAT/GST: 세금 프로파일 유지 (국가, 유효한 VAT-ID, B2B/B2C).
날짜 별 세율 (버전), EU B2B에 대한 역 요금.
FX 변환: 송장 날짜 (ERU/제공자) 의 요금, 요금 출처를 유지하십시오.
문서: 인보이스, 신용 메모, 직불 메모-번호 및 시리즈.
9) 지불, 데이트 및 분쟁
PSP (Stripe/Braintree/Adyen): 토큰 화 된 지불, 거절에 대한 배상, 식사 (1-3-7 일).
분쟁/청구: 상태 수정, 송장에 연결, 상호 작용 일정.
환불: 'payment _ id' 및 'inbice _ id' 와 관련된 부분/전체.
사기 신호: 지리/ASN 이상, 사용 버스트, 다른 카드-청구 플래그.
10) 크레딧, 할인, SLA 크레딧
프로모션 대출 (지갑), SLA 위반에 대한 서비스 크레딧 (다음 기간 자동 시작).
쿠폰: 고정/관심, 최소 기간, 계획/종점에 대한 제한.
투명성: 포털에서 대출의 균형과 상각의 이력을 보여줍니다.
11) 이념과 조정
Idempotency-Key를 통한 모든 쓰기 작업.
조정-원본을 편집하지 않고 조정 이벤트 (양성/음성) 를 통해서만 가능합니다.
조정: 사용량을 매일 검증합니다.
12) 안전 및 준수
게이트웨이의 HMAC/JWT 서명 사용 이벤트
환경 당 개별 키 (prod/stage) 를 섭취하려면 mTLS를 사용하십시오.
PII 최소화 (PAN/메일을 불필요하게 저장하지 마십시오), DSAR/Legal Hold.
금융 거래에 대한 감사 로그 변경 불가능 (추가 전용).
13) 청구 포털 API (OpenAPI 단편)
yaml paths:
/v1/billing/usage:
get:
summary: Usage breakdown parameters: [ {name: from, in: query}, {name: to, in: query}, {name: unit, in: query} ]
responses: {"200": {description: OK}}
/v1/billing/invoices:
get: { summary: List invoices }
/v1/billing/invoices/{id}:
get: { summary: Get invoice (PDF/JSON) }
/v1/billing/credits:
get: { summary: Credit wallet balance }
/v1/webhooks/billing:
post:
summary: Billing webhooks description: "invoice. created, invoice. finalized, payment. succeeded, credit. applied"주요 API 응답의 헤더는 'X-Quota-Remaining', 'X-RateLimit-Remaining', 'X-Usage-Period' 입니다.
14) 웹 후크 및 청구 이벤트
이벤트: '송장. ',' 송장을 만들었습니다. 마무리 된 ',' 지불. '실패' 에 성공했습니다. ',' 크레딧을 다시 시도하십시 ',' 분쟁을 적용했습니다. '폐쇄' 를 열었습니다.
요구 사항: 웹 후크의 서명, 백오프로 반복, 'delivery _ id' 에 의한 중복 제거.
15) 보고 및 비즈니스 지표
금융 KPI:- MRR/ARR (플랜/지리 세분화), ARPU, LTV/CAC, Churn (로고/수익), 순 수익 유지 (NRR).
- 사용 → 수익: 병목 현상 변환 카드 (할당량이 부족한 곳).
- 서비스 비용: 인프라/요청 비용 → 계획 마진.
sql
-- MRR by invoice dates select date_trunc ('month', invoice_date) m, sum (recurring_amount) mrr from f_billing group by 1;
-- ARPU select m, sum(total_amount)/nullif(count(distinct tenant_id),0) arpu from f_billing_monthly group by 1;
-- Cohort by month of activation select cohort_month, month_since_start, sum (total_amount) revenue from f_billing_cohorts;16) DevEx: 셀프 서비스 포털
등록, 계획, 키, 사용 그래프, 인보이스 (PS/JSON), 웹 후크.
업그레이드/다운 그레이드, 송장 미리보기 (pro-forma), 결제 방법 관리.
알림: "쿼터 <10%", "오버 릿지 포함", "송장 발급/지불".
17) 테스트 및 환경
샌드 박스 청구: 더미 PSP, 테스트 세율.
사용 이벤트의 계약 테스트 (스키마/필수 필드).
사슴, 가격 너도밤 나무 회귀 테스트에서 prod 샘플을 재생합니다.
백필은 안전합니다: demempotency를 사용한 배치 수정을 통해서만 가능합니다.
18) FinOps와 관세의 경제
엔드 포인트/플랜의 마진을 고려하십시오: 수익-서비스 비용.
"고가의" 운영을 대출에 할당하고 저계층에서 제한하십시오.
관찰 가능성의 쿼리 비용을 모니터링하고 청구에 대한 링크.
19) 발사 점검표
- 'usage _ 이벤트 '/' 조정 '/' 송장 _ line' 체계가 커밋되고 다양합니다.
- 테스트 된 가격 책 (평면/계층/볼륨), 정확한 용어/재정의.
- 섭취 및 웹 후크의 이념성, 감사 로그 추가 전용.
- 세금/VAT/FX 정확한 고객 프로필이 작성되었습니다.
- 포털: 사용, 송장, 크레딧, 웹 후크; PSP 통합 및 도닝.
- DWH보고 (MRR/ARPU/LTV/Churn/NRR), 매일 조정.
- SLA 신용 및 분쟁 정책이 문서화되어 있습니다.
20) 빈번한 오류 및 패턴 방지
demempotency → 중복 사용/이중 쓰기 없음.
무거운 종점에 대한 대출없이 "요청에 대한 가격" → 마이너스 마진.
클라이언트 → 규정 준수 오류가 아닌 "회사 대신" 세금이 부과됩니다.
세부 사항이없는 음성 → 고객 분쟁.
불일치를보고하는 사용 PSP 인보이스 → 간의 조정이 없습니다.
합계
API에 대한 강력한 청구는 이벤트 중심의 계량 아키텍처, 명확한 가격책, 엄격한 dempotence, 정확한 세금/FX 송장 및 투명한보고입니다. 사용량을 수익에 연결하고, 고객에게 명확한 세부 정보를 제공하며, 이벤트에서 송장, MRR 대시 보드에 이르기까지 전체 여정을 자동화하십시오. 이것은 예측 가능한 소득, 더 적은 분쟁 및 관리 가능한 제품 경제를 제공 할 것입니다.