# 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](./RF-MGN-015-002-gestion-suscripciones-tenant.md) - Suscripciones
- [RF-MGN-015-003](./RF-MGN-015-003-metodos-pago.md) - Métodos de Pago
- [Especificación CFDI 4.0 SAT](http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm)

## 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)