# MGN-015: Especificaciones Técnicas Backend

## Descripción

Especificaciones técnicas de la API REST para el módulo de Billing y Suscripciones. Incluye endpoints para gestión de planes, suscripciones, métodos de pago, facturación y métricas de uso.

## Especificaciones Disponibles

| ID | Nombre | RF Relacionado | Estado |
|----|--------|----------------|--------|
| [ET-MGN-015-001](./ET-MGN-015-001-api-planes-suscripcion.md) | API de Planes de Suscripción | RF-001 | Especificado |
| [ET-MGN-015-002](./ET-MGN-015-002-api-suscripciones.md) | API de Suscripciones | RF-002 | Especificado |
| [ET-MGN-015-003](./ET-MGN-015-003-api-metodos-pago.md) | API de Métodos de Pago | RF-003 | Especificado |
| [ET-MGN-015-004](./ET-MGN-015-004-api-facturacion.md) | API de Facturación | RF-004 | Especificado |
| [ET-MGN-015-005](./ET-MGN-015-005-api-uso-metricas.md) | API de Uso y Métricas | RF-005 | Especificado |

## Estructura del Módulo

```
src/modules/billing/
├── index.ts                    # Exports del módulo
├── billing.routes.ts           # Router principal
├── plans/
│   ├── plans.controller.ts
│   ├── plans.service.ts
│   ├── plans.routes.ts
│   └── plans.validation.ts
├── subscriptions/
│   ├── subscriptions.controller.ts
│   ├── subscriptions.service.ts
│   ├── subscriptions.routes.ts
│   └── subscriptions.validation.ts
├── payment-methods/
│   ├── payment-methods.controller.ts
│   ├── payment-methods.service.ts
│   ├── payment-methods.routes.ts
│   └── payment-methods.validation.ts
├── invoices/
│   ├── invoices.controller.ts
│   ├── invoices.service.ts
│   ├── invoices.routes.ts
│   └── invoices.validation.ts
├── usage/
│   ├── usage.controller.ts
│   ├── usage.service.ts
│   └── usage.routes.ts
├── webhooks/
│   ├── stripe.webhook.ts
│   └── webhook.routes.ts
├── jobs/
│   ├── subscription-renewal.job.ts
│   ├── payment-retry.job.ts
│   ├── invoice-generation.job.ts
│   └── record-usage.job.ts
└── services/
    ├── pac.service.ts          # Integración PAC para CFDI
    └── stripe.service.ts       # Integración Stripe
```

## Rutas de la API

### Planes (Super Admin)
| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | /api/v1/billing/plans | Listar planes |
| GET | /api/v1/billing/plans/:id | Obtener plan |
| POST | /api/v1/billing/plans | Crear plan |
| PUT | /api/v1/billing/plans/:id | Actualizar plan |
| DELETE | /api/v1/billing/plans/:id | Eliminar plan |
| PATCH | /api/v1/billing/plans/:id/toggle | Activar/desactivar |

### Suscripciones (Tenant Owner)
| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | /api/v1/billing/subscription | Suscripción actual |
| POST | /api/v1/billing/subscription/upgrade | Upgrade de plan |
| POST | /api/v1/billing/subscription/downgrade | Downgrade de plan |
| POST | /api/v1/billing/subscription/cancel | Cancelar suscripción |
| POST | /api/v1/billing/subscription/reactivate | Reactivar |
| PUT | /api/v1/billing/subscription/billing-cycle | Cambiar ciclo |
| GET | /api/v1/billing/subscription/history | Historial |

### Métodos de Pago (Tenant Owner)
| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | /api/v1/billing/payment-methods | Listar métodos |
| POST | /api/v1/billing/payment-methods/setup-intent | Crear setup intent |
| POST | /api/v1/billing/payment-methods | Agregar método |
| PATCH | /api/v1/billing/payment-methods/:id/default | Establecer default |
| DELETE | /api/v1/billing/payment-methods/:id | Eliminar método |

### Facturas (Tenant Owner)
| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | /api/v1/billing/invoices | Listar facturas |
| GET | /api/v1/billing/invoices/:id | Obtener factura |
| GET | /api/v1/billing/invoices/:id/pdf | Descargar PDF |
| GET | /api/v1/billing/invoices/:id/xml | Descargar XML CFDI |
| POST | /api/v1/billing/invoices/:id/request-cfdi | Solicitar CFDI |
| POST | /api/v1/billing/invoices/:id/retry-payment | Reintentar pago |

### Uso y Métricas (Usuarios)
| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | /api/v1/billing/usage | Uso actual |
| GET | /api/v1/billing/usage/history | Historial de uso |
| GET | /api/v1/billing/usage/check | Verificar acción |
| GET | /api/v1/billing/features | Features habilitadas |
| GET | /api/v1/billing/features/:feature | Verificar feature |

### Webhooks
| Método | Ruta | Descripción |
|--------|------|-------------|
| POST | /api/v1/webhooks/stripe | Webhook de Stripe |

## Integraciones Externas

### Stripe
- **Uso:** Procesamiento de pagos, tokenización de tarjetas
- **Endpoints:** PaymentIntents, SetupIntents, Customers, PaymentMethods
- **Webhooks:** payment_method.updated, customer.source.expiring

### PAC (Proveedor Autorizado de Certificación)
- **Uso:** Timbrado de CFDI para facturas mexicanas
- **Opciones:** Facturama, SW Sapien, Finkok
- **Funciones:** validateRFC, timbrar, cancelar

## Variables de Entorno

```env
# Stripe
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# PAC para CFDI
PAC_PROVIDER=facturama
PAC_USER=xxx
PAC_PASSWORD=xxx
PAC_SANDBOX=false

# Datos fiscales del emisor
CFDI_RFC_EMISOR=XXX123456789
CFDI_NOMBRE_EMISOR=Mi Empresa S.A. de C.V.
CFDI_REGIMEN_FISCAL=601
CFDI_LUGAR_EXPEDICION=12345

# Modo de despliegue
DEPLOYMENT_MODE=saas  # o 'single_tenant'
```

## Jobs Programados

| Job | Frecuencia | Descripción |
|-----|------------|-------------|
| generateRenewalInvoices | Diario 00:00 | Genera facturas 1 día antes de renovación |
| processSubscriptionRenewals | Diario 01:00 | Procesa renovaciones de suscripciones |
| retryFailedPayments | Cada hora | Reintenta pagos fallidos (días 1, 3, 7) |
| recordUsageMetrics | Cada 6 horas | Registra métricas de uso por tenant |
| sendExpirationAlerts | Diario | Envía alertas de tarjetas por vencer |

## Middlewares Específicos

```typescript
// Verificar límites antes de acciones
router.post('/users', checkUserLimit, usersController.create);
router.post('/companies', checkCompanyLimit, companiesController.create);

// Verificar features habilitadas
router.use('/crm', requireFeature('crm'));
router.use('/projects', requireFeature('projects'));
```

## Seguridad

1. **PCI-DSS:** Nunca almacenar datos sensibles de tarjetas
2. **Webhooks:** Verificar firma de Stripe en cada request
3. **Autorización:** Roles específicos por endpoint
4. **Rate limiting:** Aplicar en endpoints de pago

## Notas de Implementación

1. Este módulo se oculta completamente en modo `single_tenant`
2. Los planes son entidades globales (sin tenant_id)
3. Las suscripciones y facturas tienen tenant_id y RLS
4. El caché de uso se invalida en cada cambio de recursos