Enterprise edición

Facturación

De un vistazo

NextPDF Enterprise rastrea el uso de unidades de cómputo (CU) por inquilino frente a una cuota de plan y aplica una política de exceso configurable: bloqueo estricto, bloqueo con orientación de reintento, o continuar y alertar. También dispara alertas de uso deduplicadas en los umbrales del 80 %, del 100 % y de presupuesto superado. Esta página describe el comportamiento de facturación observable y el contrato público.

Disponibilidad y licenciamiento

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un envoltorio de licencia de nivel Enterprise. Un despliegue sin esa titularidad no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

La facturación es una capacidad base de Enterprise sin ningún indicador por característica independiente; los niveles de plan y sus cuotas incluidas se resuelven a través del registro de planes.

Descripción conceptual

La facturación mide el consumo en unidades de cómputo. Cada inquilino se ejecuta bajo un plan; cada plan transporta una cuota de CU incluida y un conjunto de capacidades. Se distribuyen tres niveles de plan predeterminados —Standard, Advanced y High Control— con cuotas incluidas progresivamente mayores y conjuntos de capacidades progresivamente más amplios (los niveles superiores añaden los paquetes complementarios de Intelligence y Privacy). El registro es la consulta canónica; una implementación de marca blanca puede construirlo con definiciones personalizadas.

La política de exceso decide qué ocurre cuando un inquilino supera su cuota incluida. Una política de bloqueo estricto bloquea el procesamiento inmediatamente y transporta la semántica HTTP 402. Una política de bloqueo suave bloquea con orientación de reintento y transporta HTTP 429. Una política de alerta de presupuesto nunca bloquea — el procesamiento continúa y, en su lugar, se disparan alertas, transportando HTTP 200. Solo el bloqueo estricto y el bloqueo suave son bloqueantes; el gestor de cuotas plantea una condición de cuota superada únicamente cuando la política bloquea y la cuota incluida se supera realmente.

El servicio de alertas evalúa el uso frente a los umbrales en orden ascendente —advertencia del 80 %, advertencia del 100 %, y después presupuesto superado— y cada tipo de alerta se dispara como máximo una vez por período de facturación por inquilino. El presupuesto superado requiere un exceso estricto, no simplemente alcanzar el 100 %. El estado de las alertas se rastrea a través de una interfaz de repositorio, de modo que la deduplicación sobrevive entre solicitudes, y el servicio expone una operación clara para restablecer el estado de las alertas en el cambio de período de facturación.

Por qué funciona así

La facturación está construida como una capa de decisión pura, no como un sistema de almacenamiento. Las comprobaciones de cuota, la aritmética de excesos y la evaluación de alertas se ejecutan en memoria frente a una PlanDefinition y una única cifra de uso actual, sin E/S en la ruta de comprobación. La persistencia queda fuera de esa decisión: el estado de deduplicación de alertas se alcanza únicamente a través de la AlertStateRepositoryInterface que suministra un operador, lo que mantiene la durabilidad y el límite del período de facturación bajo control del host. El resultado del exceso es un pequeño enum explícito que asigna cada política a un estado HTTP fijo, de modo que la decisión de bloquear o continuar permanece determinista y auditable. Esa separación permite que la misma superficie de facturación se ejecute sin cambios desde una única instancia hasta una flota multiinquilino medida. Contexto de diseño: Operar NextPDF en producción.

Superficie pública de la API

composer require nextpdf/enterprise:^3

Los puntos de integración admitidos son el registro de planes (get, has, defaultRegistry), el gestor de cuotas (checkQuota, remainingQuota, usagePercentage), el calculador de excesos (calculate, que devuelve un resultado de exceso inmutable), el enum de política de exceso (httpStatusCode, isBlocking) y el servicio de alertas de facturación (evaluate, clearAlerts). El repositorio de estado de alertas es una interfaz — suministre una implementación en memoria para las pruebas o una duradera para producción.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

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

Casos límite y trampas

La alerta de presupuesto nunca bloquea. Bajo una política de alerta de presupuesto, checkQuota no genera ningún error ni siquiera muy por encima de la cuota; confíe en las alertas disparadas, no en una excepción.
El presupuesto superado necesita un exceso estricto. Alcanzar exactamente el 100 % dispara la advertencia del 100 %, no el presupuesto superado; el presupuesto superado requiere un uso estrictamente por encima de la cuota incluida.
Las alertas se deduplican por período. Cada tipo de alerta se dispara una vez por inquilino por período de facturación. Borre el estado de las alertas en el cambio de período o las alertas no se vuelven a disparar el período siguiente.
Cuota incluida nula o no establecida. Un plan con una cuota incluida no positiva informa de una proporción de uso de 0.0 en lugar de dividir por cero.
El restablecimiento de período es el límite del mes siguiente. El instante de restablecimiento de cuota superada predeterminado es el primer día del mes natural siguiente a medianoche.

Rendimiento

Las comprobaciones de cuota, el cálculo de excesos y la evaluación de alertas son operaciones en memoria de tiempo constante frente a una definición de plan y la cifra de uso actual suministrada. No hay E/S en la ruta de comprobación a menos que la implementación de su repositorio de estado de alertas la realice.

Notas de seguridad

Las decisiones de facturación se derivan de una cifra de uso actual acotada por inquilino y suministrada por el llamante; la identidad del inquilino debe provenir de un contexto autenticado, nunca de una entrada suministrada por el cliente. La superficie de facturación aplica la cuota y emite alertas — no autentica por sí misma al inquilino.

Conformidad

Los resultados de la política de exceso transportan la semántica estándar de los códigos de estado HTTP: pago requerido (402) para el bloqueo estricto, demasiadas solicitudes (429) con orientación de reintento para el bloqueo suave y éxito (200) para la alerta de presupuesto, siguiendo la especificación de semántica HTTP de la IETF (RFC 9110) para las clases 402, 429 y 2xx. RFC 9110 no se recuperó del corpus RAG para esta página; este mapeo se afirma a partir de los códigos de estado declarados en el código y de la conocida especificación de semántica HTTP, marcado aquí como declarado en el código en lugar de verificado por RAG.

Contrato de comportamiento

El consumo se mide en unidades de cómputo; cada inquilino se ejecuta bajo un plan con una cuota de CU incluida y un conjunto de capacidades.
La política de exceso es una de bloqueo estricto (402, bloqueante), bloqueo suave (429 con orientación de reintento, bloqueante) o alerta de presupuesto (200, no bloqueante); se plantea una condición de cuota superada únicamente cuando la política bloquea y la cuota incluida se supera realmente.
Las alertas se evalúan en orden ascendente (advertencia del 80 %, advertencia del 100 %, presupuesto superado) y cada tipo se dispara como máximo una vez por período de facturación por inquilino; el presupuesto superado requiere un exceso estricto.
Una cuota incluida no positiva informa de una proporción de uso de 0.0 en lugar de dividir por cero.
Las comprobaciones de cuota, el cálculo de excesos y la evaluación de alertas son operaciones en memoria de tiempo constante sin E/S en la ruta de comprobación a menos que el repositorio de estado de alertas la realice.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API admitida. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera del alcance.

Alternativa de Core

NextPDF Core (Apache-2.0) no tiene superficie de facturación, cuota ni exceso — ninguna; esta capacidad no tiene equivalente en el nivel Core. El procesamiento de Core no está medido, ni acotado por cuota, ni alertado por NextPDF.

Alternativa de Pro

NextPDF Pro no tiene superficie de facturación, cuota ni exceso — ninguna; esta capacidad no tiene equivalente en el nivel Pro. El registro de planes, el gestor de cuotas, el calculador de excesos y el servicio de alertas se distribuyen únicamente en el paquete nextpdf/enterprise.

Nota sobre el límite de Enterprise

El registro de planes, la política de exceso y la deduplicación de alertas se describen a nivel de comportamiento. El repositorio de estado de alertas es una interfaz; la persistencia duradera la suministra el host, y la estrategia interna de almacenamiento del estado de alertas queda fuera del alcance de la superficie pública.

Límite de despliegue

Las decisiones de facturación se derivan de una cifra de uso actual acotada por inquilino y suministrada por el llamante. El operador es responsable de la implementación del repositorio de estado de alertas, de su persistencia y del calendario de cambio del período de facturación. NextPDF Enterprise aplica la cuota y emite alertas, pero no autentica por sí mismo al inquilino ni persiste el uso.

Límite de cumplimiento legal

No se aplica ninguna restricción de control de exportación a la superficie de facturación. Las inclusiones de plan, las cuotas y los términos comerciales se rigen por su acuerdo de licencia, no por la aplicación en tiempo de ejecución. Esta documentación no es una opinión legal ni contractual; consulte a sus propios asesores y su acuerdo para el alcance del plan.