صدور صورت حساب API و گزارش

1) چرا صدور صورت حساب خود را برای API

کسب درآمد شفاف: لینک استفاده → درآمد.
مقیاس پذیری و کنترل: سهمیه ها، لغو، وام ها، کتاب قیمت با توجه به برنامه ها.
دقت مالی: مالیات/مالیات بر ارزش افزوده، چند ارزی، اعمال و بسته شدن اسناد.
اعتماد مشتری: گزارش های دقیق استفاده، وب سایت ها، پورتال خدمات خود.

2) معماری صورتحساب (سطح بالا)

Producers (API gateway, services) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Tax → Payments (PSP) → Reporting DWH → Client Portal/Webhooks.

• اندازه گیری - جمع آوری و عادی سازی استفاده (درخواست، وام، حجم).
• رتبه بندی - برآورد هزینه رویداد با توجه به قیمت کتاب/برنامه.
• صورتحساب - جمع آوری برای دوره، سود، مالیات، تخفیف، اعتبار.
• پرداخت - نوشتن آف/refands, قدمت (dunning).
• گزارش - MRR/ARPU/LTV، ریزش کوهورت، هزینه برای خدمت.
• حسابرسی - idemotence، سیاهههای مربوط بدون تغییر.

3) اشخاص و شناسه ها

حساب (مستاجر)، طرح، حقوق، رویداد استفاده، فاکتور، یادداشت اعتباری، مشخصات مالیاتی.
حیاتی: idempotency_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
}

قوانین: رویدادها فقط اضافه می شوند ؛ ویرایش ها - از طریق رویدادهای اصلاحی اصلاحی با اشاره به «event _ id».

5) لایه ذخیره سازی و تجمع

5. 1 OLTP (صورتحساب DB)

Таблицы: «مستاجران»، «برنامه ها»، «طرح _ قیمت ها»، «حقوق»، «استفاده _ رویدادها»، «خطوط امتیاز»، «فاکتورها»، «صورتحساب _ خطوط»، «نرخ مالیات»، «اعتبار»، «پرداخت»، «بازپرداخت»، «اختلافات».

5. 2 DWH (تجزیه و تحلیل)

Факты: 'f _ usage', 'f _ billing', 'f _ payments'; ابعاد: d _ tenant، 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 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/month

7) صورتحساب: تشکیل حساب

1. دوره قطع (با حساب محلی).

2. نرخ در برنامه بالا/پایین درجه (به روز).

3. امتیاز استفاده + خطوط فاکتور ثابت.

4. مالیات (مالیات بر ارزش افزوده/GST) توسط محل مشتری و نقطه خدمات.

5. اعتبار/تخفیف/کوپن.

6. امضا و انتشار، ارسال برای پرداخت (PSP)، webhooks.

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) مالیات و چند ارزی

مالیات بر ارزش افزوده/مالیات بر ارزش افزوده/GST: نگه داشتن مشخصات مالیاتی (کشور، معتبر مالیات بر ارزش افزوده ID، B2B/B2C).
نرخ مالیات بر اساس تاریخ (نسخه)، هزینه معکوس برای B2B اتحادیه اروپا.
تبدیل FX: نرخ در تاریخ فاکتور (ERU/ارائه دهنده)، منبع نرخ را نگه دارید.
اسناد: فاکتور، یادداشت اعتباری، یادداشت بدهی - با شماره و سری.

9) پرداخت، تاریخ و اختلافات

PSP (Stripe/Braintree/Adyen): پرداخت های توکن شده، بازپرداخت امتناع، دانینگ (1-3-7 روز).
اختلافات/بازپرداخت: رفع وضعیت، پیوند به فاکتور، جدول زمانی تعامل.
بازپرداخت: جزئی/کامل، مرتبط با «پرداخت _ id» و «فاکتور _ id».
سیگنال های تقلب: ناهنجاری های جغرافیایی/ASN، انفجار استفاده، کارت های مختلف - پرچم در صدور صورت حساب.

10) اعتبار، تخفیف، اعتبار SLA

وام های تبلیغاتی (کیف پول)، اعتبار خدمات برای نقض SLA (شروع خودکار در دوره بعدی).
کوپن: ثابت/بهره, حداقل مدت, محدودیت در طرح/نقاط پایانی.
شفافیت: در پورتال نشان می دهد تعادل وام و تاریخ نوشتن.

11) عدم توانایی و تنظیمات

تمام عملیات نوشتن از طریق Idempotency-Key.
تنظیمات - فقط از طریق حوادث تنظیمات (مثبت/منفی)، بدون ویرایش اصل.
آشتی: تأیید روزانه استفاده فاکتورهای PSP.

12) ایمنی و انطباق

رویدادهای استفاده از امضای HMAC/JWT از دروازه.
mTLS برای مصرف، کلید های فردی در هر محیط (prod/stage).
PII minimization (PAN/mail را بدون نیاز ذخیره نکنید)، 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) وب سایت ها و رویدادهای صورتحساب

رویدادها: "فاکتور. ایجاد شده «،» فاکتور. پرداخت نهايي. موفق شد، دانینگ. دوباره سعی کنید، اعتبار. «،» مشاجره اعمال می شود. باز کرد.
مورد نیاز: امضای webhooks، تکرار با عقب نشینی، deduplication توسط 'delivery _ id'.

15) گزارش و معیارهای کسب و کار

• 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: پورتال خود سرویس

ثبت نام، برنامه ها، کلید ها، نمودارهای استفاده، فاکتورها (PDF/JSON)، وب سایت ها.
ارتقا/پایین آوردن، پیش نمایش فاکتور (pro-forma)، مدیریت روش پرداخت.
اطلاعیه ها: «سهمیه <10٪»، «overidge شامل»، «فاکتور صادر شده/پرداخت شده».

17) تست و محیط زیست

صدور صورت حساب Sandbox: PSP های ساختگی، نرخ مالیات تست.
تست قرارداد رویدادهای استفاده (زمینه های طرح/مورد نیاز).
نمونه ضرب مجدد در گوزن، قیمت آزمون رگرسیون راش.
Backfill امن است: فقط از طریق دسته مصرف با idempopotency.

18) FinOps و اقتصاد تعرفه

حاشیه در نقاط پایانی/برنامه ها را در نظر بگیرید: درآمد − هزینه برای خدمت.
عملیات «گران» را به وام ها اختصاص دهید و در سطوح پایین محدود کنید.
نظارت بر هزینه پرس و جو در مشاهده و لینک به صدور صورت حساب.

19) چک لیست راه اندازی

• 'usage _ event '/' adjustment '/' invoice _ line' schemes متعهد و نسخه هستند.
• قیمت کتاب تست شده (مسطح/ردیف/حجم)، prorate/override درست است.
• Idempotency مصرف و webhooks، حسابرسی ورود به سیستم ضمیمه فقط.
• مالیات/مالیات بر ارزش افزوده/FX درست، پروفایل های مشتری پر شده است.
• پورتال: استفاده، فاکتورها، اعتبارات، وب سایت ها ؛ ادغام PSP و دانینگ.
• گزارش DWH (MRR/ARPU/LTV/Churn/NRR)، آشتی روزانه.
• اعتبار SLA و سیاست های اختلاف مستند شده است.

20) خطاهای مکرر و ضد الگوهای

بدون idempotency → استفاده تکراری/دو بار نوشتن.
قیمت «در مورد درخواست» بدون وام برای نقاط پایانی سنگین → حاشیه منفی.
مالیات «در محل شرکت»، نه مشتری → خطاهای انطباق.
صورتحساب بدون جزئیات → اختلافات مشتری.
بدون مصالحه بین usage↔PSP↔invoysy → گزارش اختلافات.

مجموع

صدور صورت حساب قوی برای رابط های برنامه کاربردی است معماری اندازه گیری رویداد محور, کتاب قیمت روشن, idempotence دقیق, صحیح مالیات/FX صورتحساب, و گزارش شفاف. استفاده از لینک به درآمد، به مشتری جزئیات روشن و به طور خودکار کل سفر - از رویداد به فاکتور به MRR داشبورد. این امر درآمد قابل پیش بینی، اختلافات کمتر و اقتصاد محصول قابل کنترل را فراهم می کند.