---
id: "US-PAY-007"
title: "Ver y Descargar Facturas"
type: "User Story"
status: "Done"
priority: "Media"
epic: "OQI-005"
project: "trading-platform"
story_points: 3
created_date: "2025-12-05"
updated_date: "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](../_MAP.md)

---

## Historia de Usuario

**Como** usuario de Trading Platform 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: `Trading Platform_Factura_INV-2025-000042.pdf`
- PDF contiene:
  - Logo de Trading Platform
  - 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 Trading Platform - #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)

```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 "Trading Platform_Factura_INV-2025-000042.pdf"
    And el PDF debería contener mis datos fiscales
    And el PDF debería tener logo de Trading Platform
    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:
   ```json
   {
     "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: `trading-invoices`
- Path: `invoices/{year}/{month}/{invoiceId}.pdf`
- Generar URL firmada con expiración:
```typescript
const url = s3.getSignedUrl('getObject', {
  Bucket: 'trading-invoices',
  Key: `invoices/2025/12/${invoiceId}.pdf`,
  Expires: 86400, // 24 horas
});
```

### Email Template

**Subject:** Tu factura de Trading Platform - #INV-2025-000042

```
Hola Juan,

Adjuntamos tu factura de Trading Platform.

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@trading.com

Saludos,
El equipo de Trading Platform
```

---

## Dependencias

- [RF-PAY-004: Sistema de Facturación](../requerimientos/RF-PAY-004-facturacion.md)
- Sistema de generación de PDF
- AWS S3 para almacenamiento

---

## Requerimientos Relacionados

- [RF-PAY-004: Sistema de Facturación Automática](../requerimientos/RF-PAY-004-facturacion.md)

---

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