Τιμολόγηση και υποβολή εκθέσεων API

1) Γιατί η ίδια η χρέωση για API

Διαφανής νομιμοποίηση: σύνδεση χρήσης → έσοδα.
Επεκτασιμότητα και έλεγχος: ποσοστώσεις, παράκαμψη, δάνεια, φάκελος τιμών σύμφωνα με τα σχέδια.
Δημοσιονομική ακρίβεια: φόροι/ΦΠΑ, πολλαπλά νομίσματα, πράξεις και έγγραφα κλεισίματος.
Εμπιστοσύνη πελατών: λεπτομερείς αναφορές χρήσης, webhooks, πύλη αυτοεξυπηρέτησης.

2) Αρχιτεκτονική τιμολόγησης (υψηλού επιπέδου)

Οι παραγωγοί (πύλη API, υπηρεσίες) → Usage Event Bus (Kafka/Queue) → Metering & Rating → Billing DB → Invoicing/Taxes → Payments (PSP) → Reporting DWH → Client Portal/Webhooks.

• Μέτρηση - συλλογή και ομαλοποίηση της χρήσης (αιτήματα, δάνεια, όγκοι).
• Αξιολόγηση - εκτίμηση του κόστους του γεγονότος σύμφωνα με το βιβλίο τιμών/το σχέδιο.
• Τιμολόγηση - ομαδοποίηση για την περίοδο, κέρδη, φόροι, εκπτώσεις, πιστώσεις.
• Πληρωμές - διαγραφές/διορθώσεις, χρονολόγηση (dunning).
• Υποβολή εκθέσεων - MRR/ARPU/LTV, κλάση 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)

: «ενοικιαστές», «σχέδια», «σχέδιο _ τιμές», «δικαιώματα», «χρήση _ εκδηλώσεις», «βαθμολογημένες _ γραμμές», «τιμολόγια», «τιμολόγιο _ γραμμές», «φόρος _ συντελεστές», «πιστώσεις», «πληρωμές», «επιστροφές», «διαφορές».

5. 2 DWH (ανάλυση)

: 'f _ use', 'f _ billing', 'f _ payment Факты, διαστάσεις: "d _ ενοικιαστής", "d _ plan", "d _ endpoin ," 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) Βιβλίο τιμών και διαβάθμιση (διαβάθμιση)

Μοντέλα υποστήριξης: επίπεδη, κλιμακωτή, όγκος, δεσμοποιημένες πιστώσεις, πληρωμή-as-you-go, και παράκαμψη.

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: διατήρηση του φορολογικού προφίλ (χώρα, ισχύουσα ταυτότητα ΦΠΑ, B2B/B2C).
Φορολογικοί συντελεστές ανά ημερομηνία (έκδοση), αντιστροφή της επιβάρυνσης για την EU B2B.
Μετατροπή FX: ισοτιμία κατά την ημερομηνία τιμολογίου (ERU/πάροχος), διατήρηση της πηγής της ισοτιμίας.
Έγγραφα: τιμολόγιο, πιστωτικό σημείωμα, χρεωστικό σημείωμα - με αριθμούς και σειρές.

9) Πληρωμές, ημερομηνίες και διαφορές

PSP (Stripe/Braintree/Adyen): μαρκαρισμένες πληρωμές, retrays κατά την απόρριψη, dunning (1-3-7 ημέρες).
Διαφορές/χρέωση: καθορισμός καταστατικών, σύνδεση με τιμολόγιο, χρονοδιάγραμμα αλληλεπίδρασης.
Επιστροφές: μερικές/πλήρεις, που συνδέονται με «πληρωμή _ id» και «τιμολόγιο _ id».
Σήματα απάτης: γεωγραφικές/ASN ανωμαλίες, εκρήξεις χρήσης, διαφορετικές κάρτες - σημαίες χρέωσης.

10) Πιστώσεις, εκπτώσεις, πιστώσεις SLA

Promo δάνεια (πορτοφόλι), πιστώσεις εξυπηρέτησης για παραβίαση της SLA (αυτόματη εκκίνηση την επόμενη περίοδο).
Τοκομερίδια: σταθεροί/τόκοι, ελάχιστη διάρκεια, περιορισμοί στο σχέδιο/τελικά σημεία.
Διαφάνεια: στην πύλη παρουσιάζονται το υπόλοιπο των δανείων και η ιστορία των διαγραφών.

11) Ιδιαιτερότητα και προσαρμογές

Όλες οι λειτουργίες εγγραφής μέσω Idempotency-Key.
Προσαρμογές - μόνο μέσω προσαρμογών γεγονότων (θετικών/αρνητικών), χωρίς επεξεργασία του πρωτοτύπου.
Αντιστοίχιση: καθημερινή επαλήθευση της χρήσης τιμολογίων ΠΥΠ.

12) Ασφάλεια και συμμόρφωση

Γεγονότα χρήσης υπογραφής HMAC/JWT από την πύλη.
mTLS για κατάποση, μεμονωμένα κλειδιά ανά περιβάλλον (prod/stage).
Ελαχιστοποίηση 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-Ποσοστώσεις-Υπόλοιπο», «X- όριο-υπόλοιπο», «X-περίοδος χρήσης».

14) Webhooks και εκδηλώσεις τιμολόγησης

Γεγονότα: "τιμολόγιο. δημιουργήθηκε ',' τιμολόγιο. οριστικοποιημένη πληρωμή ','. πέτυχε 'failed', 'dunning. retry ',' credit. εφαρμοζόμενη διαφορά «,». ανοιχτό 'closed'.
Απαιτήσεις: υπογραφή webhooks, επανάληψη με backoff, αφαίρεση από '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), webhooks.
Αναβάθμιση/υποβάθμιση, προεπισκόπηση τιμολογίου (pro-forma), διαχείριση μεθόδων πληρωμής.
Κοινοποιήσεις: «ποσόστωση <10%», «συμπεριλαμβανομένης της υπέρβασης», «εκδοθέν/καταβληθέν τιμολόγιο».

17) Δοκιμές και περιβάλλον

Τιμολόγηση Sandbox: εικονική PSP, συντελεστές φόρου δοκιμής.
Συμβατικές δοκιμές συμβάντων χρήσης (σχήματα/απαιτούμενα πεδία).
Επαναλάβετε δείγματα prod στο ελάφι, δοκιμές παλινδρόμησης της οξιάς.
Η οπισθοπλήρωση είναι ασφαλής: μόνο μέσω της κατάποσης παρτίδων με ιδιοτέλεια.

18) FinOps και τα οικονομικά των τιμολογίων

Εξετάστε το περιθώριο για τα τελικά σημεία/σχέδια: έσοδα − κόστος προς εξυπηρέτηση.
Διάθεση «δαπανηρών» πράξεων σε δάνεια και περιορισμός σε χαμηλά επίπεδα.
Παρακολούθηση του κόστους των ερωτήσεων όσον αφορά την παρατηρησιμότητα και σύνδεση με την τιμολόγηση.

19) Κατάλογος ελέγχου εκτόξευσης

• Το 'usage _ event '/' adjustment '/' pricoice _ line' schemes δεσμεύεται και ενημερώνεται.
• Έλεγχος τιμολογίου (επίπεδο/κλιμακωτό/όγκο), ορθή προφορά/παράκαμψη.
• Ευελιξία κατάποσης και webhooks, μόνο προσθήκη λογιστικού ελέγχου.
• Ο φόρος/ΦΠΑ/FX είναι σωστός, συμπληρώνονται τα προφίλ των πελατών.
• Πύλη: χρήση, τιμολόγια, πιστώσεις, webhooks. Ολοκλήρωση και αποσύνδεση PSP.
• Αναφορά DWH (MRR/ARPU/LTV/Churn/NRR), συμφωνία καθημερινά.
• Τεκμηριώνονται οι πολιτικές πιστώσεων και διαφορών της SLA.

20) Συχνά σφάλματα και αντι-πρότυπα

Καμία ταυτότητα → διπλή χρήση/διπλή διαγραφή.
Τιμή «περί αιτήματος» χωρίς δάνεια για μεγάλα τελικά σημεία → αρνητικό περιθώριο.
Φόροι «στον τόπο της εταιρείας», όχι σφάλματα συμμόρφωσης → πελάτη.
Τιμολόγια χωρίς λεπτομέρειες → διαφορές πελατών.
Δεν υπάρχει συμφωνία μεταξύ usage↔PSP↔invoysy → αναγγελιών διαφορών.

Σύνολο

Η ισχυρή τιμολόγηση των API είναι η αρχιτεκτονική μέτρησης με γνώμονα τα γεγονότα, το σαφές βιβλίο τιμών, η αυστηρή ταυτότητα, η ορθή τιμολόγηση φόρου/FX και η διαφανής υποβολή εκθέσεων. Σύνδεση της χρήσης με τα έσοδα, παροχή στον πελάτη σαφών στοιχείων και αυτοματοποίηση ολόκληρης της διαδρομής - από γεγονός σε τιμολόγιο έως ταμπλό MRR. Αυτό θα προσφέρει προβλέψιμα εισοδήματα, λιγότερες διαφορές και μια διαχειρίσιμη οικονομία προϊόντων.