# Modulo 4 Operacion (Suscripciones, Planes y Facturacion)

## Alcance
- Planes mensual/anual y limites por tenant.
- Trial gratis por dias.
- Suscripcion con estados: `trialing`, `active`, `past_due`, `cancelled`.
- Facturas y transacciones.
- Cobro recurrente manual y por cron.
- Politica de retry y suspension por impago.

## Politica de impago
- Al fallar cobro se incrementa `failed_attempts`.
- Con proveedor `manual`, el estado pasa a `past_due`.
- Si `failed_attempts >= 3`, el tenant pasa a `suspended`.
- Al pagar factura manualmente, vuelve a `active` y se reinicia contador.

## Operaciones clave
1. Cambiar plan/ciclo/proveedor:
- Modulo `Suscripciones`.
- Formulario `Actualizar suscripcion`.

2. Aplicar trial:
- Formulario `Prueba gratis`.

3. Ejecutar cobro manual:
- Boton `Ejecutar ciclo ahora`.

4. Reintentar cobro de past_due:
- Boton `Reintentar cobro past_due`.

5. Regularizar factura:
- En tabla de facturas usar `Marcar pagada`.

6. Cancelar/reactivar:
- Botones `Cancelar` y `Reactivar`.

## Endpoints operativos
- `POST /cron/billing?tenant={slug}`
- `POST /cron/billing-retry?tenant={slug}`
- `POST /cron/billing-monitor?tenant={slug}`
- `POST /cron/backup?tenant={slug}`
- `GET /api/v1/billing/subscription?tenant={slug}`
- `GET /api/v1/billing/invoices?tenant={slug}`
- `GET /api/v1/billing/payment-methods?tenant={slug}`
- `GET /api/v1/billing/status-history?tenant={slug}`
- `GET /api/v1/billing/health?tenant={slug}`
- `POST /api/v1/billing/run-cycle?tenant={slug}`
- `POST /api/v1/billing/retry?tenant={slug}`
- `POST /billing/webhook?tenant={slug}`
- `POST /billing/stripe/customer/sync?tenant={slug}`
- `POST /billing/stripe/payment-method/attach?tenant={slug}`
- `POST /billing/stripe/invoice/charge?tenant={slug}`
- `GET /billing/invoice/print?tenant={slug}&id={invoice_id}`

## Seguridad operativa
- Configurar `.env`:
- `APP_INTERNAL_SECRET=...`
- `IMPERSONATION_READ_ONLY=1` (opcional recomendado para soporte)
- `STRIPE_WEBHOOK_SECRET=whsec_...` (si usas Stripe)
- `STRIPE_SECRET_KEY=sk_test_...` (si usas cobro real Stripe)
- Cron/webhooks deben enviar `X-Internal-Secret` (o `secret`).

## Acceso sin login manual (portal maestro)
- Desde Billing > Empresas y licencias usar `Entrar al CRM`.
- Se genera token de impersonacion one-time (60s).
- Redirige a `/impersonate?tenant={slug}&token=...`.
- El token se consume una sola vez y deja traza en auditoria.

## Auditoria esperada
- `billing.subscription_updated`
- `billing.plan_updated`
- `billing.trial_set`
- `billing.subscription_cancelled`
- `billing.subscription_resumed`
- `billing.run_cycle_manual`
- `billing.retry_cycle_manual`
- `billing.invoice_paid_manual`
- `billing.tax_profile_saved`
- `billing.payment_method_saved`
- `billing.payment_method_default_set`
- `billing.self_plan_change`
- `billing.self_cancel`