erp-core/docs/04-modelado/requerimientos-funcionales/mgn-015/RF-MGN-015-004-facturacion-cobros.md

RF-MGN-015-004: Facturación y Cobros

Módulo: MGN-015 - Billing y Suscripciones Prioridad: P0 (MVP para SaaS) Story Points: 13 Estado: Definido Fecha: 2025-11-24

Descripción

El sistema debe generar facturas automáticamente por las suscripciones contratadas, procesar cobros mediante los métodos de pago registrados, y mantener un historial completo de transacciones. En México, debe soportar la generación de CFDI (Comprobante Fiscal Digital por Internet).

Actores

• Actor Principal: Sistema (generación automática)
• Actores Secundarios:
  • Tenant Owner (consulta y descarga)
  • Gateway de Pagos (procesamiento)
  • PAC (timbrado CFDI para México)

Precondiciones

1. Suscripción activa con plan de pago
2. Método de pago válido registrado
3. Datos fiscales del tenant (para CFDI)
4. Integración con gateway de pagos activa

Flujo Principal - Facturación Automática

1. Sistema detecta suscripción próxima a renovar (1 día antes)
2. Sistema genera factura con líneas correspondientes:
   • Plan de suscripción (período)
   • Uso adicional si aplica
   • Descuentos/cupones activos
3. Sistema calcula subtotal, impuestos, total
4. Sistema intenta cobrar al método de pago principal
5. Si cobro exitoso:
   • Registra pago en billing.payments
   • Marca factura como paid
   • Genera CFDI si es requerido
   • Envía factura por email
6. Si cobro falla: Inicia flujo de reintentos

Flujos Alternativos

FA-1: Cobro Fallido

1. Gateway rechaza transacción
2. Sistema registra error en factura (billing_errors)
3. Sistema marca factura como pending
4. Sistema notifica al tenant owner
5. Sistema programa reintento (día 1, 3, 7)
6. Si todos fallan: Suspende suscripción

FA-2: Factura con Cupón

1. Sistema detecta cupón activo en suscripción
2. Sistema aplica descuento según tipo (porcentaje/fijo)
3. Sistema reduce monto a cobrar
4. Línea de descuento aparece en factura
5. Sistema actualiza usos restantes del cupón

FA-3: Solicitud de CFDI

1. Tenant owner solicita CFDI de factura
2. Sistema valida datos fiscales completos (RFC, razón social)
3. Sistema genera XML según especificación SAT
4. Sistema envía a PAC para timbrado
5. PAC retorna UUID y sello
6. Sistema almacena XML timbrado
7. Usuario puede descargar PDF y XML

FA-4: Nota de Crédito

1. Admin genera nota de crédito (reembolso parcial/total)
2. Sistema crea factura con amount negativo
3. Sistema procesa reembolso vía gateway
4. Si CFDI: Genera comprobante de egreso
5. Crédito disponible para próximas facturas

Reglas de Negocio

• RN-1: Facturas se generan 1 día antes de renovación
• RN-2: Cobro automático usa método de pago principal
• RN-3: IVA 16% para clientes en México
• RN-4: CFDI obligatorio para clientes con RFC
• RN-5: Facturas pagadas no se pueden modificar
• RN-6: Reembolsos solo mediante nota de crédito
• RN-7: Historial de facturas disponible por 5 años
• RN-8: Numeración consecutiva por serie

Criterios de Aceptación

• Sistema genera facturas automáticamente por renovación
• Sistema procesa cobros al método de pago principal
• Tenant owner puede ver historial de facturas
• Tenant owner puede descargar PDF de facturas
• Sistema genera CFDI para clientes mexicanos
• Tenant owner puede descargar XML de CFDI
• Sistema aplica cupones/descuentos correctamente
• Sistema maneja reintentos de cobros fallidos
• Admin puede generar notas de crédito
• Sistema envía facturas por email

Entidades Involucradas

• Principales:
  • billing.invoices (id, tenant_id, subscription_id, status, subtotal, tax, total)
  • billing.invoice_lines (id, invoice_id, description, quantity, unit_price)
  • billing.payments (id, invoice_id, amount, status, gateway_response)
• Relacionadas:
  • billing.subscriptions (suscripción facturada)
  • billing.payment_methods (método de cobro)
  • billing.coupon_redemptions (descuentos aplicados)

Estados de Factura

draft → pending → paid
              ↓
           overdue → void

paid → refunded (nota de crédito)

Estado	Descripción
draft	En preparación
pending	Emitida, pendiente de pago
paid	Pagada
overdue	Vencida (pago fallido)
void	Anulada
refunded	Reembolsada

Estructura de Factura

┌────────────────────────────────────────────────┐
│ FACTURA #INV-2024-0001                         │
│ Fecha: 2024-01-15                              │
├────────────────────────────────────────────────┤
│ Cliente: Demo Company S.A. de C.V.             │
│ RFC: DCO123456ABC                              │
├────────────────────────────────────────────────┤
│ Concepto              Cant.   Precio    Total  │
│ ─────────────────────────────────────────────  │
│ Plan Professional     1      $499.00   $499.00 │
│ (Ene 15 - Feb 14)                              │
│ Usuarios adicionales  2       $50.00   $100.00 │
│ Descuento PROMO20    -1       20%      -$119.80│
├────────────────────────────────────────────────┤
│                      Subtotal:         $479.20 │
│                      IVA 16%:           $76.67 │
│                      TOTAL:            $555.87 │
├────────────────────────────────────────────────┤
│ UUID CFDI: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx│
└────────────────────────────────────────────────┘

Referencias

• RF-MGN-015-002 - Suscripciones
• RF-MGN-015-003 - Métodos de Pago
• Especificación CFDI 4.0 SAT

Notas Técnicas

• Tablas: billing.invoices, billing.invoice_lines, billing.payments
• Numeración: Serie + consecutivo (INV-2024-0001)
• CFDI: Integración con PAC (Facturama, SW Sapien, etc.)
• Gateway: Stripe para cobros, webhook para confirmaciones
• Jobs:
  • Generación de facturas (diario, 1 día antes de renovación)
  • Reintentos de cobro (días 1, 3, 7)
  • Envío de recordatorios (3 días antes de vencimiento)

Dependencias

• RF Requeridos:
  • RF-MGN-015-002 (Suscripciones)
  • RF-MGN-015-003 (Métodos de Pago)
• Bloqueante para: RF-MGN-015-005 (Registro de Uso)