Enterprise edição

Cobrança

Visão geral

O NextPDF Enterprise rastreia o uso de compute unit (CU) por tenant em relação a uma cota de plano e aplica uma política de excedente configurável: bloquear rigidamente, bloquear com orientação de nova tentativa ou continuar e alertar. Ele também dispara alertas de uso deduplicados nos limiares de 80%, 100% e orçamento excedido. Esta página descreve o comportamento de cobrança observável e o contrato público.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem esse direito não carrega as classes do recurso. Compare edições e obtenha uma licença.

A cobrança é um recurso base do Enterprise, sem sinalizador separado por recurso; os níveis de plano e suas cotas incluídas são resolvidos por meio do registro de planos.

Visão conceitual

A cobrança mede o consumo em compute units. Cada tenant é executado sob um plano; cada plano carrega uma cota de CU incluída e um conjunto de recursos. Três níveis de plano padrão são entregues — Standard, Advanced e High Control — com cotas incluídas progressivamente maiores e conjuntos de recursos progressivamente mais amplos (os níveis mais altos adicionam os pacotes complementares Intelligence e Privacy). O registro é a consulta canônica; uma implantação white-label pode construí-lo com definições personalizadas.

A política de excedente decide o que acontece quando um tenant ultrapassa sua cota incluída. Uma política de hard-stop bloqueia o processamento imediatamente e carrega a semântica HTTP 402. Uma política de soft-stop bloqueia com orientação de nova tentativa e carrega HTTP 429. Uma política de budget-alert nunca bloqueia — o processamento continua e, em vez disso, alertas são disparados, carregando HTTP 200. Apenas hard-stop e soft-stop são bloqueantes; o gerenciador de cotas levanta uma condição de cota excedida somente quando a política bloqueia e a cota incluída é de fato excedida.

O serviço de alertas avalia o uso em relação aos limiares em ordem crescente — aviso de 80%, aviso de 100% e, então, orçamento excedido — e cada tipo de alerta é disparado no máximo uma vez por período de cobrança por tenant. Orçamento excedido exige excedente estrito, não apenas atingir 100%. O estado dos alertas é rastreado por meio de uma interface de repositório, então a deduplicação sobrevive entre requisições, e o serviço expõe uma operação clara para redefinir o estado dos alertas na virada do período de cobrança.

Por que funciona assim

A cobrança é construída como uma camada de decisão pura, não como um sistema de armazenamento. Verificações de cota, matemática de excedente e avaliação de alertas rodam em memória contra uma PlanDefinition e uma única figura de uso atual, sem I/O no caminho de verificação. A persistência fica fora dessa decisão: o estado de deduplicação de alertas é alcançado apenas por meio da AlertStateRepositoryInterface que um operador fornece, o que mantém a durabilidade e a fronteira do período de cobrança sob controle do host. O resultado do excedente é um pequeno enum explícito que mapeia cada política para um status HTTP fixo, de modo que a decisão de bloquear ou continuar permanece determinística e auditável. Essa separação permite que a mesma superfície de cobrança rode sem alterações desde uma única instância até uma frota multi-tenant medida. Contexto de design: Operando o NextPDF em produção.

Superfície pública da API

composer require nextpdf/enterprise:^3

Os pontos de integração suportados são o registro de planos (get, has, defaultRegistry), o gerenciador de cotas (checkQuota, remainingQuota, usagePercentage), a calculadora de excedente (calculate, retornando um resultado de excedente imutável), o enum de política de excedente (httpStatusCode, isBlocking) e o serviço de alertas de cobrança (evaluate, clearAlerts). O repositório de estado de alertas é uma interface — forneça uma implementação em memória para testes ou uma durável para produção.

Exemplo de código — início 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

Exemplo de código — produção

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 extremos e armadilhas

Budget-alert nunca bloqueia. Sob uma política de budget-alert, checkQuota não levanta exceção mesmo bem além da cota; conte com os alertas disparados, não com uma exceção.
Orçamento excedido exige excedente estrito. Atingir exatamente 100% dispara o aviso de 100%, não o de orçamento excedido; orçamento excedido exige uso estritamente acima da cota incluída.
Os alertas deduplicam por período. Cada tipo de alerta é disparado uma vez por tenant por período de cobrança. Limpe o estado dos alertas na virada do período, ou os alertas não voltam a disparar no período seguinte.
Cota incluída zero ou não definida. Um plano com uma cota incluída não positiva relata uma razão de uso de 0.0 em vez de dividir por zero.
A redefinição do período é a fronteira do próximo mês. O instante padrão de redefinição da cota excedida é o primeiro dia do próximo mês do calendário à meia-noite.

Desempenho

Verificações de cota, cálculo de excedente e avaliação de alertas são operações de tempo constante, em memória, em relação a uma definição de plano e à figura de uso atual fornecida. Não há I/O no caminho de verificação, a menos que a implementação do seu repositório de estado de alertas o realize.

Notas de segurança

As decisões de cobrança são derivadas de uma figura de uso atual delimitada por tenant e fornecida pelo chamador; a identidade do tenant deve vir de um contexto autenticado, nunca de entrada fornecida pelo cliente. A superfície de cobrança impõe a cota e emite alertas — ela própria não autentica o tenant.

Conformidade

Os resultados da política de excedente carregam a semântica padrão de status HTTP: pagamento exigido (402) para hard-stop, requisições demais (429) com orientação de nova tentativa para soft-stop e sucesso (200) para budget-alert, seguindo a especificação de semântica HTTP da IETF (RFC 9110) para as classes 402, 429 e 2xx. A RFC 9110 não foi recuperada do corpus de RAG para esta página; este mapeamento é afirmado a partir dos códigos de status declarados no código e da conhecida especificação de semântica HTTP, marcado aqui como declarado no código e não verificado por RAG.

Contrato de comportamento

O consumo é medido em compute units; cada tenant é executado sob um plano com uma cota de CU incluída e um conjunto de recursos.
A política de excedente é uma de hard-stop (402, bloqueante), soft-stop (429 com orientação de nova tentativa, bloqueante) ou budget-alert (200, não bloqueante); uma condição de cota excedida é levantada somente quando a política bloqueia e a cota incluída é de fato excedida.
Os alertas avaliam em ordem crescente (aviso de 80%, aviso de 100%, orçamento excedido) e cada tipo é disparado no máximo uma vez por período de cobrança por tenant; orçamento excedido exige excedente estrito.
Uma cota incluída não positiva relata uma razão de uso de 0.0 em vez de dividir por zero.
Verificações de cota, cálculo de excedente e avaliação de alertas são operações de tempo constante em memória, sem I/O no caminho de verificação, a menos que o repositório de estado de alertas o realize.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivo de runbook e prefixos de tíquete estão fora do escopo.

Fallback do Core

O NextPDF Core (Apache-2.0) não tem nenhuma superfície de cobrança, cota ou excedente — nenhuma; este recurso não tem equivalente no nível Core. O processamento do Core não é medido, restringido por cota nem alertado pelo NextPDF.

Fallback do Pro

O NextPDF Pro não tem nenhuma superfície de cobrança, cota ou excedente — nenhuma; este recurso não tem equivalente no nível Pro. O registro de planos, o gerenciador de cotas, a calculadora de excedente e o serviço de alertas são entregues apenas no pacote nextpdf/enterprise.

Nota sobre o limite do Enterprise

O registro de planos, a política de excedente e a deduplicação de alertas são descritos no nível de comportamento. O repositório de estado de alertas é uma interface; a persistência durável é fornecida pelo host, e a estratégia interna de armazenamento do estado de alertas está fora do escopo da superfície pública.

Limite de implantação

As decisões de cobrança são derivadas de uma figura de uso atual delimitada por tenant e fornecida pelo chamador. O operador é responsável pela implementação do repositório de estado de alertas, por sua persistência e pelo cronograma de virada do período de cobrança. O NextPDF Enterprise impõe a cota e emite alertas, mas ele próprio não autentica o tenant nem persiste o uso.

Limite de conformidade legal

Nenhuma restrição de controle de exportação se aplica à superfície de cobrança. As inclusões de plano, as cotas e os termos comerciais são regidos pelo seu contrato de licença, não pela imposição em tempo de execução. Esta documentação não é um parecer jurídico ou contratual; consulte sua própria assessoria e o seu contrato para o escopo do plano.