@seedgrid/ai-toolkit 0.0.0-stage → 0.3.1

package/seedgridKB/SeedGrid/Extensions/billing/Configuracao.md

@@ -0,0 +1,243 @@
+---
+tags: [seedgrid, extension, billing, quarkus, configuracao]
+fonte: java/seedgrid-quarkus-ext-billing
+branch: main
+commit: ba38efc347
+analisado-em: 2026-10-14
+---
+
+# Billing (Quarkus): configuração
+
+Voltar para [[SeedGrid/Extensions/billing/Visao-geral|Visão geral do billing]] · [[SeedGrid/Extensions/billing/Exemplos|Exemplos]]
+
+## 1. Cabeçalho
+
+| Item | Valor |
+|---|---|
+| Prefixos | `seedgrid.billing.*` no core e `seedgrid.billing.stripe.*` no provider Stripe |
+| Classes `@ConfigMapping` (core) | `BillingAccessGateConfig` (`seedgrid.billing.access-gate`), `BillingApiConfig` (`seedgrid.billing.api`), `BillingCatalogConfig` (`.catalog`), `BillingCheckoutConfig` (`.checkout`), `BillingPortalConfig` (`.portal`), `BillingTrialConfig` (`.trial`), `BillingFeatureGateConfig` (`.feature-gate`), `PlanTermAttributesConfig` (`.plan-term.additional-attributes`), `BillingReconciliationConfig` (`.reconciliation`) |
+| `@ConfigProperty` (core) | `BillingConfig` (business-timezone, currency, overage-meter-name), `BillingEntityManager` (persistence-unit), `PlanPublicationService` (stripe.product, como fallback) |
+| `ConfigProvider` direto | `BillingApiOpenApiFilter` (`seedgrid.billing.api.enabled`) |
+| `@ConfigProperty` (stripe) | `StripeBillingProvider` (apiKey, webhookSecret, defaultSuccessUrl, defaultCancelUrl, test-clock-enabled) e `StripeProductBootstrap` (product, product-name) |
+| Defaults em arquivo | `seedgrid-billing-core/runtime/src/main/resources/META-INF/microprofile-config.properties` (ordinal 100) |
+| Fase | **Todas são de runtime.** Não há `@ConfigRoot` nem `*BuildTimeConfig` nos deployments. Os processors só registram feature, beans e `ConsumesUsageSites`. |
+
+Abreviações usadas na coluna Origem:
+- `core/` = `java/seedgrid-quarkus-ext-billing/seedgrid-billing-core/runtime/src/main/java/br/com/seedgrid/billing/`
+- `stripe/` = `java/seedgrid-quarkus-ext-billing/seedgrid-billing-stripe/runtime/src/main/java/br/com/seedgrid/billing/stripe/`
+- `core-mp` = `seedgrid-billing-core/runtime/src/main/resources/META-INF/microprofile-config.properties`
+
+**Por que cada grupo tem um prefixo próprio:** o SmallRye recusa chave desconhecida sob o prefixo de um mapping. Se houvesse um mapping único em `seedgrid.billing`, as chaves `seedgrid.billing.stripe.*` derrubariam o boot. **Confirmado** (javadoc de `BillingConfig`).
+
+**Variáveis de ambiente:** a regra MicroProfile se aplica sem ambiguidade a todas as propriedades abaixo, porque a busca vai da propriedade para a env. Exemplos: `seedgrid.billing.access-gate.enabled` vira `SEEDGRID_BILLING_ACCESS_GATE_ENABLED`, e `seedgrid.billing.stripe.apiKey` vira `SEEDGRID_BILLING_STRIPE_APIKEY`. Além disso, o `core-mp` expande **nomes explícitos** em algumas chaves, indicados na coluna Relações. Três deles **diferem** da regra MP.
+
+## 2. Propriedades próprias
+
+### 2.1 Geral / negócio
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.billing.business-timezone` | String (ZoneId) | qualquer `ZoneId` válido | `America/Sao_Paulo` | Não | Define o fuso em que o negócio conta os dias: vigência de preço, virada do ciclo e data nos e-mails de acesso. Valor vazio ou inválido gera um WARN e usa `America/Sao_Paulo`, sem derrubar o boot. | `BusinessTimeZone` → services de ciclo, `UserAccessEmails` | `core-mp` expande `${SEEDGRID_BILLING_BUSINESS_TIMEZONE:America/Sao_Paulo}`. É independente de `seedgrid.app.business-timezone` (commons). | runtime | declaração: `core/configs/BillingConfig.java` (construtor); consumo: `core/configs/BusinessTimeZone#resolve` |
+| `seedgrid.billing.currency` | String | código ISO 4217 em minúsculas (ex.: `brl`, `usd`), como o Stripe espera | `brl` | Não | Moeda dos preços publicados no provider (fixo e metered) e do overview. | `PlanPublicationService#publish`, `BillingOverviewService` | `core-mp`: `${SEEDGRID_BILLING_CURRENCY:brl}` | runtime | `core/configs/BillingConfig.java`; consumo `core/services/PlanPublicationService#publish` |
+| `seedgrid.billing.overage-meter-name` | String | texto livre | `Excedente` | Não | Prefixo do nome **exibido** do meter de excedente no provider: `"<valor> - <label do contador>"`. O identificador técnico é o event name `overage_<produto>_<contador>`. | `PlanPublicationService#publish` | — | runtime | `core/configs/BillingConfig.java`; consumo `core/services/PlanPublicationService#publish` |
+| `seedgrid.billing.persistence-unit` | Optional\<String\> | nome de PU; vazio ou `<default>` = PU default | — (sem valor = PU default) | Não | Escolhe o `EntityManager` das tabelas do billing. | `BillingEntityManager` (repositories do billing) | O `subdomain-tenancy` define `master` no microprofile-config dele (**Confirmado**). Usuários e security continuam no EntityManager da security. | runtime | `core/repositories/BillingEntityManager.java` (construtor) |
+
+### 2.2 API e bloqueio geral
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.billing.api.enabled` | boolean | `true`/`false` | `true` | Não | Com `false`, os prefixos `/admin/plans`, `/admin/subscriptions`, `/admin/accounts`, `/admin/billing`, `/me/plans`, `/me/subscription`, `/me/usage` e `/me/billing` respondem 404 (pre-matching, antes da autenticação) e somem do OpenAPI. O webhook continua. | `BillingApiToggleFilter#filter` (lido por requisição) e `BillingApiOpenApiFilter` (no startup) | O login-tenancy liga este valor a `seedgrid.login-tenancy.modules.billing.enabled` (BILLING_INTEGRATION_GUIDE). O default fica no `@WithDefault` de propósito, para um tenancy poder definir o próprio default sem empatar em ordinal. | runtime | `core/configs/BillingApiConfig#enabled`; consumo `core/filters/BillingApiToggleFilter`, `core/filters/BillingApiOpenApiFilter#filterOpenAPI` |
+| `seedgrid.billing.access-gate.enabled` | boolean | `true`/`false` | `false` | Não | Liga o bloqueio **geral**: conta sem assinatura vigente recebe 402 em qualquer endpoint autenticado. Ficam liberados `OPTIONS`, anônimos, `/public`, `/q/`, `/me/plans`, `/me/subscription`, `/me/usage`, `/me/billing`, `allowed-paths`, `@PlatformScope` e usuário sem conta. | `AccessGateFilter#filter` (por requisição) | O bloqueio por funcionalidade (`@ConsumesUsage`/`@RequiresPlanFeature`) independe deste. | runtime | `core/configs/BillingAccessGateConfig#enabled`; consumo `core/filters/AccessGateFilter#filter` |
+| `seedgrid.billing.access-gate.block-past-due` | boolean | `true`/`false` | `true` | Não | Assinatura `PAST_DUE` também nega acesso no bloqueio geral (402 `PAYMENT_PAST_DUE`). | `SubscriptionAccessService#denialForAccess`, chamado só por `AccessGateFilter` | **Confirmado:** só tem efeito com `access-gate.enabled=true`. O **consumo** (`denialForConsumption`/`denialForAnyConsumption`) sempre bloqueia `PAST_DUE`, independentemente desta flag. | runtime | `core/configs/BillingAccessGateConfig#blockPastDue`; consumo `core/services/SubscriptionAccessService#denialForAccess` |
+| `seedgrid.billing.access-gate.allowed-paths` | Optional\<List\<String\>\> | prefixos separados por vírgula; casa por fronteira de segmento (`/me/plans` não casa `/me/plansx`); prefixo terminado em `/` casa qualquer coisa abaixo | — | Não | Prefixos extras sempre liberados pelo bloqueio geral. | `AccessGateFilter#allowedPaths`, `BillingPaths#startsWithAny` | Somados a `RestControllerPath.ACCESS_GATE_ALWAYS_ALLOWED`. | runtime | `core/configs/BillingAccessGateConfig#allowedPaths` |
+
+### 2.3 Catálogo, checkout e portal
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.billing.catalog.product-id` | Optional\<String\> | ID do produto no provider | — (cai em `seedgrid.billing.stripe.product`) | Condicional: um dos dois é necessário para publicar term, criar meter e reportar excedente | Define o produto sob o qual os preços dos planos e os meters (`overage_<produto>_<contador>`) são criados. Sem nenhum dos dois, a publicação lança `ProviderProductNotConfiguredException`, e o consumo com excedente não reporta ao provider (retorno silencioso). | `PlanPublicationService#productId`, `UsageService#reportOverageAfterCommit` | Fallback: `seedgrid.billing.stripe.product`. | runtime | `core/configs/BillingCatalogConfig#productId`; consumo `core/services/PlanPublicationService#productId` |
+| `seedgrid.billing.checkout.success-url` | Optional\<String\> | URL absoluta | — | Condicional: o Stripe exige URL de sucesso; sem ela, vale `seedgrid.billing.stripe.defaultSuccessUrl` | URL para onde o provider devolve o cliente após o checkout. | `CheckoutService` → `CheckoutRequest.successUrl` | O Stripe usa `defaultSuccessUrl` quando esta é nula. Se ambas faltarem, envia `""` (**Inferência:** o Stripe recusaria a sessão). | runtime | `core/configs/BillingCheckoutConfig#successUrl`; consumo `core/services/CheckoutService` (l.120) |
+| `seedgrid.billing.checkout.cancel-url` | Optional\<String\> | URL absoluta | — | Condicional (idem) | URL de retorno quando o cliente cancela o checkout. | `CheckoutService` | Fallback: `seedgrid.billing.stripe.defaultCancelUrl`. | runtime | `core/configs/BillingCheckoutConfig#cancelUrl`; consumo `core/services/CheckoutService` (l.121) |
+| `seedgrid.billing.portal.return-url` | Optional\<String\> | URL absoluta | — | Não | URL de retorno do customer portal. Sem valor, não chama `setReturnUrl` (o Stripe usa o default da conta). | `SubscriptionChangeService#portal` → `StripeBillingProvider#createPortal` | — | runtime | `core/configs/BillingPortalConfig#returnUrl`; consumo `core/services/SubscriptionChangeService` (l.86) |
+
+### 2.4 Trial e feature gate
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.billing.trial.enabled` | boolean | `true`/`false` | `true` | Não | Conta nova sem nenhuma assinatura ganha uma assinatura `ACTIVE` no term do trial. | `TrialService#provisionTrial` | `core-mp`: `${SEEDGRID_BILLING_TRIAL_ENABLED:true}` | runtime | `core/configs/BillingTrialConfig#enabled`; consumo `core/services/TrialService#provisionTrial` |
+| `seedgrid.billing.trial.plan-term-public-id` | String | `publicId` de um term do plano TRIAL | `00000000-0000-0000-0000-0000000000a2` (semeado pela V505) | Não | Define o term usado no trial. Se não existir, `provisionTrial` só registra um WARN, enquanto `/admin/plans/trial` lança `TrialPlanNotFoundException`. Um term de outro plano também é recusado. | `TrialService#requireTrialTerm`, `#provisionTrial` | `core-mp`: `${SEEDGRID_BILLING_TRIAL_PLAN_TERM_PUBLIC_ID:...}` | runtime | `core/configs/BillingTrialConfig#planTermPublicId` |
+| `seedgrid.billing.feature-gate.exempt-company-ids` | Optional\<List\<Long\>\> | IDs internos de `Company`, separados por vírgula | — | Não | Companies nunca bloqueadas por `@RequiresPlanFeature`, por exemplo a empresa da plataforma. | `PlanFeatureGate#isExempt` | — | runtime | `core/configs/BillingFeatureGateConfig#exemptCompanyIds`; consumo `core/services/PlanFeatureGate` |
+
+### 2.5 Limites dos `additionalAttributes` e reconciliação
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `seedgrid.billing.plan-term.additional-attributes.max-size-bytes` | int | inteiro positivo | `16384` | Não | Tamanho máximo, em bytes UTF-8, do JSON final. Se exceder, responde HTTP 400. | `PlanTermAttributesService` | `core-mp` expande `${SEEDGRID_BILLING_PLAN_TERM_ATTRIBUTES_MAX_SIZE_BYTES:16384}`. **O nome explícito difere** da regra MP (`SEEDGRID_BILLING_PLAN_TERM_ADDITIONAL_ATTRIBUTES_MAX_SIZE_BYTES`). Ambos funcionam (Inferência pela precedência de ordinais). | runtime | `core/configs/PlanTermAttributesConfig#maxSizeBytes`; consumo `core/services/PlanTermAttributesService` (l.50) |
+| `seedgrid.billing.plan-term.additional-attributes.max-depth` | int | inteiro positivo (objeto raiz = 1) | `5` | Não | Profundidade máxima de aninhamento. | idem | `core-mp`: `SEEDGRID_BILLING_PLAN_TERM_ATTRIBUTES_MAX_DEPTH` (difere da regra MP) | runtime | `core/configs/PlanTermAttributesConfig#maxDepth` |
+| `seedgrid.billing.plan-term.additional-attributes.max-keys` | int | inteiro positivo | `100` | Não | Total de chaves em todos os objetos, inclusive aninhados e dentro de arrays. | idem | `core-mp`: `SEEDGRID_BILLING_PLAN_TERM_ATTRIBUTES_MAX_KEYS` (difere da regra MP) | runtime | `core/configs/PlanTermAttributesConfig#maxKeys` |
+| `seedgrid.billing.reconciliation.throttle-seconds` | long | `>= 0`; `0` = sem throttle | `60` | Não | Intervalo mínimo entre reconciliações **implícitas** da mesma conta com o provider (anti-stampede, guardado em memória). | `SubscriptionReconciliationService#reconcileThrottled` | `core-mp`: `${SEEDGRID_BILLING_RECONCILIATION_THROTTLE_SECONDS:60}` | runtime | `core/configs/BillingReconciliationConfig#throttleSeconds`; consumo `core/services/SubscriptionReconciliationService` (construtor) |
+
+### 2.6 Provider Stripe (`seedgrid-billing-stripe`)
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| 🔒 `seedgrid.billing.stripe.apiKey` | String | secret key do Stripe (`sk_test_…`/`sk_live_…`); **não** use a publishable `pk_…` | — | **Sim**, com o módulo stripe presente (**Inferência forte**: `@ConfigProperty` String sem default; o teste de deployment define valor dummy) | Atribuída a `Stripe.apiKey` global no `@PostConstruct`. O prefixo `sk_test` ativa o Test Clock e a busca de customers em clocks. | `StripeBillingProvider#init`, `#maybeCreateTestClockCustomer` | env: `SEEDGRID_BILLING_STRIPE_APIKEY`. O guia de integração sugere `${STRIPE_API_KEY}` no host. | runtime | `stripe/spis/impl/StripeBillingProvider.java` (construtor) |
+| 🔒 `seedgrid.billing.stripe.webhookSecret` | String | signing secret do endpoint (`whsec_…`) | — | **Sim**, com o módulo stripe (mesma inferência) | Valida o header `Stripe-Signature` em `Webhook.constructEvent`. Se falhar, responde 400. | `StripeBillingProvider#parseAndVerifyWebhook` | env: `SEEDGRID_BILLING_STRIPE_WEBHOOKSECRET`. Em dev, vem do `stripe listen`. | runtime | idem (l.251) |
+| `seedgrid.billing.stripe.defaultSuccessUrl` | Optional\<String\> | URL absoluta | — | Condicional (ver `checkout.success-url`) | Fallback quando o core não envia a URL de sucesso. Sem nenhuma das duas, envia `""`. | `StripeBillingProvider#createCheckout` | Preferir `seedgrid.billing.checkout.success-url`. | runtime | idem (l.126) |
+| `seedgrid.billing.stripe.defaultCancelUrl` | Optional\<String\> | URL absoluta | — | Condicional | Fallback da URL de cancelamento. | `StripeBillingProvider#createCheckout` | Preferir `seedgrid.billing.checkout.cancel-url`. | runtime | idem (l.127) |
+| `seedgrid.billing.stripe.test-clock-enabled` | boolean | `true`/`false` | `true` | Não | Com chave `sk_test`, a nova assinatura nasce num customer preso a um Stripe Test Clock, para testes E2E. Com chave live, é ignorada. | `StripeBillingProvider#maybeCreateTestClockCustomer` | Só tem efeito com `apiKey` iniciada por `sk_test`. | runtime | idem (construtor, l.101) |
+| `seedgrid.billing.stripe.product` | Optional\<String\> | ID do produto Stripe (fixo, escolhido pelo host) | — | Condicional (ver `catalog.product-id`) | No startup, `StripeProductBootstrap` faz retrieve-or-create do produto. É best-effort: falha gera WARN. Também serve de fallback do `catalog.product-id`. | `StripeProductBootstrap#onStart`, `PlanPublicationService#productId` | Lida também pelo **core**. | runtime | `stripe/services/StripeProductBootstrap.java`; `core/services/PlanPublicationService.java` (construtor) |
+| `seedgrid.billing.stripe.product-name` | Optional\<String\> | texto | — (usa o próprio ID) | Não | Nome do produto criado no bootstrap. | `StripeProductBootstrap#onStart` | Só tem efeito com `seedgrid.billing.stripe.product`. | runtime | `stripe/services/StripeProductBootstrap.java` |
+
+### 2.7 Propriedades de outras extensions lidas ou exigidas pelo billing
+
+| Propriedade | Dona | Uso no billing | Origem |
+|---|---|---|---|
+| `seedgrid.show-dev-message` (default `false`) | commons/security (mesma chave em `ApiExceptionHandler` do commons) | `BillingApiExceptionExtension` inclui a mensagem de desenvolvedor no problem+json | `core/exceptions/BillingApiExceptionExtension.java` (construtor) |
+| `seedgrid.ratelimit.billing-webhook.{enabled,permits,window}` | resilience (`RateLimitService`) | ajusta o rate limit do webhook (default 300/min) | `core/controllers/BillingWebhookController` (`@SeedGridRateLimit(configKey="billing-webhook")`) |
+| `seedgrid.ratelimit.billing-checkout.{enabled,permits,window}` | resilience | checkout (default 30/min) | `core/controllers/MeBillingController` |
+| `seedgrid.ratelimit.billing-portal.{enabled,permits,window}` | resilience | portal (default 30/min) | `core/controllers/MeBillingController` |
+| `seedgrid.security.encryption.key` 🔒, `seedgrid.security.default-company.*`, `seedgrid.security.jwt.*` | security | obrigatórias da security, que o billing passou a exigir transitivamente em 2026-09-10 | comentário em `seedgrid-billing-core/deployment/src/test/resources/application.properties` |
+
+Ver [[SeedGrid/Extensions/resilience/Configuracao|Configuração do resilience]] e [[SeedGrid/Extensions/security/Configuracao|Configuração do security]].
+
+## 3. Propriedades de frameworks (definidas no `core-mp`, ordinal 100)
+
+| Propriedade | Valor no `core-mp` | Efeito / recomendação |
+|---|---|---|
+| `quarkus.flyway.locations` | `db/migration/billing` | Só as migrations do billing. Um host com Flyway nativo **precisa** sobrescrever com `db/migration/security,db/migration/billing` (mais as próprias), senão o boot falha com `relation "companies" does not exist`. |
+| `quarkus.flyway.table` | `flyway_schema_history_billing` | Os testes de deployment sobrescrevem para `flyway_schema_history`. |
+| `quarkus.flyway.migrate-at-start` | `true` | — |
+| `quarkus.flyway.baseline-on-migrate` | `true` | — |
+| `quarkus.flyway.baseline-version` | `0` | — |
+| `quarkus.hibernate-orm.database.generation` | `none` | — |
+| `quarkus.hibernate-orm.physical-naming-strategy` | (não definido) | **Recomendado** pelos testes: `org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy`. As entidades da security exigem esse valor. O login-tenancy já o fixa. |
+| `quarkus.flyway.out-of-order` | (não definido) | Só para upgrade de bancos criados com versões ≤ 2026.07.02 (V501 destravada). Ver README do core. |
+
+> Login-tenancy e subdomain-tenancy desligam o Flyway nativo e rodam as migrations por módulo (`LoginTenancyMigrationService`, `MigrationService`). Nesses hosts, os `quarkus.flyway.*` acima não governam a ordem.
+
+## 4. Propriedades usadas só em testes
+
+| Arquivo | Propriedades relevantes |
+|---|---|
+| `seedgrid-billing-core/deployment/src/test/resources/application.properties` | `quarkus.flyway.locations=db/migration/security,db/migration/billing`, `quarkus.flyway.table`, naming strategy, `quarkus.hibernate-orm.schema-management.strategy=none`, `seedgrid.security.*` (valores de teste) |
+| `seedgrid-billing-core/integration-tests/src/test/resources/application.properties` | datasource e Flyway (`classpath:db/migration/security,…/audit,…/billing`, `clean-at-start=true`), `seedgrid.audit.*`, `seedgrid.security.*`, `mp.jwt.*`, `smallrye.jwt.*`, `quarkus.mailer.mock`, `seedgrid.ratelimit.{login,auth-refresh,billing-checkout,billing-portal,billing-webhook}.enabled=false`, `quarkus.index-dependency.seedgrid-filemanagement.*`, `quarkus.arc.exclude-types`, e valores de teste para `seedgrid.billing.catalog.product-id`, `checkout.*`, `portal.return-url`, `reconciliation.throttle-seconds=0` e `plan-term.additional-attributes.*` (2048/4/20) |
+| `seedgrid-billing-core/integration-tests/.../TestData.java` | lê `seedgrid.security.default-company.cnpj` via `ConfigProvider` |
+| `seedgrid-billing-stripe/deployment/src/test/resources/application.properties` | `seedgrid.billing.stripe.apiKey`/`webhookSecret` com valores dummy, `seedgrid.security.*`, Flyway |
+| `seedgrid-billing-stripe/integration-tests/src/main/resources/application.properties` | vazio |
+
+## 5. Aliases, obsoletas e renomeações
+
+| Propriedade | Situação |
+|---|---|
+| `seedgrid.billing.stripe.product` usada pelo core | Alias de fato de `seedgrid.billing.catalog.product-id`. `PlanPublicationService` a chama de `legacyStripeProductId`. Precedência: `catalog.product-id` primeiro, depois `stripe.product`. |
+| `seedgrid.billing.stripe.defaultSuccessUrl`/`defaultCancelUrl` | Fallback legado de `seedgrid.billing.checkout.success-url`/`cancel-url`. O README do Stripe recomenda as do core. |
+| Nomes camelCase (`apiKey`, `webhookSecret`, `defaultSuccessUrl`) | Fogem do padrão kebab-case do restante. São os nomes reais, sem alias kebab. |
+
+## 6. Configuração mínima (`application.properties`)
+
+```properties
+# Provider Stripe (segredos SOMENTE via ambiente)
+seedgrid.billing.stripe.apiKey=${STRIPE_API_KEY}            # <SEGREDO:stripe-api-key>
+seedgrid.billing.stripe.webhookSecret=${STRIPE_WEBHOOK_SECRET}  # <SEGREDO:stripe-webhook-secret>
+
+# Produto base no provider (necessário para publicar terms)
+seedgrid.billing.stripe.product=<id-do-produto>
+
+# Retorno do checkout (o Stripe exige as duas)
+seedgrid.billing.checkout.success-url=https://<seu-app>/assinatura?ok=1
+seedgrid.billing.checkout.cancel-url=https://<seu-app>/assinatura
+
+# Host com Flyway nativo (sem login/subdomain-tenancy): security antes do billing
+quarkus.flyway.locations=db/migration/security,db/migration/billing
+quarkus.hibernate-orm.physical-naming-strategy=org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy
+```
+
+Mais as obrigatórias da security: [[SeedGrid/Extensions/security/Configuracao|Configuração do security]].
+
+## 7. Configuração completa comentada
+
+```properties
+# ---------- Negócio ----------
+# Fuso do dia civil (vigência de preço, virada de ciclo). Default America/Sao_Paulo.
+seedgrid.billing.business-timezone=America/Sao_Paulo
+# Moeda ISO 4217 em minúsculas. Default brl.
+seedgrid.billing.currency=brl
+# Prefixo do nome exibido do meter de excedente. Default Excedente.
+seedgrid.billing.overage-meter-name=Excedente
+# PU das tabelas do billing. Sem valor = PU default. subdomain-tenancy usa master.
+#seedgrid.billing.persistence-unit=master
+
+# ---------- API REST ----------
+# false = endpoints de plano/assinatura/me respondem 404 e somem do OpenAPI (webhook continua). Default true.
+seedgrid.billing.api.enabled=true
+
+# ---------- Bloqueio geral (opcional) ----------
+# Default false. true = conta sem assinatura vigente só alcança o caminho para pagar.
+seedgrid.billing.access-gate.enabled=false
+# Default true. PAST_DUE entra no bloqueio geral.
+seedgrid.billing.access-gate.block-past-due=true
+# Prefixos extras liberados (sem default).
+#seedgrid.billing.access-gate.allowed-paths=/me/permissions,/me/profile
+
+# ---------- Catálogo / checkout / portal ----------
+# Produto do provider; sem valor usa seedgrid.billing.stripe.product.
+#seedgrid.billing.catalog.product-id=<id-do-produto>
+seedgrid.billing.checkout.success-url=https://<seu-app>/assinatura?ok=1
+seedgrid.billing.checkout.cancel-url=https://<seu-app>/assinatura
+seedgrid.billing.portal.return-url=https://<seu-app>/assinatura
+
+# ---------- Trial ----------
+# Default true.
+seedgrid.billing.trial.enabled=true
+# Default 00000000-0000-0000-0000-0000000000a2 (seed V505).
+#seedgrid.billing.trial.plan-term-public-id=<public-id-do-term-trial>
+
+# ---------- Feature gate ----------
+# IDs de Company nunca bloqueados por @RequiresPlanFeature (sem default).
+#seedgrid.billing.feature-gate.exempt-company-ids=<id-company-plataforma>
+
+# ---------- Limites de additionalAttributes (HTTP 400 ao exceder) ----------
+# Defaults 16384 / 5 / 100.
+seedgrid.billing.plan-term.additional-attributes.max-size-bytes=16384
+seedgrid.billing.plan-term.additional-attributes.max-depth=5
+seedgrid.billing.plan-term.additional-attributes.max-keys=100
+
+# ---------- Reconciliação ----------
+# Segundos mínimos entre reconciliações implícitas da mesma conta. Default 60; 0 = sempre.
+seedgrid.billing.reconciliation.throttle-seconds=60
+
+# ---------- Stripe ----------
+seedgrid.billing.stripe.apiKey=${STRIPE_API_KEY}                 # <SEGREDO:stripe-api-key>
+seedgrid.billing.stripe.webhookSecret=${STRIPE_WEBHOOK_SECRET}   # <SEGREDO:stripe-webhook-secret>
+seedgrid.billing.stripe.product=<id-do-produto>
+seedgrid.billing.stripe.product-name=<Nome do Produto>
+# Fallbacks (prefira as do core):
+#seedgrid.billing.stripe.defaultSuccessUrl=https://<seu-app>/sucesso
+#seedgrid.billing.stripe.defaultCancelUrl=https://<seu-app>/cancelado
+# Só tem efeito com chave sk_test. Default true.
+seedgrid.billing.stripe.test-clock-enabled=true
+
+# ---------- Rate limit (extension resilience) ----------
+#seedgrid.ratelimit.billing-webhook.permits=300
+#seedgrid.ratelimit.billing-webhook.window=PT1M
+#seedgrid.ratelimit.billing-checkout.enabled=true
+```
+
+## 8. Receitas
+
+| Caso | Configuração |
+|---|---|
+| Bloquear tudo quando o trial acabar ou não houver pagamento | `seedgrid.billing.access-gate.enabled=true`. Para liberar telas extras, use `seedgrid.billing.access-gate.allowed-paths=/me/profile`. |
+| Bloquear só funcionalidades anotadas (padrão) | Não configure nada. Use `@ConsumesUsage`/`@RequiresPlanFeature`. |
+| Empresa da plataforma nunca bloqueada por plano | `seedgrid.billing.feature-gate.exempt-company-ids=<id>` |
+| Host com billing desligado (sem tabelas) | `seedgrid.billing.api.enabled=false`. No login-tenancy isso segue `seedgrid.login-tenancy.modules.billing.enabled`. |
+| subdomain-tenancy | `seedgrid.billing.persistence-unit=master` (já definido pela extension de tenancy) |
+| Desenvolvimento local com Stripe | `SEEDGRID_BILLING_STRIPE_APIKEY=<SEGREDO:stripe-test-key>`, `stripe listen --forward-to localhost:8080/public/billing/webhook` e `SEEDGRID_BILLING_STRIPE_WEBHOOKSECRET=<SEGREDO:whsec-do-cli>` |
+| Produção | Webhook em `https://<dominio>/public/billing/webhook` com no mínimo `checkout.session.completed` e `invoice.paid`, chave live e test clock irrelevante |
+| Testes de integração sem esperar throttle | `seedgrid.billing.reconciliation.throttle-seconds=0` |
+
+## 9. Dúvidas e lacunas
+- `apiKey`/`webhookSecret` obrigatórias: dedução pela semântica do `@ConfigProperty` sem default, não testada aqui. O `@ApplicationScoped` é lazy, mas o Quarkus valida injection points de config no startup.
+- Sem URL de sucesso ou cancelamento em lugar nenhum, o Stripe recebe `""`. O comportamento exato (erro do Stripe) não foi verificado.
+- Nomes de env explícitos de `plan-term.additional-attributes.*` diferem da regra MP. Ambos devem funcionar, mas isso não foi testado.

package/seedgridKB/SeedGrid/Extensions/billing/Enums.md

@@ -0,0 +1,165 @@
+---
+tags: [seedgrid, extension, billing, quarkus, enum]
+fonte: java/seedgrid-quarkus-ext-billing
+branch: main
+commit: ba38efc347
+analisado-em: 2026-10-14
+---
+
+# Billing (Quarkus): enums
+
+Voltar para [[SeedGrid/Extensions/billing/Visao-geral|Visão geral]] · [[SeedGrid/Extensions/billing/Configuracao|Configuração]]. Porte Rust: [[SeedGrid/Extensions/billing/Rust|Rust]].
+
+Nenhum enum é tipo de propriedade de configuração. Nenhum tem `@JsonValue`/`@JsonProperty`: no JSON aparecem pelo **nome da constante** (Jackson padrão, case-sensitive). Todos os enums persistidos usam `@Enumerated(EnumType.STRING)` e as colunas são `varchar` **sem CHECK constraint** nas migrations, então o banco aceita qualquer texto. O módulo `seedgrid-billing-stripe` não define enums: só converte os do core.
+
+## Índice
+
+Arquivos em `java/seedgrid-quarkus-ext-billing/seedgrid-billing-core/runtime/src/main/java/br/com/seedgrid/billing/`.
+
+| Enum | Arquivo | Usado em | Público? |
+|---|---|---|---|
+| `SubscriptionStatus` | `entities/SubscriptionStatus.java` | `tenant_subscriptions.status`, `AdminSubscriptionRequest.status` | sim |
+| `AccountStatus` | `entities/AccountStatus.java` | `accounts.status` | sim (entidade) |
+| `PurchaseStatus` | `entities/PurchaseStatus.java` | `billing_purchases.status` | sim (entidade) |
+| `AccountHistoryType` | `entities/AccountHistoryType.java` | `billing_account_history.type`; `AccountHistoryResponse.type` (String) | sim |
+| `SubscriptionLifecycleEvent.Type` | `dtos/events/SubscriptionLifecycleEvent.java` | evento CDI e códigos `billing.*` | sim |
+| `UserAccessEvent.Type` | `dtos/events/UserAccessEvent.java` | evento CDI e e-mails de acesso | sim |
+| `BillingEventType` | `dtos/BillingEventType.java` | `BillingEvent.type` (SPIs), `billing_events.type` | sim |
+| `RecurringInterval` | `dtos/RecurringInterval.java` | `CreatePriceRequest`, `CreateMeteredPriceRequest`, `PriceInfo` | sim |
+| `TiersMode` | `dtos/TiersMode.java` | `CreateMeteredPriceRequest.tiersMode` | sim |
+| `AggregationFormula` | `dtos/AggregationFormula.java` | `CreateMeterRequest.aggregation` | sim |
+
+## SubscriptionStatus
+FQN `br.com.seedgrid.billing.entities.SubscriptionStatus`. STRING em `tenant_subscriptions.status varchar(32)` (V509), sem CHECK. Sem campos nem métodos.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `ACTIVE` | Assinatura em vigor. | Vigente = `ACTIVE` ou `PAST_DUE` já iniciada e não terminada (`Subscription#isResolvable`, `SubscriptionRepository`). Default no `@PrePersist`. | Confirmado. Cancelamento agendado (`cancelAtPeriodEnd`) segue `ACTIVE` até o provider avisar. |
+| `PAST_DUE` | Pagamento falhou (dunning no provider). | Continua vigente para a UI e **sempre bloqueia consumo** (`SubscriptionAccessService`). Bloqueia o acesso geral só se `seedgrid.billing.access-gate.block-past-due=true` (ver [[SeedGrid/Extensions/billing/Configuracao|Configuração]]). | Confirmado. |
+| `INACTIVE` | Substituída por outra assinatura (checkout de outro plano, fim do trial). | Deixa de ser vigente. `SubscriptionActivationService#activate` também fixa `endsAt = agora`. | Confirmado. |
+| `CANCELED` | Encerrada. | Definida por `SUBSCRIPTION_CANCELED` e por `syncFromProvider` quando o provider diz `canceled`/`incomplete_expired`; preenche `endsAt` se nulo. | Confirmado. |
+
+Mapeamento de status do provider (`SubscriptionActivationService#mapProviderStatus`): `active`, `trialing` → `ACTIVE`; `past_due`, `unpaid` → `PAST_DUE`; `canceled`, `incomplete_expired` → `CANCELED`; qualquer outro → nada muda.
+
+```mermaid
+stateDiagram-v2
+    [*] --> ACTIVE
+    ACTIVE --> PAST_DUE: PAYMENT_FAILED, DISPUTE_OPENED, provider past_due
+    PAST_DUE --> ACTIVE: PAYMENT_CONFIRMED, recompra do mesmo term, provider active
+    ACTIVE --> INACTIVE: outro term ativado na conta
+    PAST_DUE --> INACTIVE: outro term ativado na conta
+    ACTIVE --> CANCELED: SUBSCRIPTION_CANCELED, provider canceled
+    PAST_DUE --> CANCELED: SUBSCRIPTION_CANCELED, provider canceled
+```
+
+Também pode ser enviado em `POST /admin/subscriptions` (`AdminSubscriptionRequest.status`, qualquer valor do enum; ausente = `ACTIVE`). O filtro `active`/`inactive` da listagem admin é texto livre, não este enum.
+
+## AccountStatus
+FQN `br.com.seedgrid.billing.entities.AccountStatus`. STRING em `accounts.status varchar(64)` (V502), sem CHECK.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `PENDING_EMAIL_VERIFICATION` | Conta criada, e-mail ainda não verificado. | Default quando o status é nulo (`Account#prePersist`). | Confirmado. Nenhum código consulta esse valor. |
+| `ACTIVE` | Conta ativa. | `AccountCreationService` grava `ACTIVE` ao criar a conta. | Confirmado. |
+| `SUSPENDED` | Conta suspensa. | **Existe no enum, mas nenhum código grava ou trata esse valor.** Gravado direto no banco, não tem efeito. | Confirmado por busca no módulo. |
+
+Na prática o status da conta não influencia o acesso: quem decide é a assinatura.
+
+## PurchaseStatus
+FQN `br.com.seedgrid.billing.entities.PurchaseStatus`. STRING em `billing_purchases.status varchar(64)` (V509), sem CHECK.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `PENDING` | Compra registrada, não confirmada. | Default em `Purchase#prePersist`. | Nenhum fluxo grava `PENDING` explicitamente. |
+| `PAID` | Pagamento confirmado. | `SubscriptionBillingEventHandler#handlePayment` grava em `CHECKOUT_COMPLETED`/`PAYMENT_CONFIRMED`. `PurchaseRepository` filtra `PAID`. | Confirmado. |
+| `FAILED` | Compra falhou. | **Existe no enum, mas nenhum código grava ou consulta esse valor.** `PAYMENT_FAILED` só altera a assinatura. | Confirmado. |
+| `REFUNDED` | Reembolsada. | `REFUND_CREATED` marca a compra localizada por `providerReference`. | Confirmado. Como a consulta usa só `PAID`, deixa de contar. |
+
+## AccountHistoryType
+FQN `br.com.seedgrid.billing.entities.AccountHistoryType`. STRING em `billing_account_history.type varchar(40)` (V511), sem CHECK. O método `static of(SubscriptionLifecycleEvent.Type)` faz `valueOf(type.name())`: os 9 primeiros valores **precisam** ter o mesmo nome das constantes de `SubscriptionLifecycleEvent.Type`.
+
+| Valor | Significado | Efeito / onde é tratado | Observações |
+|---|---|---|---|
+| `ACTIVATED` | Assinatura ativada. | Gravado por `AccountHistoryService` ao receber o evento de ciclo de vida. | Espelha o evento. |
+| `UPGRADED` | Upgrade. | Contado no overview (`BillingOverviewService`). | Espelha o evento. |
+| `DOWNGRADE_SCHEDULED` | Downgrade agendado. | Contado no overview como downgrade. | Espelha o evento. |
+| `DOWNGRADE_CANCELED` | Downgrade desfeito. | Só histórico. | Espelha o evento. |
+| `CANCELLATION_REQUESTED` | Cancelamento pedido. | Só histórico. | Espelha o evento. |
+| `CANCELED` | Cancelamento efetivado. | Só histórico. | Espelha o evento. |
+| `REACTIVATED` | Reativada. | Só histórico. | Espelha o evento. |
+| `PAST_DUE` | Pagamento pendente. | Só histórico. | Espelha o evento. |
+| `TRIAL_ENDED` | Trial encerrado. | Só histórico. | Espelha o evento. |
+| `UNITS_GRANTED` | Unidades extras concedidas no ciclo. | `AdminAccountService` (`POST /admin/accounts/{id}/grant-units`). | Só do admin. |
+| `TRIAL_EXTENDED` | Dias a mais no trial. | `AdminAccountService` (`POST .../grant-trial-days`). | Só do admin. |
+
+A resposta REST (`AccountHistoryResponse.type`) é `String`: sai o nome da constante.
+
+## SubscriptionLifecycleEvent.Type
+FQN `br.com.seedgrid.billing.dtos.events.SubscriptionLifecycleEvent.Type`. Não persistido diretamente (vira `AccountHistoryType`).
+
+| Valor | Significado | Disparado por | Código de notificação |
+|---|---|---|---|
+| `ACTIVATED` | Nova assinatura ativada. | `SubscriptionBillingEventHandler#handlePayment` | `billing.subscription-activated` |
+| `UPGRADED` | Plano de preço igual ou maior. | `SubscriptionChangeService` | `billing.subscription-upgraded` |
+| `DOWNGRADE_SCHEDULED` | Downgrade agendado para o fim do ciclo. | `SubscriptionChangeService` | `billing.subscription-downgraded` |
+| `DOWNGRADE_CANCELED` | Downgrade desfeito. | `SubscriptionChangeService` | `billing.downgrade-canceled` |
+| `CANCELLATION_REQUESTED` | Cancelamento no fim do período pedido. | `SubscriptionChangeService` | `billing.cancellation-requested` |
+| `CANCELED` | Assinatura encerrada. | `SubscriptionBillingEventHandler` (`SUBSCRIPTION_CANCELED`) | `billing.subscription-canceled` |
+| `REACTIVATED` | Cancelamento agendado revertido. | `SubscriptionChangeService` | `billing.subscription-reactivated` |
+| `PAST_DUE` | Pagamento falhou. | `SubscriptionBillingEventHandler` (`PAYMENT_FAILED`) | `billing.payment-past-due` |
+| `TRIAL_ENDED` | Trial terminou; `reason` = `TIME` ou `QUOTA`. | `TrialEndedNotifier` (uma vez por assinatura) | `billing.trial-ended` |
+
+Confirmado em `BillingLifecycleNotificationObserver` (switch exaustivo). `DISPUTE_OPENED` coloca a assinatura em `PAST_DUE`, mas **não dispara** este evento.
+
+## UserAccessEvent.Type
+FQN `br.com.seedgrid.billing.dtos.events.UserAccessEvent.Type`. Não persistido.
+
+| Valor | Significado | Disparado por | Efeito |
+|---|---|---|---|
+| `LOSS_SCHEDULED` | Usuário escolhido para perder acesso quando o plano com menos vagas valer. | `SeatService` | `UserAccessEmailObserver` envia `accessLoss` com data. |
+| `LOSS_APPLIED` | Perdeu o acesso agora. | `SeatService` | `accessLoss` imediato. |
+| `RESTORED` | Estava escolhido, mas o downgrade foi desfeito. | `SeatService` | `accessRestored`. |
+
+## BillingEventType
+FQN `br.com.seedgrid.billing.dtos.BillingEventType`. Campo `BillingEvent.type`. Persistido por nome em `billing_events.type varchar(50)` (idempotência do webhook). Evento Stripe não mapeado gera `UnsupportedEventException` e resposta 204.
+
+| Valor | Significado | Efeito no `SubscriptionBillingEventHandler` | Origem no Stripe |
+|---|---|---|---|
+| `CHECKOUT_COMPLETED` | Checkout concluído. | Registra a compra `PAID` e ativa o term do metadata. Sem term, só registra a compra. | `checkout.session.completed` |
+| `PAYMENT_CONFIRMED` | Fatura paga. | Regulariza `PAST_DUE`, efetiva a virada de ciclo, registra a compra e ativa o term se houver metadata. | `invoice.paid` |
+| `PAYMENT_FAILED` | Falha de pagamento. | Marca `PAST_DUE` e dispara `PAST_DUE`. | `invoice.payment_failed` |
+| `SUBSCRIPTION_CREATED` | Assinatura criada no provider. | **Existe no enum e o Stripe o emite, mas o handler não o trata** (cai no `default`, sem efeito). | `customer.subscription.created` |
+| `SUBSCRIPTION_UPDATED` | Assinatura alterada. | Sincroniza status e `cancelAtPeriodEnd` com o provider. | `customer.subscription.updated` |
+| `SUBSCRIPTION_CANCELED` | Assinatura cancelada. | `CANCELED` e dispara `CANCELED`. | `customer.subscription.deleted` |
+| `REFUND_CREATED` | Reembolso. | Compra → `REFUNDED`. | `charge.refunded` |
+| `DISPUTE_OPENED` | Disputa aberta. | Suspende (`PAST_DUE`) as assinaturas do customer. | `charge.dispute.created` |
+
+## RecurringInterval
+FQN `br.com.seedgrid.billing.dtos.RecurringInterval`.
+
+| Valor | Significado | Efeito | Observações |
+|---|---|---|---|
+| `DAY` | Diário. | Stripe `Interval.DAY`; leitura `"day"`. | O core só usa `MONTH`. |
+| `WEEK` | Semanal. | Stripe `WEEK`; leitura `"week"`. | idem |
+| `MONTH` | Mensal. | Stripe `MONTH`. **Default** para `null` e para qualquer string desconhecida na leitura. | `PlanPublicationService` sempre envia `MONTH`. |
+| `YEAR` | Anual. | Stripe `YEAR`; leitura `"year"`. | — |
+
+## TiersMode
+FQN `br.com.seedgrid.billing.dtos.TiersMode`.
+
+| Valor | Significado | Efeito | Observações |
+|---|---|---|---|
+| `GRADUATED` | Cada faixa cobra seu preço pela parcela que cai nela (Javadoc). | Stripe `TiersMode.GRADUATED`; é o resultado para `null`. | O core não usa tiers. |
+| `VOLUME` | Toda a quantidade é cobrada no preço da faixa do total (Javadoc). | Stripe `TiersMode.VOLUME`. | idem |
+
+## AggregationFormula
+FQN `br.com.seedgrid.billing.dtos.AggregationFormula`. Default `SUM` quando `null`.
+
+| Valor | Significado | Efeito | Observações |
+|---|---|---|---|
+| `SUM` | Soma dos valores de uso. | Stripe `Formula.SUM`. Único usado pelo core (`PlanPublicationService`). | Default. |
+| `COUNT` | Contagem de eventos. | Stripe `Formula.COUNT`. | — |
+| `LAST` | Último valor do período. | **O provider Stripe não implementa**: cai em `SUM` (comentário no código: o SDK só expõe SUM e COUNT). | Confirmado em `StripeBillingProvider#toMeterFormula`. |
+
+## Internos
+Nenhum enum interno em `seedgrid-billing-core` nem em `seedgrid-billing-stripe` (fora dos testes).

package/seedgridKB/SeedGrid/Extensions/billing/Exemplos.md

@@ -0,0 +1,205 @@
+---
+tags: [seedgrid, extension, billing, quarkus, exemplos]
+fonte: java/seedgrid-quarkus-ext-billing
+branch: main
+commit: ba38efc347
+analisado-em: 2026-10-14
+---
+
+# Billing (Quarkus): exemplos
+
+Ver também [[SeedGrid/Extensions/billing/Visao-geral|Visão geral]] e [[SeedGrid/Extensions/billing/Configuracao|Configuração]].
+
+Os exemplos usam a API real do código. A fonte de cada um está indicada.
+
+## 1. Dependências
+
+Fonte: `README.md` (raiz). Versão alinhada ao pom `2026.10.14-1`.
+
+```xml
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-billing-core</artifactId>
+    <version>2026.10.14-1</version>
+</dependency>
+<dependency>
+    <groupId>br.com.seedgrid</groupId>
+    <artifactId>seedgrid-billing-stripe</artifactId>
+    <version>2026.10.14-1</version>
+</dependency>
+```
+
+Com `seedgrid-login-tenancy`, o core já vem da foundation. Declare só o `seedgrid-billing-stripe` (README do Stripe).
+
+## 2. Declarar os contadores de uso
+
+Fonte: `seedgrid-billing-core/integration-tests/src/test/java/br/com/seedgrid/billing/it/ProductUsageMeters.java`.
+
+```java
+@ApplicationScoped
+public class ProductUsageMeters implements UsageMeterContributor {
+
+    public static final String REQUESTS = "requests";
+    public static final String STORAGE = "storage-mb";
+
+    @Override
+    public List<UsageMeterDefinition> meters() {
+        return List.of(
+                new UsageMeterDefinition(REQUESTS, "Requisicoes"),
+                new UsageMeterDefinition(STORAGE, "MB armazenados"));
+    }
+}
+```
+
+Regras do README:
+- O código usa `[a-z0-9-]`, com até 40 caracteres, e é uma identidade permanente: não reaproveite.
+- Vários beans `UsageMeterContributor` são somados.
+
+## 3. Consumo por anotação, consumo programático e gate por plano
+
+Fonte: `integration-tests/.../ProductController.java`.
+
+```java
+@Path("/it/product")
+@Authenticated
+@Produces(MediaType.APPLICATION_JSON)
+public class ProductController {
+
+    private final CurrentAccountResolver currentAccountResolver;
+    private final UsageService usageService;
+
+    public ProductController(CurrentAccountResolver currentAccountResolver, UsageService usageService) {
+        this.currentAccountResolver = currentAccountResolver;
+        this.usageService = usageService;
+    }
+
+    // 1 unidade de "requests"; só contabiliza se o método retornar
+    @POST
+    @Path("/work")
+    @ConsumesUsage(meter = ProductUsageMeters.REQUESTS)
+    public Map<String, String> work() {
+        return Map.of("status", "done");
+    }
+
+    // quantidade conhecida só em runtime
+    @POST
+    @Path("/store")
+    @Transactional
+    public Map<String, Object> store(@QueryParam("mb") int mb) {
+        Account account = currentAccountResolver.requireCurrentAccount();
+        usageService.assertCanConsume(account, ProductUsageMeters.STORAGE, mb);
+        usageService.consume(account, ProductUsageMeters.STORAGE, mb, "store-" + UUID.randomUUID());
+        return Map.of("storedMb", mb);
+    }
+
+    // o plano vigente precisa liberar a permissão; senão 402 FEATURE_NOT_IN_PLAN
+    @POST
+    @Path("/premium")
+    @RequiresPlanFeature("IT_PREMIUM_REPORT")
+    public Map<String, String> premium() {
+        return Map.of("status", "premium");
+    }
+}
+```
+
+`@ConsumesUsage` também aceita `units` (padrão `1`). `@RequiresPlanFeature` aceita `message` para personalizar o `detail` do 402.
+
+## 4. Validar `additionalAttributes` do term
+
+Fonte: `integration-tests/.../ProductPlanTermValidator.java`.
+
+```java
+@ApplicationScoped
+public class ProductPlanTermValidator implements PlanTermAdditionalFieldsValidator {
+
+    @Override
+    public void validate(PlanTerm term, Map<String, JsonNode> additionalAttributes) {
+        JsonNode quota = additionalAttributes.get("monthlyRequests");
+        if (quota != null && (!quota.canConvertToInt() || !quota.isIntegralNumber() || quota.asInt() <= 0)) {
+            throw new InvalidPlanTermAdditionalAttributesException("monthlyRequests deve ser inteiro positivo");
+        }
+    }
+}
+```
+
+## 5. Restringir as contas visíveis no admin
+
+Fonte: `seedgrid-billing-core/BILLING_INTEGRATION_GUIDE.md`. O `PartnerService` é do host.
+
+```java
+@RequestScoped
+public class PartnerBillingAccountScope implements BillingAccountScope {
+    @Inject PartnerService partners;
+
+    @Override
+    public Optional<Set<Long>> visibleCompanyIds() {
+        return partners.currentPartner().map(p -> partners.companyIdsOf(p)); // empty() = operador da casa
+    }
+}
+```
+
+## 6. Observar eventos
+
+Fonte: README do Stripe, seção 9, e javadoc de `SubscriptionLifecycleEvent`.
+
+```java
+void aoMudar(@Observes(during = TransactionPhase.AFTER_SUCCESS) SubscriptionLifecycleEvent event) {
+    // event.type(): ACTIVATED, UPGRADED, DOWNGRADE_SCHEDULED, CANCELED, PAST_DUE, TRIAL_ENDED...
+    // event.accountPublicId(), event.toPlanName(), event.effectiveAt(), event.reason()
+}
+
+void aoConsumir(@Observes UsageConsumedEvent event) {
+    // mesma transação do consumo: grave o detalhe do produto
+    // event.meter(), event.units(), event.overageUnits(), event.balanceAfter()
+}
+```
+
+## 7. Criar um term com contadores (REST)
+
+Fonte: README da raiz.
+
+```http
+POST /admin/plans/{planId}/terms
+Content-Type: application/json
+
+{ "monthlyPrice": 149.90, "maxUsers": 3,
+  "meters": [
+    { "meter": "requests",   "includedUnits": 1000, "overagePrice": 0.10 },
+    { "meter": "storage-mb", "includedUnits": 500,  "overagePrice": 0 } ],
+  "additionalAttributes": { "supportLevel": "priority" } }
+```
+
+- `overagePrice > 0`: cada unidade além da franquia é cobrada no meter do contador.
+- `overagePrice = 0`: esgotar a franquia bloqueia com 402.
+
+## 8. Configuração mínima com Stripe
+
+Fonte: `BILLING_INTEGRATION_GUIDE.md`, passo 2. Ver também a [[SeedGrid/Extensions/billing/Configuracao|tabela completa]].
+
+```properties
+seedgrid.billing.stripe.apiKey=${STRIPE_API_KEY}               # <SEGREDO:stripe-api-key>
+seedgrid.billing.stripe.webhookSecret=${STRIPE_WEBHOOK_SECRET} # <SEGREDO:stripe-webhook-secret>
+seedgrid.billing.stripe.product=meu-produto
+seedgrid.billing.checkout.success-url=https://app.exemplo.com/assinatura?ok=1
+seedgrid.billing.checkout.cancel-url=https://app.exemplo.com/assinatura
+seedgrid.billing.portal.return-url=https://app.exemplo.com/assinatura
+seedgrid.billing.feature-gate.exempt-company-ids=1
+```
+
+Em desenvolvimento local, segundo o README do Stripe:
+
+```bash
+stripe login
+stripe listen --forward-to localhost:8080/public/billing/webhook
+# copie o whsec_... impresso para SEEDGRID_BILLING_STRIPE_WEBHOOKSECRET e reinicie a app
+```
+
+## 9. Personalizar os e-mails de acesso
+
+Fonte: `BILLING_INTEGRATION_GUIDE.md`, passo 5, e `UserAccessEmails`.
+
+Coloque arquivos no host em `src/main/resources/templates/billing/{html,txt}/`:
+- `user-access-loss.html` e `user-access-loss.txt`
+- `user-access-restored.html` e `user-access-restored.txt`
+
+Os placeholders disponíveis são `{name}`, `{plan}`, `{explanation}` e `{notice}`.