trading-platform/docs/02-definicion-modulos/OQI-005-payments-stripe/historias-usuario/US-PAY-007-ver-facturas.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-PAY-007	Ver y Descargar Facturas	User Story	Done	Media	OQI-005	trading-platform	3	2025-12-05	2026-01-04

US-PAY-007: Ver y Descargar Facturas

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

---

Historia de Usuario

Como usuario de OrbiQuant que ha realizado pagos Quiero ver y descargar mis facturas Para tener comprobantes de mis transacciones y poder deducir impuestos

---

Criterios de Aceptación

AC-001: Acceder a Facturas

Dado que soy usuario logueado con historial de pagos Cuando navego a "Configuración → Facturas" Entonces debería ver:

• Lista de todas mis facturas ordenadas por fecha (más reciente primero)
• Para cada factura:
  • Número de factura (ej: INV-2025-000042)
  • Fecha de emisión
  • Descripción (Suscripción Pro, Curso Trading Básico, etc.)
  • Monto total
  • Estado (Pagada, Pendiente, Reembolsada)
  • Botón "Descargar PDF"
  • Botón "Ver Detalles"
• Filtros: Por año, por tipo (suscripción/curso), por estado
• Paginación si tengo > 20 facturas

AC-002: Ver Sin Facturas

Dado que soy usuario nuevo sin pagos realizados Cuando navego a la sección de facturas Entonces debería ver:

• Mensaje: "No tienes facturas todavía"
• Ilustración o ícono de facturas vacías
• Botón "Ver Planes" para incentivar compra

AC-003: Descargar Factura PDF

Dado que tengo una factura pagada Cuando hago click en "Descargar PDF" Entonces debería:

• Descargar archivo PDF inmediatamente
• Nombre del archivo: OrbiQuant_Factura_INV-2025-000042.pdf
• PDF contiene:
  • Logo de OrbiQuant
  • Datos fiscales de empresa
  • Mis datos (nombre, email, país)
  • Número de factura y fecha
  • Detalle de productos/servicios
  • Subtotal, impuestos (si aplica), total
  • Método de pago (últimos 4 dígitos)
  • Footer: "Powered by Stripe"

AC-004: Ver Detalles de Factura

Dado que quiero ver más información de una factura Cuando hago click en "Ver Detalles" Entonces debería ver modal/página con:

• Todos los datos de la factura
• Desglose de impuestos si aplica
• ID de transacción de Stripe
• Método de pago usado
• Botón "Descargar PDF"
• Botón "Enviar por Email"

AC-005: Enviar Factura por Email

Dado que estoy viendo detalles de una factura Cuando hago click en "Enviar por Email" Entonces debería:

• Ver confirmación: "Factura enviada a juan@example.com"
• Recibir email con:
  • Asunto: "Tu factura de OrbiQuant - #INV-2025-000042"
  • PDF adjunto
  • Link de descarga (válido 24h)

AC-006: Filtrar Facturas

Dado que tengo múltiples facturas Cuando aplico filtros Entonces debería poder filtrar por:

• Año: 2025, 2024, 2023, etc.
• Tipo: Suscripción, Curso, Recarga de Wallet
• Estado: Pagada, Reembolsada
• Resultados se actualizan inmediatamente

AC-007: Buscar Factura

Dado que estoy en la página de facturas Cuando ingreso número de factura en búsqueda (ej: "INV-2025-042") Entonces debería:

• Ver solo facturas que coincidan con el criterio
• Resaltar número coincidente
• Mensaje "No se encontraron facturas" si no hay resultados

AC-008: Factura de Suscripción Mensual

Dado que tengo suscripción activa Cuando veo mis facturas Entonces debería ver:

• Una factura por cada cobro mensual
• Número secuencial: SUB-2025-000001, SUB-2025-000002, etc.
• Descripción: "Suscripción Pro - Enero 2025"
• Período cubierto: "01/01/2025 - 31/01/2025"

AC-009: Nota de Crédito (Reembolso)

Dado que recibí un reembolso Cuando veo mis facturas Entonces debería ver:

• Nota de crédito con número CN-2025-000001
• Estado: "Reembolsada"
• Referencia a factura original
• Monto negativo (-$29.00)
• Ambas facturas (original + nota de crédito) listadas

AC-010: Actualizar Datos Fiscales

Dado que quiero facturas con datos fiscales correctos Cuando navego a "Datos Fiscales" en configuración Entonces debería poder agregar/editar:

• Nombre fiscal (si difiere de nombre de usuario)
• RFC/Tax ID
• Dirección fiscal completa
• Régimen fiscal (si aplica)
• Nota: "Estos datos se aplicarán a facturas futuras"

---

Mockup

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                         Facturas                            │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Filtros:  [2025 ▼]  [Todos ▼]  [Buscar: INV-2025-...]     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ INV-2025-000042              05/12/2025    Pagada   │   │
│  │ Suscripción Pro - Diciembre 2025                    │   │
│  │                                            $49.00   │   │
│  │                                                     │   │
│  │ [Descargar PDF]  [Ver Detalles]                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ INV-2025-000038              28/11/2025    Pagada   │   │
│  │ Curso: Trading Básico 101                           │   │
│  │                                            $29.00   │   │
│  │                                                     │   │
│  │ [Descargar PDF]  [Ver Detalles]                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ SUB-2025-000015              05/11/2025    Pagada   │   │
│  │ Suscripción Pro - Noviembre 2025                    │   │
│  │                                            $49.00   │   │
│  │                                                     │   │
│  │ [Descargar PDF]  [Ver Detalles]                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ CN-2025-000003               15/10/2025  Reembolsada│   │
│  │ Nota de Crédito: Curso Trading Avanzado            │   │
│  │ (Ref: INV-2025-000025)                   -$49.00   │   │
│  │                                                     │   │
│  │ [Descargar PDF]  [Ver Detalles]                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Mostrando 1-10 de 24 facturas                              │
│  [← Anterior]  [1] [2] [3]  [Siguiente →]                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘


───────────── Modal: Detalles de Factura ─────────────

┌─────────────────────────────────────────────────────────────┐
│                                                      [X]    │
│              Factura #INV-2025-000042                       │
│                                                             │
│  Fecha de emisión: 05/12/2025                               │
│  Estado: Pagada                                             │
│                                                             │
│  ───────────────────────────────────────────────────        │
│                                                             │
│  FACTURADO A:                                               │
│  Juan Pérez                                                 │
│  juan.perez@example.com                                     │
│  México                                                     │
│                                                             │
│  ───────────────────────────────────────────────────        │
│                                                             │
│  DESCRIPCIÓN                         PRECIO                │
│  Suscripción Pro                                            │
│  Período: 01/12/2025 - 31/12/2025    $49.00                │
│                                                             │
│                                      SUBTOTAL:   $49.00    │
│                                      IVA (16%):   $7.84    │
│                                      ─────────────────      │
│                                      TOTAL:      $56.84    │
│                                                             │
│  ───────────────────────────────────────────────────        │
│                                                             │
│  MÉTODO DE PAGO:                                            │
│  Visa •••• 4242                                             │
│                                                             │
│  ID de transacción: pi_3Abc123...                          │
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ Descargar PDF   │  │ Enviar por Email│                  │
│  └─────────────────┘  └─────────────────┘                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Flujo de Usuario (Gherkin)

Feature: Ver y Descargar Facturas

  Scenario: Ver lista de facturas
    Given que soy usuario logueado "juan@example.com"
    And he realizado 3 compras en el último mes
    When navego a "Configuración → Facturas"
    Then debería ver 3 facturas listadas
    And deberían estar ordenadas por fecha descendente
    And cada una debería tener botón "Descargar PDF"

  Scenario: Descargar factura PDF
    Given que estoy viendo mi lista de facturas
    When hago click en "Descargar PDF" en factura "INV-2025-000042"
    Then debería descargar archivo "OrbiQuant_Factura_INV-2025-000042.pdf"
    And el PDF debería contener mis datos fiscales
    And el PDF debería tener logo de OrbiQuant
    And el PDF debería mostrar total de $56.84 (incluido IVA)

  Scenario: Ver detalles de factura
    Given que estoy viendo mi lista de facturas
    When hago click en "Ver Detalles" en una factura
    Then debería ver modal con información detallada
    And debería ver desglose de impuestos
    And debería ver método de pago usado
    And debería ver ID de transacción de Stripe

  Scenario: Enviar factura por email
    Given que estoy viendo detalles de factura "INV-2025-000042"
    When hago click en "Enviar por Email"
    Then debería ver "Factura enviada a juan@example.com"
    And debería recibir email con PDF adjunto
    And email debería incluir link de descarga válido 24h

  Scenario: Filtrar facturas por año
    Given que tengo facturas de 2024 y 2025
    When selecciono filtro "2025"
    Then debería ver solo facturas de 2025
    And no debería ver facturas de 2024

  Scenario: Usuario sin facturas
    Given que soy usuario nuevo sin pagos
    When navego a "Configuración → Facturas"
    Then debería ver "No tienes facturas todavía"
    And debería ver botón "Ver Planes"

---

Notas Técnicas

Frontend

• Componente: apps/frontend/src/pages/Settings/Invoices.tsx
• Modal: InvoiceDetailsModal.tsx
• Fetch facturas: GET /api/v1/payments/invoices
• Descargar PDF: GET /api/v1/payments/invoices/:id/pdf

Backend

Endpoints:

1. GET /api/v1/payments/invoices

   • Query params: ?year=2025&type=subscription&status=paid
   • Response:

   {
     "invoices": [
       {
         "id": "uuid",
         "invoiceNumber": "INV-2025-000042",
         "type": "subscription",
         "status": "paid",
         "amount": 49.00,
         "taxAmount": 7.84,
         "total": 56.84,
         "currency": "USD",
         "description": "Suscripción Pro - Diciembre 2025",
         "issuedAt": "2025-12-05T00:00:00Z",
         "pdfUrl": "https://s3.../invoices/2025/12/uuid.pdf"
       }
     ],
     "total": 24,
     "page": 1,
     "perPage": 10
   }
   

2. GET /api/v1/payments/invoices/:id

   • Detalles completos de factura

3. GET /api/v1/payments/invoices/:id/pdf

   • Generar URL firmada de S3 (expiración 24h)
   • Redirect a URL firmada

4. POST /api/v1/payments/invoices/:id/email

   • Reenviar factura por email

Database

• Query desde tabla billing.invoices
• JOIN con billing.payments para método de pago
• Filtrar por userId del token

PDF Storage

• S3 Bucket: orbiquant-invoices
• Path: invoices/{year}/{month}/{invoiceId}.pdf
• Generar URL firmada con expiración:

const url = s3.getSignedUrl('getObject', {
  Bucket: 'orbiquant-invoices',
  Key: `invoices/2025/12/${invoiceId}.pdf`,
  Expires: 86400, // 24 horas
});

Email Template

Subject: Tu factura de OrbiQuant - #INV-2025-000042

Hola Juan,

Adjuntamos tu factura de OrbiQuant.

Número de factura: INV-2025-000042
Fecha: 05/12/2025
Total: $56.84 USD

También puedes descargarla desde:
[Descargar Factura] (válido por 24 horas)

¿Necesitas ayuda? Escríbenos a billing@orbiquant.com

Saludos,
El equipo de OrbiQuant

---

Dependencias

• RF-PAY-004: Sistema de Facturación
• Sistema de generación de PDF
• AWS S3 para almacenamiento

---

Requerimientos Relacionados

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

---

Tareas Técnicas

Frontend

• Página Invoices.tsx con lista
• Modal InvoiceDetailsModal.tsx
• Filtros (año, tipo, estado)
• Búsqueda por número de factura
• Paginación
• Descargar PDF con loading state
• Reenviar email con confirmación

Backend

• Endpoint GET /invoices con filtros
• Endpoint GET /invoices/:id
• Endpoint GET /invoices/:id/pdf (URL firmada)
• Endpoint POST /invoices/:id/email
• Validar que usuario sea dueño de factura
• Generar URLs firmadas de S3

Testing

• Test: Usuario ve sus facturas correctamente
• Test: Filtros funcionan
• Test: Descargar PDF genera URL firmada
• Test: No puede ver facturas de otros usuarios
• Test: Reenvío de email funciona
• Test: Usuario sin facturas ve mensaje apropiado