Penagihan

Sekilas pandang

NextPDF Enterprise melacak penggunaan compute-unit (CU) per tenant terhadap kuota plan dan menerapkan kebijakan kelebihan yang dapat dikonfigurasi: blokir keras, blokir dengan panduan coba-ulang, atau lanjutkan dan beri peringatan. Ia juga memicu peringatan penggunaan yang terdeduplikasi pada ambang 80%, 100%, dan anggaran-terlampaui. Halaman ini menjelaskan perilaku billing yang dapat diamati dan kontrak publiknya.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan amplop lisensi tingkat-Enterprise. Sebuah penerapan tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Billing adalah kapabilitas dasar Enterprise tanpa flag per-fitur terpisah; tingkatan plan dan kuota yang disertakannya diresolusi melalui registri plan.

Tinjauan konseptual

Billing mengukur konsumsi dalam compute unit. Setiap tenant berjalan di bawah sebuah plan; setiap plan membawa kuota CU yang disertakan dan himpunan kapabilitas. Tiga tingkatan plan baku disertakan — Standard, Advanced, dan High Control — dengan kuota yang disertakan yang semakin besar dan himpunan kapabilitas yang semakin luas (tingkatan yang lebih tinggi menambahkan paket add-on Intelligence dan Privacy). Registri adalah lookup kanonik; sebuah penerapan white-label dapat mengonstruksinya dengan definisi khusus.

Kebijakan kelebihan memutuskan apa yang terjadi ketika sebuah tenant melewati kuota yang disertakannya. Kebijakan hard-stop memblokir pemrosesan segera dan membawa semantik HTTP 402. Kebijakan soft-stop memblokir dengan panduan coba-ulang dan membawa HTTP 429. Kebijakan budget-alert tidak pernah memblokir — pemrosesan berlanjut dan peringatan dipicu sebagai gantinya, membawa HTTP 200. Hanya hard-stop dan soft-stop yang memblokir; manajer kuota memunculkan kondisi kuota-terlampaui hanya ketika kebijakan memblokir dan kuota yang disertakan benar-benar terlampaui.

Layanan peringatan mengevaluasi penggunaan terhadap ambang dalam urutan menaik — peringatan 80%, peringatan 100%, lalu anggaran-terlampaui — dan setiap tipe peringatan dipicu paling banyak sekali per periode billing per tenant. Anggaran-terlampaui memerlukan kelebihan yang ketat, bukan sekadar mencapai 100%. Keadaan peringatan dilacak melalui antarmuka repositori, sehingga deduplikasi bertahan lintas permintaan, dan layanan memaparkan operasi yang jelas untuk mereset keadaan peringatan pada pergantian periode billing.

Mengapa ia bekerja demikian

Billing dibangun sebagai lapisan keputusan murni, bukan sistem penyimpanan. Pemeriksaan kuota, perhitungan kelebihan, dan evaluasi peringatan berjalan di memori terhadap sebuah PlanDefinition dan satu angka penggunaan-saat-ini, tanpa I/O pada jalur pemeriksaan. Persistensi berada di luar keputusan itu: keadaan dedup-peringatan hanya dijangkau melalui AlertStateRepositoryInterface yang disediakan operator, yang menjaga durabilitas dan batas periode-billing tetap dalam kendali host. Hasil kelebihan adalah enum eksplisit kecil yang memetakan setiap kebijakan ke status HTTP tetap, sehingga keputusan blokir-atau-lanjut tetap deterministik dan dapat diaudit. Pemisahan itu memungkinkan permukaan billing yang sama berjalan tanpa perubahan dari satu instans hingga armada multi-tenant bermeter. Latar desain: Mengoperasikan NextPDF di produksi.

Permukaan API publik

composer require nextpdf/enterprise:^3

Titik integrasi yang didukung adalah registri plan (get, has, defaultRegistry), manajer kuota (checkQuota, remainingQuota, usagePercentage), kalkulator kelebihan (calculate, mengembalikan hasil kelebihan imutabel), enum kebijakan kelebihan (httpStatusCode, isBlocking), dan layanan peringatan billing (evaluate, clearAlerts). Repositori keadaan-peringatan adalah sebuah antarmuka — sediakan implementasi in-memory untuk pengujian atau yang durabel untuk produksi.

Contoh kode — mulai cepat

use NextPDF\Enterprise\Billing\OverageCalculator;
use NextPDF\Enterprise\Billing\PlanRegistry;
use NextPDF\Enterprise\Billing\SaaSPlan;

$plan   = PlanRegistry::defaultRegistry()->get(SaaSPlan::Standard);
$result = (new OverageCalculator())->calculate($plan, currentCu: 1_250.0);

$result->isOverage;   // true — 1,250 CU against a 1,000 CU included quota
$result->overageCu;   // 250.0
$result->usageRatio;  // 1.25

Contoh kode — produksi

use NextPDF\Enterprise\Billing\OveragePolicy;
use NextPDF\Enterprise\Billing\QuotaExceededException;
use NextPDF\Enterprise\Billing\QuotaManager;

$manager = new QuotaManager($registry, OveragePolicy::SoftStop);

try {
    $manager->checkQuota($tenant, SaaSPlan::Advanced, $currentCu);
} catch (QuotaExceededException $e) {
    // SoftStop → answer with 429 + Retry-After up to the reset instant.
    return $this->retryAfter($e->resetsAt);
}

foreach ($alertService->evaluate($tenant, $plan, $planDef, $currentCu) as $alert) {
    $this->notify($tenant, $alert->severity(), $alert);
}

Kasus tepi & jebakan

• Budget-alert tidak pernah memblokir. Di bawah kebijakan budget-alert, checkQuota tidak memunculkan eksepsi bahkan jauh melewati kuota; andalkan peringatan yang dipicu, bukan sebuah eksepsi.
• Anggaran-terlampaui memerlukan kelebihan yang ketat. Mencapai tepat 100% memicu peringatan 100%, bukan anggaran-terlampaui; anggaran-terlampaui memerlukan penggunaan yang benar-benar di atas kuota yang disertakan.
• Peringatan terdeduplikasi per periode. Setiap tipe peringatan dipicu sekali per tenant per periode billing. Bersihkan keadaan peringatan pada pergantian periode atau peringatan tidak akan dipicu ulang pada periode berikutnya.
• Kuota yang disertakan nol atau tak diatur. Plan dengan kuota disertakan yang non-positif melaporkan rasio penggunaan 0.0 alih-alih membagi dengan nol.
• Reset periode adalah batas bulan berikutnya. Saat reset kuota-terlampaui baku adalah hari pertama bulan kalender berikutnya pada tengah malam.

Kinerja

Pemeriksaan kuota, perhitungan kelebihan, dan evaluasi peringatan adalah operasi waktu-konstan, in-memory terhadap sebuah definisi plan dan angka penggunaan-saat-ini yang disediakan. Tidak ada I/O pada jalur pemeriksaan kecuali implementasi repositori keadaan-peringatan Anda melakukannya.

Catatan keamanan

Keputusan billing diturunkan dari angka penggunaan-saat-ini yang dibatasi-tenant yang disediakan oleh pemanggil; identitas tenant harus berasal dari konteks terautentikasi, tidak pernah dari masukan yang disediakan-klien. Permukaan billing menegakkan kuota dan memancarkan peringatan — ia tidak mengautentikasi tenant itu sendiri.

Kesesuaian

Hasil kebijakan-kelebihan membawa semantik status HTTP standar: payment-required (402) untuk hard-stop, too-many-requests (429) dengan panduan coba-ulang untuk soft-stop, dan success (200) untuk budget-alert, mengikuti spesifikasi semantik HTTP IETF (RFC 9110) untuk kelas 402, 429, dan 2xx. RFC 9110 tidak diambil dari korpus RAG untuk halaman ini; pemetaan ini ditegaskan dari kode status yang dideklarasikan-kode dan spesifikasi semantik HTTP yang umum dikenal, ditandai di sini sebagai dideklarasikan-kode alih-alih terverifikasi-RAG.

Kontrak perilaku

• Konsumsi diukur dalam compute unit; setiap tenant berjalan di bawah sebuah plan dengan kuota CU yang disertakan dan himpunan kapabilitas.
• Kebijakan kelebihan adalah salah satu dari hard-stop (402, memblokir), soft-stop (429 dengan panduan coba-ulang, memblokir), atau budget-alert (200, tidak memblokir); kondisi kuota-terlampaui dimunculkan hanya ketika kebijakan memblokir dan kuota yang disertakan benar-benar terlampaui.
• Peringatan dievaluasi dalam urutan menaik (peringatan 80%, peringatan 100%, anggaran-terlampaui) dan setiap tipe dipicu paling banyak sekali per periode billing per tenant; anggaran-terlampaui memerlukan kelebihan yang ketat.
• Kuota disertakan yang non-positif melaporkan rasio penggunaan 0.0 alih-alih membagi dengan nol.
• Pemeriksaan kuota, perhitungan kelebihan, dan evaluasi peringatan adalah operasi in-memory waktu-konstan tanpa I/O pada jalur pemeriksaan kecuali repositori keadaan-peringatan melakukannya.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas pembantu, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Fallback Core

NextPDF Core (Apache-2.0) tidak memiliki permukaan billing, kuota, atau kelebihan — tidak ada; kapabilitas ini tidak memiliki padanan tingkat-Core. Pemrosesan Core tidak diukur, tidak dibatasi-kuota, atau diberi peringatan oleh NextPDF.

Fallback Pro

NextPDF Pro tidak memiliki permukaan billing, kuota, atau kelebihan — tidak ada; kapabilitas ini tidak memiliki padanan tingkat-Pro. Registri plan, manajer kuota, kalkulator kelebihan, dan layanan peringatan disertakan hanya dalam paket nextpdf/enterprise.

Catatan batas Enterprise

Registri plan, kebijakan kelebihan, dan deduplikasi peringatan dijelaskan pada tingkat perilaku. Repositori keadaan-peringatan adalah sebuah antarmuka; persistensi durabel disediakan oleh host, dan strategi penyimpanan keadaan-peringatan internal berada di luar cakupan permukaan publik.

Batas penerapan

Keputusan billing diturunkan dari angka penggunaan-saat-ini yang dibatasi-tenant yang disediakan oleh pemanggil. Operator memiliki implementasi repositori keadaan-peringatan, persistensinya, dan jadwal pergantian periode-billing. NextPDF Enterprise menegakkan kuota dan memancarkan peringatan tetapi tidak mengautentikasi tenant atau mempersistensikan penggunaan itu sendiri.

Batas kepatuhan hukum

Tidak ada restriksi kontrol-ekspor yang berlaku pada permukaan billing. Inklusi plan, kuota, dan ketentuan komersial diatur oleh perjanjian lisensi Anda, bukan oleh penegakan runtime. Dokumentasi ini bukan opini hukum atau kontraktual; konsultasikan dengan penasihat Anda sendiri dan perjanjian Anda untuk cakupan plan.

Lihat juga

• Penagihan — referensi NextPDF Enterprise
• Metering — NextPDF Enterprise
• SaaS — NextPDF Enterprise
• Licensing — NextPDF Enterprise