trading-platform/docs/02-definicion-modulos/OQI-005-payments-stripe/requerimientos/RF-PAY-004-facturacion.md

id	title	type	status	priority	epic	project	version	created_date	updated_date
RF-PAY-004	Sistema de Facturacion Automatica	Requirement	Done	Alta	OQI-005	trading-platform	1.0.0	2025-12-05	2026-01-04

RF-PAY-004: Sistema de Facturación Automática

Version: 1.0.0 Fecha: 2025-12-05 Estado: 📋 Planificado Prioridad: P1 (Alta) Story Points: 5 Épica: OQI-005

---

Descripción

El sistema debe generar, almacenar y entregar facturas electrónicas automáticas para todos los pagos procesados, cumpliendo con requisitos fiscales de LATAM y permitiendo a usuarios descargar comprobantes en formato PDF.

---

Objetivo de Negocio

• Cumplir con obligaciones fiscales en cada país
• Reducir consultas de soporte por comprobantes
• Facilitar deducción de impuestos para empresas
• Mejorar profesionalismo y confianza de la plataforma
• Automatizar envío de facturas por email

---

Tipos de Facturas

Tipo	Descripción	Ejemplo
Recibo de Pago	Compra única (curso)	Invoice #INV-2025-001234
Factura de Suscripción	Cobro mensual recurrente	Invoice #SUB-2025-001234
Nota de Crédito	Reembolso parcial/total	Credit Note #CN-2025-001234

---

Requisitos Funcionales

RF-PAY-004.1: Generación Automática de Facturas

DEBE:

1. Generar factura inmediatamente después de pago exitoso
2. Asignar número de factura único secuencial
3. Incluir todos los datos fiscales requeridos
4. Generar PDF con diseño profesional
5. Almacenar PDF en S3/storage persistente

Trigger:

• Webhook invoice.payment_succeeded de Stripe
• Webhook payment_intent.succeeded para pagos únicos

RF-PAY-004.2: Contenido de Factura

DEBE incluir:

Información del Emisor:

• Razón Social: "Trading Platform Inc."
• RFC/Tax ID: XX-XXXXXXX-XX
• Dirección fiscal completa
• Email de contacto: billing@trading.com

Información del Cliente:

• Nombre completo
• Email
• País/Región
• RFC/Tax ID (si lo proporcionó)
• Dirección de facturación (si la proporcionó)

Detalles de la Transacción:

• Número de factura único
• Fecha de emisión
• Descripción del producto/servicio
• Cantidad
• Precio unitario
• Subtotal
• Impuestos (IVA/VAT si aplica)
• Total
• Método de pago (últimos 4 dígitos de tarjeta)

Footer:

• "Powered by Stripe"
• Políticas de reembolso
• Contacto de soporte

RF-PAY-004.3: Numeración de Facturas

DEBE:

1. Formato: {PREFIX}-{YEAR}-{SEQUENCE}
   • INV-2025-000001 (pago único)
   • SUB-2025-000001 (suscripción)
   • CN-2025-000001 (nota de crédito)
2. Secuencia separada por tipo
3. Reiniciar secuencia cada año
4. Incremento atómico para evitar duplicados

Implementación:

async function generateInvoiceNumber(type: InvoiceType): Promise<string> {
  const year = new Date().getFullYear();
  const prefix = type === 'subscription' ? 'SUB' :
                 type === 'credit_note' ? 'CN' : 'INV';

  const sequence = await db.invoiceSequence.increment({
    where: { prefix, year },
    field: 'current',
  });

  return `${prefix}-${year}-${sequence.toString().padStart(6, '0')}`;
}
// Ejemplo: INV-2025-000042

RF-PAY-004.4: Generación de PDF

DEBE:

1. Usar librería de generación de PDF (puppeteer, pdfkit, react-pdf)
2. Aplicar diseño responsive (A4)
3. Incluir logo de Trading Platform
4. Soportar múltiples idiomas (ES, EN)
5. Tamaño máximo: 1 MB

Diseño:

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  [Logo Trading Platform]              FACTURA / INVOICE       │
│                                                         │
│  Trading Platform Inc.                  #INV-2025-000042   │
│  1234 Tech Street                   Fecha: 05/12/2025  │
│  San Francisco, CA 94105                                │
│  RFC: XX-XXXXXXX-XX                                     │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  FACTURADO A:                                           │
│  Juan Pérez                                             │
│  juan.perez@example.com                                 │
│  México                                                 │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  DESCRIPCIÓN              CANT.   PRECIO    TOTAL       │
│  ─────────────────────────────────────────────────      │
│  Suscripción Pro          1      $49.00    $49.00      │
│  (01/01/2025 - 31/01/2025)                              │
│                                                         │
│                                          SUBTOTAL: $49.00│
│                                          IVA (16%): $7.84│
│                                          ───────────────│
│                                          TOTAL:   $56.84│
│                                                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  MÉTODO DE PAGO:                                        │
│  Visa •••• 4242                                         │
│                                                         │
│  Powered by Stripe | ID: pi_3Abc123...                 │
│                                                         │
│  Dudas: support@trading.com                           │
│                                                         │
└─────────────────────────────────────────────────────────┘

RF-PAY-004.5: Almacenamiento de Facturas

DEBE:

1. Guardar PDF en S3 bucket: invoices/{year}/{month}/{invoiceId}.pdf
2. Registrar metadata en tabla billing.invoices
3. Generar URL firmada con expiración de 24h para descarga
4. Mantener facturas por mínimo 7 años (requisito fiscal)

Modelo de datos:

@Entity({ name: 'invoices', schema: 'billing' })
class Invoice {
  id: string;                    // UUID
  userId: string;                // FK a users
  invoiceNumber: string;         // INV-2025-000042 (UNIQUE)
  type: InvoiceType;             // payment | subscription | credit_note
  status: InvoiceStatus;         // draft | issued | paid | void
  paymentId?: string;            // FK a payments
  subscriptionId?: string;       // FK a subscriptions
  stripeInvoiceId?: string;      // Stripe Invoice ID
  pdfUrl: string;                // S3 URL
  amount: Decimal;               // Monto total
  currency: string;              // USD
  taxAmount?: Decimal;           // IVA/VAT
  issuedAt: Date;                // Fecha de emisión
  dueAt?: Date;                  // Fecha de vencimiento
  paidAt?: Date;                 // Fecha de pago
  customerName: string;
  customerEmail: string;
  customerTaxId?: string;        // RFC/CUIT/RUT
  metadata?: object;
  createdAt: Date;
  updatedAt: Date;
}

RF-PAY-004.6: Envío Automático por Email

DEBE:

1. Enviar email inmediatamente después de generar factura
2. Adjuntar PDF de la factura
3. Incluir link de descarga (URL firmada)
4. Asunto personalizado por idioma
5. Tracking de apertura y descarga

Template de Email:

Asunto: Tu factura de Trading Platform - #INV-2025-000042

Hola Juan,

Gracias por tu pago de $49.00 USD.

Tu factura está adjunta a este email. También puedes descargarla desde:
[Descargar Factura] (válido por 24 horas)

Detalles de la compra:
- Producto: Suscripción Pro
- Período: 01/01/2025 - 31/01/2025
- Total: $49.00 USD

¿Preguntas? Escríbenos a support@trading.com

Saludos,
El equipo de Trading Platform

RF-PAY-004.7: Actualización de Datos Fiscales

DEBE:

1. Permitir al usuario agregar/editar:
   • Nombre fiscal (puede diferir de nombre de usuario)
   • RFC/Tax ID
   • Dirección fiscal completa
   • Régimen fiscal (si aplica)
2. Validar formato de RFC según país
3. Aplicar datos fiscales a futuras facturas (no retroactivo)
4. Mostrar advertencia si falta información fiscal

RF-PAY-004.8: Notas de Crédito (Reembolsos)

DEBE:

1. Generar nota de crédito automáticamente al procesar reembolso
2. Referenciar factura original
3. Formato: CN-2025-000001
4. Incluir monto original y monto reembolsado
5. Enviar por email junto con confirmación de reembolso

---

Flujo de Generación de Factura

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Stripe    │     │   Backend   │     │   S3/Store  │     │   Usuario   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ Webhook: invoice. │                   │                   │
       │ payment_succeeded │                   │                   │
       │──────────────────▶│                   │                   │
       │                   │                   │                   │
       │                   │ 1. Fetch payment  │                   │
       │                   │    & user data    │                   │
       │                   │                   │                   │
       │                   │ 2. Generate       │                   │
       │                   │    invoice number │                   │
       │                   │    (INV-2025-042) │                   │
       │                   │                   │                   │
       │                   │ 3. Render PDF     │                   │
       │                   │    from template  │                   │
       │                   │                   │                   │
       │                   │                   │ 4. Upload PDF     │
       │                   │──────────────────▶│                   │
       │                   │◀──────────────────│                   │
       │                   │ { url }           │                   │
       │                   │                   │                   │
       │                   │ 5. Save invoice   │                   │
       │                   │    to DB          │                   │
       │                   │                   │                   │
       │                   │ 6. Send email     │                   │
       │                   │    with PDF       │                   │
       │                   │──────────────────────────────────────▶│
       │                   │                   │                   │
       │                   │                   │                   │

---

Reglas de Negocio

RN-001: Generación Obligatoria

SIEMPRE generar factura para:

• Compra de curso > $0
• Cobro de suscripción mensual
• Recarga de wallet > $10
• Reembolso (nota de crédito)

NO generar para:

• Pagos fallidos
• Suscripciones en trial (hasta que se cobre)
• Créditos promocionales gratuitos

RN-002: Impuestos (IVA/VAT)

País	IVA	Nota
México	16%	Solo si cliente tiene RFC
Colombia	19%	Siempre aplicar
Argentina	21%	Siempre aplicar
Chile	19%	Siempre aplicar
USA	0%	No hay VAT federal
EU	Variable	Según país del cliente

Stripe Tax puede calcular automáticamente si se habilita.

RN-003: Idioma de Factura

• Detectar idioma según user.preferredLanguage
• Fallback a inglés si no hay traducción
• Soportar: ES, EN, PT (futuro)

RN-004: Modificación de Facturas

• Facturas emitidas NO se pueden editar
• Si hay error, emitir nota de crédito y nueva factura
• Mantener trazabilidad completa

---

Cumplimiento Fiscal

México (SAT)

• Usar CFDI 4.0 para facturación formal (futuro)
• Por ahora, factura simplificada es suficiente
• Incluir RFC en formato: AAAA######XXX

Colombia (DIAN)

• Incluir NIT del cliente
• IVA del 19% obligatorio
• Resolución de facturación (futuro)

Argentina (AFIP)

• Incluir CUIT del cliente
• IVA del 21%
• Factura electrónica (futuro)

---

Seguridad

Acceso a Facturas

• Solo el usuario propietario puede descargar su factura
• URLs firmadas con expiración de 24h
• Logs de acceso a facturas

Datos Sensibles

• NO incluir número completo de tarjeta (solo last4)
• Encriptar Tax IDs en BD
• Cumplir GDPR/CCPA en retención de datos

---

Configuración Requerida

# Storage
AWS_S3_BUCKET=trading-invoices
AWS_S3_REGION=us-east-1
INVOICE_PDF_RETENTION_YEARS=7

# Facturación
COMPANY_LEGAL_NAME="Trading Platform Inc."
COMPANY_TAX_ID=XX-XXXXXXX-XX
COMPANY_ADDRESS="1234 Tech Street, San Francisco, CA 94105"
COMPANY_EMAIL=billing@trading.com

# Email
INVOICE_FROM_EMAIL=billing@trading.com
INVOICE_REPLY_TO=support@trading.com

---

Webhooks Relacionados

Evento	Acción
invoice.payment_succeeded	Generar factura de suscripción
payment_intent.succeeded	Generar factura de pago único
charge.refunded	Generar nota de crédito

---

Manejo de Errores

Error	Código	Acción
Fallo en generación de PDF	500	Retry 3 veces, alertar dev
Fallo en upload a S3	500	Guardar PDF temporalmente, retry
Email bounce	400	Guardar factura, notificar usuario en app
Datos fiscales incompletos	400	Generar con datos disponibles

---

Métricas de Negocio

• Total de facturas emitidas/mes
• Tasa de descarga de facturas
• Tiempo promedio de generación de PDF
• Facturas con datos fiscales completos vs incompletos

---

Criterios de Aceptación

• Factura se genera automáticamente después de pago exitoso
• PDF incluye todos los datos fiscales requeridos
• Número de factura es único y secuencial
• PDF se almacena en S3 correctamente
• Email con factura se envía inmediatamente
• Usuario puede descargar factura desde dashboard
• URL de descarga expira después de 24h
• Nota de crédito se genera para reembolsos
• Usuario puede actualizar datos fiscales en perfil
• Impuestos se calculan correctamente según país

---

Especificación Técnica Relacionada

• ET-PAY-004: Invoice Generation

Historias de Usuario Relacionadas

• US-PAY-007: Ver Facturas
• US-PAY-002: Suscribirse a Plan