Enterprise édition

Facturation

En bref

NextPDF Enterprise suit la consommation en unités de calcul (CU) par locataire au regard d’un quota de plan et applique une politique de dépassement configurable : bloquer durement, bloquer avec des indications de réessai, ou continuer et alerter. Il déclenche également des alertes d’utilisation dédupliquées aux seuils de 80 %, 100 % et budget dépassé. Cette page décrit le comportement de facturation observable et le contrat public.

Disponibilité & licence

Cette capacité est livrée dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de palier Enterprise. Un déploiement dépourvu de cette habilitation ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

La facturation est une capacité Enterprise de base sans indicateur distinct par fonctionnalité ; les paliers de plan et leurs quotas inclus se résolvent via le registre de plans.

Vue d’ensemble conceptuelle

La facturation mesure la consommation en unités de calcul. Chaque locataire s’exécute sous un plan ; chaque plan porte un quota de CU inclus et un ensemble de capacités. Trois paliers de plan par défaut sont livrés — Standard, Advanced et High Control — avec des quotas inclus progressivement plus larges et des ensembles de capacités progressivement plus étendus (les paliers supérieurs ajoutent les packs complémentaires Intelligence et Privacy). Le registre est la consultation canonique ; un déploiement en marque blanche peut le construire avec des définitions personnalisées.

La politique de dépassement décide de ce qui se passe lorsqu’un locataire dépasse son quota inclus. Une politique de blocage dur (hard-stop) bloque immédiatement le traitement et porte la sémantique HTTP 402. Une politique de blocage souple (soft-stop) bloque avec des indications de réessai et porte la sémantique HTTP 429. Une politique d’alerte budgétaire (budget-alert) ne bloque jamais — le traitement continue et des alertes se déclenchent à la place, portant la sémantique HTTP 200. Seuls hard-stop et soft-stop sont bloquants ; le gestionnaire de quotas lève une condition de dépassement de quota uniquement lorsque la politique bloque et que le quota inclus est réellement dépassé.

Le service d’alerte évalue l’utilisation au regard des seuils en ordre croissant — avertissement à 80 %, avertissement à 100 %, puis budget dépassé — et chaque type d’alerte se déclenche au plus une fois par période de facturation et par locataire. Le seuil budget dépassé nécessite un dépassement strict, et non le simple fait d’atteindre 100 %. L’état des alertes est suivi via une interface de dépôt, de sorte que la déduplication survit aux requêtes, et le service expose une opération claire pour réinitialiser l’état des alertes au basculement de période de facturation.

Pourquoi ça fonctionne ainsi

La facturation est conçue comme une pure couche de décision, et non comme un système de stockage. Les vérifications de quota, le calcul de dépassement et l’évaluation des alertes s’exécutent en mémoire au regard d’un PlanDefinition et d’une seule valeur d’utilisation courante, sans E/S sur le chemin de vérification. La persistance se situe en dehors de cette décision : l’état de déduplication des alertes n’est atteint qu’à travers l’AlertStateRepositoryInterface fournie par un opérateur, ce qui maintient la durabilité et la frontière de période de facturation sous le contrôle de l’hôte. Le résultat de dépassement est un petit enum explicite qui associe chaque politique à un statut HTTP fixe, de sorte que la décision de bloquer ou de continuer reste déterministe et auditable. Cette séparation permet à la même surface de facturation de s’exécuter sans changement, d’une instance unique à une flotte mesurée multi-locataire. Contexte de conception : Exploiter NextPDF en production.

Surface d’API publique

composer require nextpdf/enterprise:^3

Les points d’intégration pris en charge sont le registre de plans (get, has, defaultRegistry), le gestionnaire de quotas (checkQuota, remainingQuota, usagePercentage), le calculateur de dépassement (calculate, renvoyant un résultat de dépassement immuable), l’enum de politique de dépassement (httpStatusCode, isBlocking) et le service d’alerte de facturation (evaluate, clearAlerts). Le dépôt d’état des alertes est une interface — fournis une implémentation en mémoire pour les tests ou une implémentation durable pour la production.

Exemple de code — Démarrage rapide

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

Exemple de code — Production

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);
}

Cas limites & pièges

L’alerte budgétaire ne bloque jamais. Sous une politique d’alerte budgétaire, checkQuota ne lève rien même bien au-delà du quota ; appuie-toi sur les alertes déclenchées, et non sur une exception.
Le budget dépassé nécessite un dépassement strict. Atteindre exactement 100 % déclenche l’avertissement à 100 %, et non le budget dépassé ; le budget dépassé nécessite une utilisation strictement supérieure au quota inclus.
Les alertes se dédupliquent par période. Chaque type d’alerte se déclenche une fois par locataire et par période de facturation. Réinitialise l’état des alertes au basculement de période, sinon les alertes ne se redéclenchent pas la période suivante.
Quota inclus nul ou non défini. Un plan avec un quota inclus non positif rapporte un ratio d’utilisation de 0.0 plutôt que de diviser par zéro.
La réinitialisation de période est la frontière du mois suivant. L’instant de réinitialisation par défaut après dépassement de quota est le premier jour du mois civil suivant à minuit.

Performance

Les vérifications de quota, le calcul de dépassement et l’évaluation des alertes sont des opérations en mémoire à temps constant au regard d’une définition de plan et de la valeur d’utilisation courante fournie. Il n’y a aucune E/S sur le chemin de vérification, sauf si ton implémentation de dépôt d’état des alertes en effectue.

Notes de sécurité

Les décisions de facturation sont dérivées d’une valeur d’utilisation courante délimitée par locataire et fournie par l’appelant ; l’identité du locataire doit provenir d’un contexte authentifié, jamais d’une entrée fournie par le client. La surface de facturation applique le quota et émet des alertes — elle n’authentifie pas elle-même le locataire.

Conformité

Les résultats de la politique de dépassement portent une sémantique de statut HTTP standard : paiement requis (402) pour le blocage dur, trop de requêtes (429) avec indications de réessai pour le blocage souple, et succès (200) pour l’alerte budgétaire, conformément à la spécification de sémantique HTTP de l’IETF (RFC 9110) pour les classes 402, 429 et 2xx. RFC 9110 n’a pas été récupérée du corpus RAG pour cette page ; cette correspondance est affirmée à partir des codes de statut déclarés dans le code et de la spécification de sémantique HTTP bien connue, indiquée ici comme déclarée par le code plutôt que vérifiée par RAG.

Contrat de comportement

La consommation est mesurée en unités de calcul ; chaque locataire s’exécute sous un plan avec un quota de CU inclus et un ensemble de capacités.
La politique de dépassement est l’une parmi blocage dur (402, bloquant), blocage souple (429 avec indications de réessai, bloquant) ou alerte budgétaire (200, non bloquant) ; une condition de dépassement de quota n’est levée que lorsque la politique bloque et que le quota inclus est réellement dépassé.
Les alertes s’évaluent en ordre croissant (avertissement à 80 %, avertissement à 100 %, budget dépassé) et chaque type se déclenche au plus une fois par période de facturation et par locataire ; le budget dépassé nécessite un dépassement strict.
Un quota inclus non positif rapporte un ratio d’utilisation de 0.0 plutôt que de diviser par zéro.
Les vérifications de quota, le calcul de dépassement et l’évaluation des alertes sont des opérations en mémoire à temps constant sans E/S sur le chemin de vérification, sauf si le dépôt d’état des alertes en effectue.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espace de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Repli sur le Core

NextPDF Core (Apache-2.0) n’a aucune surface de facturation, de quota ou de dépassement — aucune ; cette capacité n’a aucun équivalent au palier Core. Le traitement Core n’est ni mesuré, ni soumis à quota, ni alerté par NextPDF.

Repli sur Pro

NextPDF Pro n’a aucune surface de facturation, de quota ou de dépassement — aucune ; cette capacité n’a aucun équivalent au palier Pro. Le registre de plans, le gestionnaire de quotas, le calculateur de dépassement et le service d’alerte sont livrés uniquement dans le paquet nextpdf/enterprise.

Note sur la frontière Enterprise

Le registre de plans, la politique de dépassement et la déduplication des alertes sont décrits au niveau du comportement. Le dépôt d’état des alertes est une interface ; la persistance durable est fournie par l’hôte, et la stratégie interne de stockage de l’état des alertes est hors du périmètre de la surface publique.

Frontière de déploiement

Les décisions de facturation sont dérivées d’une valeur d’utilisation courante délimitée par locataire et fournie par l’appelant. L’opérateur est propriétaire de l’implémentation du dépôt d’état des alertes, de sa persistance et du calendrier de basculement de période de facturation. NextPDF Enterprise applique le quota et émet des alertes mais n’authentifie pas lui-même le locataire et ne persiste pas l’utilisation.

Frontière de conformité légale

Aucune restriction de contrôle des exportations ne s’applique à la surface de facturation. Les inclusions de plan, les quotas et les conditions commerciales sont régis par ton contrat de licence, et non par une application à l’exécution. Cette documentation n’est pas un avis juridique ni contractuel ; consulte tes propres conseillers et ton contrat pour le périmètre des plans.