Skip to content

Billing y suscripciones ​

El módulo de billing gestiona planes, precios, suscripciones y acceso a funcionalidades de pago. Está desacoplado del proveedor externo — el sistema funciona igual con Stripe que con cualquier otro procesador de pagos.

Cuando el proveedor externo falla en suscripciones, checkout, portal o sincronización de precios, la API no propaga el error crudo de Stripe: responde 502 con código BILLING_PROVIDER_FAILURE y un mensaje fijo, registra el fallo y permite reintentar (/ 007-OBS).

La capa de proveedor (BillingProvider) también expone cargo único, reembolso y consulta de estado sin acoplarse a Stripe. Si no hay proveedor usable (BILLING_PROVIDER=noop o sin credenciales), esas operaciones de cobro se rechazan con un error accionable y no inventan un éxito. Proveedor de plataforma + cobros Nimobase→tenant (listado): un super admin consulta el estado (GET /billing/platform/provider), conecta o desconecta el proveedor (POST /billing/platform/provider/connect|disconnect), lista el historial global (GET /billing/platform/charges) y puede emitir cargos, suscripciones y reembolsos a tenants bajo /billing/platform/tenants/:companyId/.... Los fallos del proveedor no se marcan como éxito. Quien no sea super admin recibe 403 en GET status del proveedor, connect/disconnect, listado y reembolsos.

Cobros plataforma → tenant — proveedor e historial ​

El listado reutiliza billing_payments con metadata.side = platform_to_tenant. Por defecto incluye todas las empresas; companyId es un filtro opcional. El estado y la conexión del proveedor de plataforma son solo super admin (assertSuperAdmin).

MétodoRutaRolDescripción
GET/billing/platform/providerPlatform super adminEstado de conexión (connected, providerName, providerUsable, usableForCharges). OWNER/ADMIN → 403
POST/billing/platform/provider/connectPlatform super adminConecta el proveedor para cobros Nimobase→tenant. OWNER/ADMIN → 403
POST/billing/platform/provider/disconnectPlatform super adminDesconecta el proveedor — bloquea nuevos cobros/reembolsos Nimobase→tenant. OWNER/ADMIN → 403
GET/billing/platform/chargesPlatform super adminHistorial global; query companyId?, search, status, dateFrom, dateTo. Respuesta { data } con identidad de empresa (companyName, companyEmail), refundedAmount / refundableAmount
POST/billing/platform/tenants/:companyId/charges/:chargeId/refundPlatform super adminReembolso total/parcial (amount céntimos opcional, reason opcional). Importe inválido → 400 PLATFORM_BILLING_INVALID_REFUND_AMOUNT

BYOK de cobros del tenant ​

OWNER/ADMIN pueden registrar, activar, desactivar y eliminar credenciales BYOK de cobros de su empresa. Las credenciales viven en el vault de proveedores (familia billing / tipo stripe); esta API no redefine el vault.

MétodoRutaRolDescripción
GET/billing/byok/statusOWNER, ADMINEstado sin secretos: absent / usable / error
GET/billing/byokOWNER, ADMINListar credenciales BYOK de cobros (sin secretos)
GET/billing/byok/:idOWNER, ADMINObtener un set (sin secretos)
POST/billing/byokOWNER, ADMINRegistrar (activo por defecto); secretos pueden revelarse una vez
PATCH/billing/byok/:idOWNER, ADMINActualizar / rotar (omitir secreto conserva el anterior)
DELETE/billing/byok/:idOWNER, ADMINEliminar — 204
POST/billing/byok/:id/activateOWNER, ADMINActivar (único activo del tipo)
DELETE/billing/byok/:id/activateOWNER, ADMINDesactivar (deja de ser usable para nuevos cobros)

MEMBER/VIEWER reciben 403.

Connect ​

OWNER/ADMIN pueden iniciar el onboarding de la cuenta de cobro del tenant, consultar el estado (not_connected / pending / connected / error, sin secretos) y desconectar. Tras un onboarding exitoso Connect queda connected/usable; al desconectar deja de ser usable para nuevos cobros.

MétodoRutaRolDescripción
GET/billing/connect/statusAutenticadoEstado Connect sin secretos
POST/billing/connect/onboardingOWNER, ADMINInicia onboarding (returnUrl, refreshUrl)
DELETE/billing/connectOWNER, ADMINDesconecta — no usable para nuevos cobros

Mecanismo activo ​

OWNER/ADMIN consultan qué mecanismos (BYOK / Connect) están usables y cuál está activo para nuevos cobros empresa→cliente final, y pueden marcar exactamente uno como activo. La resolución:

  • Solo uno usable → se trata como activo.
  • Ambos usables y uno marcado → se usa el marcado.
  • Ambos usables y ninguno marcado → rechazo accionable BILLING_CHARGE_MECHANISM_MUST_CHOOSE.
  • Ninguno usable → rechazo accionable BILLING_CHARGE_MECHANISM_NONE_USABLE.
MétodoRutaRolDescripción
GET/billing/charge-mechanismOWNER, ADMINUsables + activo (sin secretos) —
PUT/billing/charge-mechanism/activeOWNER, ADMINMarcar byok o connect como activo —

Los cobros empresa→cliente final (listado) viven bajo /billing/customer-charges (OWNER/ADMIN).

Cobros empresa → cliente final ​

OWNER/ADMIN cobran a clientes finales con el mecanismo activo usable (BYOK o Connect), vía la misma capa BillingProvider. Comisión de plataforma configurable en bps (settings.platform_billing_commission_bps, default 0); el resultado del cargo incluye commissionAmount (unidades menores). El listado reutiliza los mismos registros de billing_payments (lado tenant_to_customer).

idempotencyKey (opcional) en el body del cargo único: si se repite la misma clave en el mismo tenant, la API reutiliza la fila local existente (mismo id / externalPaymentId) en lugar de insertar un segundo cobro.

MétodoRutaRolDescripción
GET/billing/customer-chargesOWNER, ADMINHistorial de la empresa activa; query search, status, dateFrom, dateTo. Respuesta { data } con refundedAmount / refundableAmount
POST/billing/customer-chargesOWNER, ADMINCargo único (amount, currency, customerEmail, idempotencyKey opcional, …) —; respuesta incluye commissionAmount. Misma idempotencyKey → misma fila local
GET/billing/customer-charges/:chargeIdOWNER, ADMINConsulta; otro tenant / inexistente → 404; incluye commissionAmount / refundableAmount
POST/billing/customer-charges/:chargeId/refundOWNER, ADMINReembolso total/parcial (amount céntimos opcional, reason opcional). Importe inválido → 400 BILLING_CUSTOMER_CHARGE_INVALID_REFUND_AMOUNT. Mecanismo no operable → 400
POST/billing/customer-charges/subscriptionsOWNER, ADMINAlta suscripción cliente final (externalPriceId, customerEmail) —
PATCH/billing/customer-charges/subscriptions/:externalSubscriptionIdOWNER, ADMINActualiza suscripción —
POST/billing/customer-charges/subscriptions/:externalSubscriptionId/cancelOWNER, ADMINCancela suscripción —

MEMBER/VIEWER → 403. Estados normalizados: pending, succeeded, failed, canceled, refunded, partially_refunded.

Conceptos clave ​

ConceptoQué es
PlanDefine qué funcionalidades incluye una suscripción y sus límites (ej. máximo de usuarios)
PrecioLa tarifa de un plan: importe, moneda e intervalo de cobro (mensual, anual, etc.)
Cliente de billingRepresentación del tenant en el sistema de pagos. Un registro por empresa
SuscripciónEl contrato activo entre el tenant y un precio concreto
EntitlementEl acceso real que tiene un tenant a una funcionalidad, derivado de su plan
FacturaRegistro de un cobro generado por la suscripción

Los entitlements son la interfaz estable para el resto de la plataforma. Otros módulos preguntan "¿tiene este tenant acceso a X?" sin saber nada de suscripciones ni proveedores.

Ciclo de vida de una suscripción ​

trialing → active → past_due → canceled
                 ↘           ↗
                   paused
                            ↘
                             expired
  • trialing — período de prueba activo
  • active — suscripción vigente, entitlements activos
  • past_due — pago fallido, todavía en período de gracia
  • paused — suscripción pausada
  • canceled — cancelada; entitlements revocados
  • expired — terminada definitivamente

Los cambios de estado llegan vía webhooks del proveedor y se procesan de forma asíncrona para no bloquear la respuesta HTTP.

Planes y precios ​

Listar planes disponibles ​

http
GET /billing/plans
Authorization: Bearer <token>

Devuelve los planes activos con sus precios. No requiere rol específico. Un plan desactivado (isActive: false) desaparece de este listado — deja de ofrecerse a nuevos checkouts/suscripciones (ver "Desactivar un plan" más abajo). GET /billing/plans/:id sigue devolviendo un plan inactivo si se conoce su UUID.

Listado admin (incluye inactivos) — ?includeInactive=true ​

http
GET /billing/plans?includeInactive=true
Authorization: Bearer <token-super-admin>

Variante solo para super admin de la plataforma (isSuperAdmin: true) que también incluye los planes desactivados — 403 para cualquier otro caller. Sin el parámetro (o includeInactive=false) el comportamiento público de arriba no cambia. Existe para que un plan desactivado desde el panel Super Admin siga siendo visible/editable/reactivable ahí mismo en lugar de desaparecer para siempre del listado propio del admin (PLANS-041-007-FIX, hallazgo de QA sobre).

Planes públicos para la landing — GET /billing/plans/public ​

http
GET /billing/plans/public

Ruta pública, sin autenticación — pensada para la landing comercial (/) del frontend, que necesita mostrar planes reales antes de que el visitante se registre. Devuelve únicamente los planes que son activos Y están marcados como visibles en la landing (isVisibleOnLanding: true, ver más abajo). Un plan inactivo nunca aparece aquí aunque esté marcado como visible.

La respuesta usa una whitelist de campos estricta — nunca el objeto entidad crudo — para no filtrar nada interno:

json
[
  {
    "name": "Pro",
    "description": "Plan para equipos",
    "prices": [{ "amount": 2900, "currency": "usd", "interval": "monthly" }],
    "features": ["api_access", "priority_support"]
  }
]

Campos nunca expuestos: id, isActive, isVisibleOnLanding, limits, metadata, ni el id de proveedor de pago (externalPriceId, p. ej. el price id de Stripe). Solo se incluyen precios activos (isActive: true) de cada plan. Sujeta al mismo rate limiting global (ThrottlerGuard) que cualquier otra ruta de la API — no hay excepción para rutas públicas.

Visibilidad en la landing (isVisibleOnLanding) — ​

Cada plan tiene un flag isVisibleOnLanding (por defecto false, oculto) que controla si aparece en GET /billing/plans/public. Solo un super admin de la plataforma puede fijarlo, y solo desde POST /billing/plans (crear) o PATCH /billing/plans/:id (actualizar) — mismo gate de assertSuperAdmin() que el resto de la gestión de planes. Un plan recién creado queda oculto hasta que se marque explícitamente como visible; los planes que ya existían antes de este flag (p. ej. el plan interno de administrador) migran a isVisibleOnLanding: false por el valor por defecto de la columna, así que tampoco aparecen en la landing hasta que un super admin los marque a propósito.

http
PATCH /billing/plans/:id
Authorization: Bearer <token-super-admin>
Content-Type: application/json

{ "name": "Pro", "isVisibleOnLanding": true }

Planes sembrados por defecto (npm run seed + ensure en runtime) ​

El catálogo de planes de plataforma Base / Pro / Max se materializa de dos formas equivalentes (misma constante PLATFORM_PLAN_LADDER en src/api/billing/constants/platform-plan-ladder.ts):

  1. npm run seed → seedPlatformPlans()
  2. Runtime (PLANS-041-ENSURE-001) → PlansService.ensurePlatformLadderInstantiated() en onModuleInit y antes de cada GET /billing/plans

Escalera validada:

Planmax_usersmax_companiesapi_accesspriority_supportcustom_domainreseller_enabled
Base31sínonono
Pro155sísínono
Max15025sísísísí

Este seed/ensure es idempotente pero de forma más estricta que el resto del script: si ya existe cualquier plan de plataforma (aunque no se llame Base/Pro/Max), el seed completo de la escalera se omite — no rellena tiers faltantes ni pisa planes existentes. Solo se ejecuta cuando billing_plans está completamente vacía. No crea precios: el checkout sigue necesitando POST /billing/plans/:id/prices (o un Super Admin) para adjuntar importes.

Estos límites sí se aplican sobre la cuenta/tenant del owner:

  • max_companies — CompaniesService.create() (PLANS-003) consulta el entitlement max_companies activo de las empresas que el owner ya posee y rechaza con 409 Conflict la creación de una empresa adicional una vez alcanzado el límite del plan — ver Empresas para el detalle del comportamiento y del mensaje de error.
  • max_users — CompaniesService.addUser() consulta el entitlement max_users activo de esa misma empresa (a diferencia de max_companies, no se agrega a nivel owner) y rechaza con 409 Conflict añadir un miembro adicional una vez alcanzado el límite — ver Empresas.
  • api_access — ApiKeysService.create() (POST /api-keys) lee la suscripción activa del tenant y rechaza con 403 Forbidden la creación de una API key si el plan de esa suscripción no declara el feature api_access — ver API Keys. Un tenant sin suscripción activa no se bloquea (comportamiento pre-existente, agnóstico de billing).

En los tres casos, un owner/tenant sin ninguna suscripción activa no se ve afectado — no hay nada que enforcear hasta que se contrata un plan. priority_support y custom_domain se almacenan y se muestran en el catálogo, pero no tienen enforcement en esta entrega: no existe todavía un módulo de producto que dependa de ellos (fuera de alcance de este módulo). Ver también company-ownership.md y.

Crear un plan ​

http
POST /billing/plans
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Pro",
  "description": "Plan para equipos",
  "features": ["api_access", "priority_support"],
  "limits": { "max_users": 15, "max_companies": 5 }
}

Los planes son un recurso global de la plataforma — no pertenecen a ningún tenant (BillingPlanEntity no tiene companyId). Por eso, crear o modificar un plan requiere ser super admin de la plataforma (isSuperAdmin: true), no basta con ser OWNER/ADMIN de una empresa: un rol de empresa solo autoriza a actuar sobre los recursos de esa empresa, y un plan no pertenece a ninguna. Lo mismo aplica a PATCH /billing/plans/:id y a añadir precios (más abajo).

isVisibleOnLanding es opcional en el body — si se omite, el plan queda oculto (false) por defecto; ver "Visibilidad en la landing" más arriba.

Validación contra el catálogo: cada clave de features debe ser una opción de catálogo de tipo flag (de sistema o personalizada de plataforma no archivada) y cada clave de limits debe ser una de tipo limit, con valor numérico ≥ 0 — ver "Catálogo de features y límites" más abajo. Una clave inexistente, del tipo equivocado, o un límite negativo/no numérico devuelve 400 Bad Request. Al editar un plan que ya tenía una personalizada archivada, esa clave se puede conservar sin error; solo se rechaza al intentar añadirla a un plan que no la tenía.

Desactivar un plan ​

http
PATCH /billing/plans/:id
Authorization: Bearer <token>
Content-Type: application/json

{ "name": "Pro", "isActive": false }

Desactivar un plan lo saca de GET /billing/plans y bloquea POST /billing/subscription y POST /billing/checkout para ese plan con 400 Bad Request — no se ofrece a nuevas suscripciones. Los tenants que ya tenían una suscripción activa a ese plan no pierden sus entitlements de inmediato: los conservan hasta que termine el periodo vigente o hasta que cambien de plan (no hay revocación automática al desactivar).

Añadir un precio a un plan ​

http
POST /billing/plans/:id/prices
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 2900,
  "currency": "usd",
  "interval": "monthly"
}

El importe va en centavos (2900 = $29.00). Intervalos disponibles: monthly, yearly, weekly, one_time.

Solo puede existir un precio activo por intervalo en un mismo plan. Requiere ser super admin de la plataforma — mismo motivo que crear/actualizar un plan.

Si la sincronización con el proveedor de pagos falla, responde 502 BILLING_PROVIDER_FAILURE (retryable: true) y no persiste el precio local — puedes reintentar.

Catálogo de features y límites ​

En vez de escribir features/limits de un plan como claves sueltas, hay un catálogo con etiquetas humanas: opciones de sistema (fijas, no eliminables) más personalizadas (añadidas por quien gestiona el catálogo). Esta sección cubre el alcance plataforma (Super Admin → planes de billing/plans); el alcance empresa (Owner/Admin → planes de reventa, owner_plans) usa el mismo modelo de opciones de sistema pero con su propio catálogo de personalizadas por empresa — ver Planes de reventa del owner.

Opciones de sistema ​

http
GET /billing/catalog/system-options
Authorization: Bearer <token>

Devuelve el catálogo fijo — no requiere rol específico:

keylabeltype
max_usersUsuarios máximoslimit
max_companiesMáximo de empresaslimit
api_accessAcceso a la APIflag
priority_supportSoporte prioritarioflag
custom_domainDominio personalizadoflag
reseller_enabledReventa habilitadaflag (solo planes de plataforma)
provider_platform_stripeStripe de plataformaflag
provider_platform_s3Almacenamiento S3 de plataformaflag
provider_platform_aiIA de plataformaflag
ai_included_tokensTokens de IA incluidos por ciclolimit
ai_included_requestsPeticiones de IA incluidas por ciclolimit
ai_model_allowlistModelos de IA permitidos (plataforma)list (en metadata / body lists)
ai_max_tokens_per_requestTecho de tokens por peticiónlimit
ai_rate_limitRate limit de IA del plan (≤ global)limit
ai_assistantsAssistants (chatbots de tenant)flag (distinto de IA plataforma)
ai_public_widgetWidget público de assistantsflag (distinto de ai_assistants)
ai_max_assistantsMáximo de assistants por empresalimit (opcional; si no está en el plan no hay tope oculto)
ai_max_skillsMáximo de skills de tenant por empresalimit (opcional; si no está en el plan no hay tope oculto)

Este catálogo no se persiste ni se edita por API — vive como constante en el código (src/api/billing/constants/system-catalog-options.ts) y es la fuente de verdad para las claves usadas en BillingPlanEntity.features/.limits.

Personalizadas de plataforma ​

http
GET /billing/catalog/custom-options?includeArchived=false
POST /billing/catalog/custom-options
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "white_label_reports",
  "label": "Informes de marca blanca",
  "type": "flag"
}

Crear/archivar/reactivar personalizadas de plataforma requiere ser super admin de la plataforma (mismo motivo que crear/editar planes). key es único frente al catálogo de sistema y frente a otras personalizadas del mismo alcance — un choque devuelve 409 Conflict.

Archivar una personalizada ​

http
POST /billing/catalog/custom-options/:id/archive
Authorization: Bearer <token>

Archivar es un flag, nunca un borrado: la personalizada deja de ofrecerse en el listado por defecto (includeArchived=false, el que usa el editor de planes al añadir opciones nuevas), pero el valor que ya tenían los planes existentes no se toca — GET /billing/catalog/custom-options?includeArchived=true sigue devolviéndola. POST .../unarchive la reactiva.

Suscripciones ​

Las rutas de suscripciones, facturas, entitlements, checkout, portal y Connect operan sobre la empresa activa que TenantInterceptor resuelve en el contexto de la petición. Para cualquier JWT de usuario, incluido Super Admin, X-Company-Id solo puede seleccionar una empresa con membresía UserCompany activa, y se aplican sus roles/grants actuales. Las API keys siguen ligadas a su empresa. Las rutas de plataforma /billing/platform/* conservan su companyId explícito y sus permisos de operación global de plataforma.

Ver la suscripción actual del tenant ​

http
GET /billing/subscription
Authorization: Bearer <token>
X-Company-Id: <companyId>

Devuelve la suscripción más reciente con su estado, fechas de período y si está programada para cancelarse; responde null si el tenant aún no tiene una. Las relaciones plan y price pueden omitirse según la ruta que produjo la respuesta. Las fechas se serializan como ISO 8601.

Crear o actualizar una suscripción ​

http
POST /billing/subscription
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json

{
  "priceId": "uuid-del-precio",
  "trialDays": 14
}

trialDays es opcional. Requiere rol OWNER o ADMIN. Si el tenant ya tiene una suscripción activa, este POST la actualiza in-place (plan/precio, período y entitlements) en lugar de insertar una segunda fila —.

Si el proveedor de pagos falla durante la creación/actualización, la API responde 502 con código BILLING_PROVIDER_FAILURE (mensaje fijo, retryable: true). No se confirma el éxito ni se deja una suscripción inconsistente — puedes reintentar la misma operación.

Cancelar una suscripción ​

http
DELETE /billing/subscription
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json

{ "atPeriodEnd": true }
  • atPeriodEnd: true — la suscripción continúa hasta el final del período actual y luego se cancela. Los entitlements permanecen activos hasta entonces.
  • atPeriodEnd: false — cancelación inmediata. Los entitlements se revocan al instante.

Requiere rol OWNER o ADMIN. Un fallo del proveedor en la cancelación también responde 502 BILLING_PROVIDER_FAILURE (reintentable); el estado local no se marca como cancelado si Stripe no completó la operación.

Entitlements ​

Las respuestas de suscripción, factura y entitlement exponen los campos de sus registros existentes con fechas ISO 8601. La suscripción puede incluir plan y price; esas relaciones son opcionales. Los metadatos son informativos y no deben tratarse como secretos ni como entrada editable.

Los entitlements son la forma correcta de preguntar si un tenant tiene acceso a algo:

Listar entitlements del tenant ​

http
GET /billing/entitlements
Authorization: Bearer <token>
X-Company-Id: <companyId>

Verificar acceso a una funcionalidad ​

http
GET /billing/entitlements/check?feature=advanced_reports
Authorization: Bearer <token>
X-Company-Id: <companyId>

Respuesta:

json
{ "has": true, "feature": "advanced_reports" }

Esta llamada es la que deben hacer los demás módulos para controlar el acceso a funcionalidades de pago.

Facturas ​

http
GET /billing/invoices
Authorization: Bearer <token>
X-Company-Id: <companyId>

Lista las facturas del tenant en orden cronológico inverso.

Sesiones de pago (Stripe) ​

Para flujos de pago con interfaz visual se pueden generar sesiones de Stripe:

Checkout — suscribirse a un plan ​

http
POST /billing/checkout
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json

{
  "priceId": "uuid-del-precio",
  "successUrl": "https://mi-app.com/billing/success",
  "cancelUrl": "https://mi-app.com/billing/cancel"
}

Devuelve { "url": "https://checkout.stripe.com/..." }. Redirige al usuario a esa URL.

Si Stripe no puede crear la sesión, responde 502 BILLING_PROVIDER_FAILURE (retryable: true) — no hay URL de éxito inventada.

Portal de facturación — gestionar suscripción existente ​

http
POST /billing/portal
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json

{ "returnUrl": "https://mi-app.com/billing" }

Devuelve { "url": "..." } con la sesión del portal de Stripe donde el usuario puede actualizar su método de pago, ver facturas y cancelar.

Fallo del proveedor → 502 BILLING_PROVIDER_FAILURE (reintentable).

Connect (cuenta de cobro del tenant) — ​

Enlace de la cuenta de cobro del tenant vía onboarding del proveedor (p. ej. Stripe Connect). No expone secretos.

Consultar estado ​

http
GET /billing/connect/status
Authorization: Bearer <token>

Respuesta (ejemplo):

json
{
  "status": "not_connected",
  "usable": false,
  "providerName": "noop",
  "onboardingUrl": null,
  "errorCode": null,
  "errorMessage": null
}

Valores de status: not_connected | pending | connected | error. usable es true solo cuando Connect está conectado y usable para nuevos cobros.

Iniciar onboarding (OWNER / ADMIN) ​

http
POST /billing/connect/onboarding
Authorization: Bearer <token>
Content-Type: application/json

{
  "returnUrl": "https://localhost:4201/settings/billing/connect/return",
  "refreshUrl": "https://localhost:4201/settings/billing/connect/refresh"
}

Devuelve status: pending y onboardingUrl para redirigir al usuario. Tras completar el onboarding, GET /billing/connect/status pasa a connected / usable: true. MEMBER y VIEWER reciben 403.

Desconectar (OWNER / ADMIN) ​

http
DELETE /billing/connect
Authorization: Bearer <token>

Marca Connect como not_connected / no usable para nuevos cobros. MEMBER y VIEWER reciben 403.

Webhooks ​

El endpoint de webhook es público (no requiere token JWT) pero verifica la firma criptográfica del proveedor antes de procesar nada.

http
POST /webhooks/stripe
stripe-signature: <firma>
Content-Type: application/json

<payload sin parsear>

El endpoint está gestionado por el módulo genérico de Webhooks — consulta la página Webhooks para detalles sobre la infraestructura.

El flujo es:

  1. Verificar firma → rechaza con 400 si es inválida
  2. Comprobar idempotencia → ignora si el evento ya fue procesado
  3. Guardar registro pendiente en BD
  4. Encolar job asíncrono para procesar
  5. Devolver { "received": true } inmediatamente

El procesamiento real ocurre en background, sin bloquear la respuesta al proveedor.

Notificaciones automáticas ​

Cuando ocurren eventos de billing, el sistema notifica automáticamente a todos los miembros del tenant afectado:

EventoNotificación
Pago fallidoPAYMENT_FAILED — avisa por in-app y email
Suscripción canceladaSUBSCRIPTION_CHANGED
Nueva factura disponibleINVOICE_AVAILABLE
Período de prueba finalizandoTRIAL_ENDING

Multi-tenancy ​

El billing pertenece al tenant (empresa), no a un usuario concreto. Cada empresa tiene su propio cliente de billing, sus propias suscripciones y sus propios entitlements. Un tenant nunca puede ver ni afectar el billing de otro.

Configuración ​

VariableDescripción
BILLING_PROVIDERnoop (por defecto, sin pagos reales) · stripe
STRIPE_SECRET_KEYClave secreta de Stripe (requerida si BILLING_PROVIDER=stripe)
STRIPE_WEBHOOK_SECRETSecreto de firma de webhooks de Stripe

En entorno local o de test, usa BILLING_PROVIDER=noop — todo funciona sin llamar a ninguna API externa.