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étodo | Ruta | Rol | Descripción |
|---|---|---|---|
GET | /billing/platform/provider | Platform super admin | Estado de conexión (connected, providerName, providerUsable, usableForCharges). OWNER/ADMIN → 403 |
POST | /billing/platform/provider/connect | Platform super admin | Conecta el proveedor para cobros Nimobase→tenant. OWNER/ADMIN → 403 |
POST | /billing/platform/provider/disconnect | Platform super admin | Desconecta el proveedor — bloquea nuevos cobros/reembolsos Nimobase→tenant. OWNER/ADMIN → 403 |
GET | /billing/platform/charges | Platform super admin | Historial global; query companyId?, search, status, dateFrom, dateTo. Respuesta { data } con identidad de empresa (companyName, companyEmail), refundedAmount / refundableAmount |
POST | /billing/platform/tenants/:companyId/charges/:chargeId/refund | Platform super admin | Reembolso 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étodo | Ruta | Rol | Descripción |
|---|---|---|---|
GET | /billing/byok/status | OWNER, ADMIN | Estado sin secretos: absent / usable / error |
GET | /billing/byok | OWNER, ADMIN | Listar credenciales BYOK de cobros (sin secretos) |
GET | /billing/byok/:id | OWNER, ADMIN | Obtener un set (sin secretos) |
POST | /billing/byok | OWNER, ADMIN | Registrar (activo por defecto); secretos pueden revelarse una vez |
PATCH | /billing/byok/:id | OWNER, ADMIN | Actualizar / rotar (omitir secreto conserva el anterior) |
DELETE | /billing/byok/:id | OWNER, ADMIN | Eliminar — 204 |
POST | /billing/byok/:id/activate | OWNER, ADMIN | Activar (único activo del tipo) |
DELETE | /billing/byok/:id/activate | OWNER, ADMIN | Desactivar (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étodo | Ruta | Rol | Descripción |
|---|---|---|---|
GET | /billing/connect/status | Autenticado | Estado Connect sin secretos |
POST | /billing/connect/onboarding | OWNER, ADMIN | Inicia onboarding (returnUrl, refreshUrl) |
DELETE | /billing/connect | OWNER, ADMIN | Desconecta — 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étodo | Ruta | Rol | Descripción |
|---|---|---|---|
GET | /billing/charge-mechanism | OWNER, ADMIN | Usables + activo (sin secretos) — |
PUT | /billing/charge-mechanism/active | OWNER, ADMIN | Marcar 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étodo | Ruta | Rol | Descripción |
|---|---|---|---|
GET | /billing/customer-charges | OWNER, ADMIN | Historial de la empresa activa; query search, status, dateFrom, dateTo. Respuesta { data } con refundedAmount / refundableAmount |
POST | /billing/customer-charges | OWNER, ADMIN | Cargo único (amount, currency, customerEmail, idempotencyKey opcional, …) —; respuesta incluye commissionAmount. Misma idempotencyKey → misma fila local |
GET | /billing/customer-charges/:chargeId | OWNER, ADMIN | Consulta; otro tenant / inexistente → 404; incluye commissionAmount / refundableAmount |
POST | /billing/customer-charges/:chargeId/refund | OWNER, ADMIN | Reembolso 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/subscriptions | OWNER, ADMIN | Alta suscripción cliente final (externalPriceId, customerEmail) — |
PATCH | /billing/customer-charges/subscriptions/:externalSubscriptionId | OWNER, ADMIN | Actualiza suscripción — |
POST | /billing/customer-charges/subscriptions/:externalSubscriptionId/cancel | OWNER, ADMIN | Cancela suscripción — |
MEMBER/VIEWER → 403. Estados normalizados: pending, succeeded, failed, canceled, refunded, partially_refunded.
Conceptos clave
| Concepto | Qué es |
|---|---|
| Plan | Define qué funcionalidades incluye una suscripción y sus límites (ej. máximo de usuarios) |
| Precio | La tarifa de un plan: importe, moneda e intervalo de cobro (mensual, anual, etc.) |
| Cliente de billing | Representación del tenant en el sistema de pagos. Un registro por empresa |
| Suscripción | El contrato activo entre el tenant y un precio concreto |
| Entitlement | El acceso real que tiene un tenant a una funcionalidad, derivado de su plan |
| Factura | Registro 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
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
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
GET /billing/plans/publicRuta 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:
[
{
"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.
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):
npm run seed→seedPlatformPlans()- Runtime (PLANS-041-ENSURE-001) →
PlansService.ensurePlatformLadderInstantiated()enonModuleInity antes de cadaGET /billing/plans
Escalera validada:
| Plan | max_users | max_companies | api_access | priority_support | custom_domain | reseller_enabled |
|---|---|---|---|---|---|---|
| Base | 3 | 1 | sí | no | no | no |
| Pro | 15 | 5 | sí | sí | no | no |
| Max | 150 | 25 | sí | 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 entitlementmax_companiesactivo 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 entitlementmax_usersactivo de esa misma empresa (a diferencia demax_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 featureapi_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
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
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
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
GET /billing/catalog/system-options
Authorization: Bearer <token>Devuelve el catálogo fijo — no requiere rol específico:
key | label | type |
|---|---|---|
max_users | Usuarios máximos | limit |
max_companies | Máximo de empresas | limit |
api_access | Acceso a la API | flag |
priority_support | Soporte prioritario | flag |
custom_domain | Dominio personalizado | flag |
reseller_enabled | Reventa habilitada | flag (solo planes de plataforma) |
provider_platform_stripe | Stripe de plataforma | flag |
provider_platform_s3 | Almacenamiento S3 de plataforma | flag |
provider_platform_ai | IA de plataforma | flag |
ai_included_tokens | Tokens de IA incluidos por ciclo | limit |
ai_included_requests | Peticiones de IA incluidas por ciclo | limit |
ai_model_allowlist | Modelos de IA permitidos (plataforma) | list (en metadata / body lists) |
ai_max_tokens_per_request | Techo de tokens por petición | limit |
ai_rate_limit | Rate limit de IA del plan (≤ global) | limit |
ai_assistants | Assistants (chatbots de tenant) | flag (distinto de IA plataforma) |
ai_public_widget | Widget público de assistants | flag (distinto de ai_assistants) |
ai_max_assistants | Máximo de assistants por empresa | limit (opcional; si no está en el plan no hay tope oculto) |
ai_max_skills | Máximo de skills de tenant por empresa | limit (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
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
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
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
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
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
GET /billing/entitlements
Authorization: Bearer <token>
X-Company-Id: <companyId>Verificar acceso a una funcionalidad
GET /billing/entitlements/check?feature=advanced_reports
Authorization: Bearer <token>
X-Company-Id: <companyId>Respuesta:
{ "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
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
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
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
GET /billing/connect/status
Authorization: Bearer <token>Respuesta (ejemplo):
{
"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)
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)
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.
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:
- Verificar firma → rechaza con 400 si es inválida
- Comprobar idempotencia → ignora si el evento ya fue procesado
- Guardar registro pendiente en BD
- Encolar job asíncrono para procesar
- 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:
| Evento | Notificación |
|---|---|
| Pago fallido | PAYMENT_FAILED — avisa por in-app y email |
| Suscripción cancelada | SUBSCRIPTION_CHANGED |
| Nueva factura disponible | INVOICE_AVAILABLE |
| Período de prueba finalizando | TRIAL_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
| Variable | Descripción |
|---|---|
BILLING_PROVIDER | noop (por defecto, sin pagos reales) · stripe |
STRIPE_SECRET_KEY | Clave secreta de Stripe (requerida si BILLING_PROVIDER=stripe) |
STRIPE_WEBHOOK_SECRET | Secreto de firma de webhooks de Stripe |
En entorno local o de test, usa BILLING_PROVIDER=noop — todo funciona sin llamar a ninguna API externa.