erp-core/docs/04-modelado/especificaciones-tecnicas/backend/mgn-015

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	API de Planes de Suscripción	RF-001	Especificado
ET-MGN-015-002	API de Suscripciones	RF-002	Especificado
ET-MGN-015-003	API de Métodos de Pago	RF-003	Especificado
ET-MGN-015-004	API de Facturación	RF-004	Especificado
ET-MGN-015-005	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

# 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

// 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