חיוב ודיווח של API

1) מדוע להיטען עבור API

כסף שקוף: קישור שימוש = הכנסה.
סקלביליות ושליטה: מכסות, עקיפה, הלוואות, ספר מחירים בהתאם לתוכניות.
דיוק פיננסי: מיסים/מע ”מ, ריבוי מע” מ, פעולות וסגירת מסמכים.
דוחות שימוש מפורטים, פנקסי אינטרנט, פורטל שירות עצמי.

2) ארכיטקטורת חיוב (ברמה גבוהה)

Producers (API gateway, services) * Usage Event Bus (Kafka/Queue) * Mettering & Rating # Billing DB * Invoicing/Mass ac.PSP.

• מטרינג - אוסף ונורמליזציה של שימוש (בקשות, הלוואות, כרכים).
• דירוג - אומדן עלות האירוע בהתאם לספר/תוכנית המחיר.
• חשבוניות - צבירה לתקופה, רווח, מיסים, הנחות, קרדיטים.
• תשלומים - מחיקה/ריפודים, היכרויות (גבייה).
• דיווח - MRR/ARPU/LTV, cohort churn, עלות לשרת.
• ביקורת - אותנטיות, יומנים לא משתנים.

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
}

כללים: אירועים רק מתווספים; עריכה - באמצעות תיקונים אירועי התאמה עם התייחסות ל "אירוע _ id'.

5) שכבת אחסון וצבירה

5. 1 OLTP (חיוב DB)

"דיירים", "תוכניות", "תוכנית _ מחירים", "זכאות", "שימוש _ אירועים", "rated _ lines", "invoices _ lines", "mass _ rates", "cridits'," products "," refunds "," discoves ".

5. 2 DWH (אנליטיקה)

offactive: ”f _ usage”, ”f _ billing”, ”f _ תשלומים”; ממדים: 'd _ derenant', '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. מיסים (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).
שיעורי מס לפי תאריך (גרסה), תשלום הפוך עבור האיחוד האירופי B2B.
המרת FX: קצב בתאריך החשבונית (ERU/despect), שמור על מקור הקצב.
מסמכים: חשבונית, מכתב אשראי, פתק חיוב עם מספרים וסדרות.

9) תשלומים, היכרויות ומחלוקות

PSP (Stripe/Braintree/Adyen): תשלומים מותאמים, מגשים מחדש על סירוב, הטבעה (1-3-7 ימים).
סכסוכים/מטענים: תיקון תקנות, קישור לחשבונית, ציר זמן אינטראקציה.
החזר: חלקי/מלא, המשויך ל ־ ”תשלום _ id' ו ־” invoice _ id'.
אותות הונאה: חריגות גיאו/ASN, התפרצויות שימוש, כרטיסים שונים - דגלים בחיוב.

10) קרדיטים, הנחות, קרדיטים של SLA

הלוואות פרומו (ארנק), אשראי שירות להפרת SLA (התחלה אוטומטית בתקופה הקרובה).
קופונים: קבוע/ריבית, טווח מינימלי, הגבלות על תוכנית/נקודות סוף.
שקיפות: בפורטל ניתן לראות את יתרת ההלוואות ואת היסטוריית המחיקות.

11) אידמפוטנטיות והתאמות

כל פעולות כתיבה באמצעות Idempotency-Key.
התאמות - רק באמצעות התאמות אירועים (חיובי/שלילי), ללא עריכת המקור.
פיוס: אימות יומי של שימוש חשבוניות PSP.

12) בטיחות וציות

אירועי שימוש בחתימת HMAC/JWT מהשער.
MTLS לבלוע, מפתחות בודדים לסביבה (prod/stage).
מזעור PII (לא מאחסנים פאן/דואר שלא לצורך), 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-Lanshared”, ”X-Eathlimit-Leserve”, ”X-Usage-Terry”.

14) חוברות אינטרנט ואירועי חיוב

אירועים: חשבונית. נוצר, חשבונית. סופית, התשלום. הצליח 'feed', 'הגבייה. לנסות מחדש, קרדיט. יישום ”,” מחלוקת. נפתח 'מאוזן'.
דרישות: חתימה של חוברות אינטרנט, חזרה עם גיבוי, שכפול על ידי "deliverse _ id'.

15) דיווח ומדדים עסקיים

• MRR/ARR (תוכנית/גיאו קטגמנטציה), ARPU, LTV/CAC, Churn (לוגו/הכנסות), NET Reservation (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%”, ”היתר כלל”, ”חשבונית שהונפקה/שולמה”.

17) בדיקות וסביבה

חיובים בארגז חול: PSP דמה, שיעורי מס מבחן.
בדיקות חוזה של אירועי שימוש (סכמה/שדות נדרשים).
הדגמה חוזרת באייל, בדיקות רגרסיה.
הילוך אחורי הוא בטוח: רק דרך אצווה-בליעה עם אידמפוטנטיות.

18) פינוקס וכלכלת תעריפים

קח בחשבון את המרווח על נקודות סוף/תוכניות: הכנסות עלות לשרת.
להקצות פעולות ”יקרות” להלוואות ולהגביל ב-low-tiers.
עקוב אחר עלות השאילתה בתצפית וקישור לחיוב.

19) שיגור רשימת בדיקות

[ ] ”usage _ event ”/” adjection ”/” invoice _ line 'schemes” מחויבים ומבוססים.

[ ] Price book שנבדק (flat/tirected/volume), prorate/overcride dick.

[ ] אידמפוטנטיות של בליעה וספרי אינטרנט, ביקורת יומן בלבד.

[ ] מיסוי/מע "מ/FX נכון, פרופילי לקוחות מלאים.

[ ] פורטל: שימוש, חשבוניות, קרדיטים, קורות אינטרנט; אינטגרציה והגבייה.

[ ] DWH דיווח (MRR/ARPU/LTV/Churn/NRR), פיוס יומי.

[ ] מדיניות האשראי והמחלוקות של ה-SLA מתועדים.

20) שגיאות תכופות ותבניות אנטי

אין אידמפוטנטיות * לשכפל שימוש/מחיקה כפולה.
מחיר ”על בקשה” ללא הלוואות עבור נקודות קצה כבדות = מרווח שלילי.
מסים ”במקום החברה”, לא טעויות ציות ללקוח.
חשבוניות ללא פירוט * סכסוכי לקוחות.
אין פיוס בין usage↔PSP↔invoysy כפול דיווח על אי התאמות.

סך הכל

חיוב חזק עבור API הוא ארכיטקטורת מטריצה מונעת אירועים, ספר מחירים ברור, אידמפוטנציה קפדנית, חשבונית מס/FX נכונה ודיווח שקוף. קישור שימוש להכנסות, לתת ללקוח פרטים ברורים ולאוטומט את המסע כולו - מאירוע לחשבונית ללוח מחוונים MRR. זה יספק הכנסות צפויות, פחות מחלוקות וכלכלת מוצרים ניתנת לניהול.