فواتير واجهة برمجة التطبيقات والإبلاغ عنها

1) لماذا الفواتير الخاصة بواجهة برمجة التطبيقات

تحقيق نقد شفاف: رابط الاستخدام → الإيرادات.
قابلية التوسع والتحكم: الحصص، التجاوز، القروض، دفتر الأسعار وفقًا للخطط.
الدقة المالية: الضرائب/ضريبة القيمة المضافة والعملات المتعددة والأعمال والمستندات الختامية.
ثقة العملاء: تقارير الاستخدام التفصيلية، خطافات الويب، بوابة الخدمة الذاتية.

2) بنية الفواتير (رفيعة المستوى)

المنتجون (بوابة API، الخدمات) → حافلة أحداث الاستخدام (كافكا/قائمة الانتظار) → القياس والتصنيف → الفوترة DB → الفواتير/الضرائب → المدفوعات (PSP) → الإبلاغ عن DWH → بوابة العملاء/خطافات الويب.

• القياس - جمع الاستخدام وتطبيعه (الطلبات والقروض والأحجام).
• التصنيف - تقدير تكلفة الحدث وفقا لدفتر الأسعار/الخطة.
• الفواتير - التجميع للفترة، الأرباح، الضرائب، الخصومات، الائتمانات.
• المدفوعات - عمليات الشطب/التجديد، المواعدة (الغرق).
• الإبلاغ - MRR/ARPU/LTV، اضطراب المجموعة، تكلفة الخدمة.
• التدقيق - الخصوصية، السجلات الثابتة.

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 _ falling', '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. الضرائب (ضريبة القيمة المضافة/ضريبة السلع والخدمات) حسب موقع العملاء ونقطة الخدمة.

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) الضرائب والعملات المتعددة

ضريبة القيمة المضافة/ضريبة القيمة المضافة/ضريبة السلع والخدمات: الاحتفاظ بالملف الضريبي (البلد، ضريبة القيمة المضافة الصالحة، B2B/B2C).
معدلات الضرائب حسب التاريخ (الإصدار)، الرسوم العكسية لـ EU B2B.
تحويل العملة الأجنبية: السعر في تاريخ الفاتورة (وحدة خفض الانبعاثات/المزود)، يحتفظ بمصدر السعر.
المستندات: فاتورة، مذكرة ائتمان، مذكرة خصم - بأرقام وسلسلة.

9) المدفوعات والمواعدة والمنازعات

PSP (Stripe/Braintree/Adyen): مدفوعات رمزية، إعادة الدفع عند الرفض، الغمر (1-3-7 أيام).
المنازعات/استرداد التكاليف: تحديد الحالات، والربط بالفاتورة، والجدول الزمني للتفاعل.
المبالغ المستردة: جزئية/كاملة، مرتبطة بـ 'الدفع _ معرف' و 'الفاتورة _ معرف'.
إشارات الاحتيال: شذوذ geo/ASN، انفجارات الاستخدام، بطاقات مختلفة - أعلام في الفوترة.

10) الاعتمادات والخصومات وائتمانات SLA

القروض الترويجية (المحفظة)، ائتمانات الخدمة لانتهاك قانون الأمن العام (بدء التشغيل التلقائي في الفترة التالية).
القسائم: ثابتة/فوائد، الحد الأدنى للأجل، القيود المفروضة على الخطة/نقاط النهاية.
الشفافية: تبين البوابة رصيد القروض وتاريخ عمليات الشطب.

11) الخصوصية والتعديلات

يكتب الجميع العمليات عبر Idempotency-Key.
التعديلات - فقط من خلال أحداث التعديلات (إيجابية/سلبية)، دون تحرير الأصل.
التسوية: التحقق يوميا من استخدام فواتير ↔ rated_lines ↔ ↔ PSP.

12) السلامة والامتثال

أحداث استخدام توقيع HMAC/JWT من البوابة.
mTLS لتناول المفاتيح الفردية لكل بيئة (prod/stage).
تقليل PII (لا تخزن PAN/mail دون داع)، DSAR/Legal Hold.
سجل مراجعة الحسابات غير قابل للتغيير (المرفق فقط) بالنسبة للمعاملات المالية.

13) واجهة برمجة تطبيقات بوابة الفوترة (شظايا 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"

العناوين الرئيسية في ردود واجهة برمجة التطبيقات الرئيسية هي "X-Cota-Remain" و "X-RateLimit-Remain" و "X-Usage-Period'.

14) شبكات الويب وفواتير الأحداث

الأحداث: فاتورة. أنشئت '،' فاتورة. '،' الدفع. نجح "فشل"، "dunning. إعادة المحاولة '،' الائتمان. '،' نزاع. فتحت «مغلقة».
المتطلبات: توقيع الخطابات الشبكية، والتكرار مع التراجع، والتفريغ بواسطة 'التسليم _ الهوية'.

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)، والخطابات الشبكية.
ترقية/تخفيض التصنيف، معاينة الفاتورة (شكلية)، إدارة طريقة الدفع.
الإخطارات: «حصة <10٪»، «زيادة مشمولة»، «فاتورة صادرة/مدفوعة».

17) الاختبار والبيئة

فوترة Sandbox: PSPs وهمية، اختبار معدلات الضرائب.
اختبارات التعاقد على أحداث الاستخدام (المخطط/الحقول المطلوبة).
إعادة تشغيل العينات في الأيل، واختبارات تراجع سعر الزان.
الردم الخلفي آمن: فقط من خلال تناول الدفعة مع الغباء.

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

ضع في اعتبارك الهامش في نقاط/خطط النهاية: الإيرادات − التكلفة للخدمة.
تخصيص عمليات «باهظة الثمن» للقروض والحد من المستويات المنخفضة.
راقب تكلفة الاستعلام في قابلية الملاحظة والربط بالفواتير.

19) قائمة التحقق من الإطلاق

• يتم الالتزام بمقاييس «الاستخدام _ الحدث »/« التعديل »/« الفاتورة _ الخط» والتحقق منها.
• تم اختبار دفتر الأسعار (مسطح/متدرج/مجلد)، التناسب/التجاوز صحيح.
• انعدام القدرة على الابتلاع والخطابات الشبكية، والتذييل بسجل مراجعة الحسابات فقط.
• الضريبة/ضريبة القيمة المضافة/العملة الأجنبية صحيحة، ملء ملفات تعريف العملاء.
• البوابة: الاستخدام، الفواتير، الاعتمادات، الخطابات الشبكية ؛ تكامل PSP والغمر.
• تقرير DWH (MRR/ARPU/LTV/Churn/NRR)، المصالحة اليومية.
• تم توثيق سياسات الائتمان والمنازعات في جيش تحرير السودان.

20) الأخطاء المتكررة والأنماط المضادة

لا → ازدواجية في الاستخدام/شطب مزدوج.
السعر «حول الطلب» بدون قروض لنقاط النهاية الثقيلة → الهامش السلبي.
الضرائب «في مكان الشركة»، وليس العميل → أخطاء الامتثال.
فواتير بدون تفاصيل → منازعات العملاء.
لا توجد تسوية بين usage↔PSP↔invoysy → الإبلاغ عن الاختلافات.

المجموع

الفواتير القوية لواجهات برمجة التطبيقات هي بنية القياس التي تحركها الأحداث، ودفتر الأسعار الواضح، والفطنة الصارمة، وفواتير الضرائب/العملات الأجنبية الصحيحة، والتقارير الشفافة. ربط الاستخدام بالإيرادات، وإعطاء العميل تفاصيل واضحة وأتمتة الرحلة بأكملها - من الحدث إلى الفاتورة إلى لوحة القيادة MRR. سيوفر هذا دخلاً يمكن التنبؤ به ونزاعات أقل واقتصاد منتج يمكن التحكم فيه.