Listado de Saldos - Exportación Excel

Módulo: Cuenta Corriente Tipo: Feature Estado: ✅ Implementado Código reporte: 0002Fecha actualización: 2025-12-23 Versión: 1.0

---

Descripción

Agregar exportación Excel al Listado de Saldos de clientes. Este informe muestra el saldo de cuenta corriente de cada cliente a una fecha determinada, con desglose de información adicional incluyendo CUIT, condición de IVA, y vendedor asignado.

El usuario puede elegir entre PDF o Excel usando el parámetro formato en el request.

---

Estructura Excel

Columnas fijas

Columna	Descripción	Tipo filtro	Tipo dato	Ancho sugerido
Código	Código del cliente	null	null	10
Cliente	Nombre del cliente	null	null	40
CUIT	CUIT del cliente	null	texto	15
Cond. IVA	Condición de IVA	null	null	20
Vendedor	Vendedor asignado	null	null	25
Cartera	Cartera del cliente	null	null	20
Fecha	Última fecha de movimiento	null	null	12
Último Pago	Fecha del último recibo	null	null	12
Teléfono	Teléfono del cliente	null	null	15
Saldo	Saldo de cuenta corriente	null	null	15

Nota: La columna Cartera solo aparece si hay carteras seleccionadas en el request.

Ejemplo de salida

| Código | Cliente           | CUIT          | Cond. IVA    | Vendedor    | Fecha      | Último Pago | Teléfono    | Saldo     |
|--------|-------------------|---------------|--------------|-------------|------------|-------------|-------------|-----------|
| 001    | Cliente ABC SA    | 30-12345678-9 | Resp. Inscr. | Juan Pérez  | 2025-12-15 | 2025-12-10  | 11-2234-5678| 15000.00  |
| 002    | Empresa XYZ SRL   | 30-87654321-0 | Resp. Inscr. | María López | 2025-12-20 | 2025-12-18  | 11-5555-6666| 8500.00   |
| 003    | Consumidor Final  | 20-11111111-1 | Cons. Final  | Juan Pérez  | 2025-12-10 | null        | null        | 2300.00   |
| **TOTAL GENERAL** | | | | | | | | **25800.00** |

Nota: La fila de total está en negrita y las primeras celdas están unidas para mayor claridad visual.

---

Mapeo de datos

Estrategia

1. Obtener saldos: Ejecutar consulta de saldos de clientes a la fecha especificada
2. Enriquecer datos: Agregar información de CUIT, Cond. IVA, y Vendedor desde tablas relacionadas
3. Ordenar: Aplicar ordenamiento según parámetro (código/nombre/monto/fecha)
4. Agrupar: Opcional, agrupar por cartera si se especifica
5. Mapear filas: Crear estructura plana de datos para Excel
6. Fila de total: Agregar última fila con suma de saldos

Filtros aplicados

• Fecha hasta: Solo incluye movimientos hasta la fecha especificada
• Rango de clientes: Filtra por rango de códigos de cliente (desde/hasta)
• Clientes específicos: Si se especifican clientes, solo muestra esos
• Carteras: Si se especifican, filtra por carteras seleccionadas
• Saldos mínimos: Solo muestra clientes con saldo mayor al especificado

Campos enriquecidos

Campo	Origen	Descripción
CUIT	ordcon.ccui::text	CUIT del cliente, convertido a texto
Condición IVA	ordiva.ides (vía ordcon.civa)	Descripción de la condición de IVA
Vendedor	ordven.vnom (vía ordcon.cven)	Nombre del vendedor asignado
Cartera	ordcon.ccar	Cartera del cliente (opcional)

---

Consideraciones técnicas

Archivos creados

• reports/mod-ctacte/listado-saldos-datos.php - Extracción y estructura de datos
• reports/mod-ctacte/listado-saldos-render.php - Renderizado HTML para PDF

Archivos modificados

• index.php - Case 0002: Bifurcación Excel/PDF
• util/excel.php - Función crearExcel(): Detección de fila de total y aplicación de estilos

Patrones utilizados

Separación datos/render: Los datos se extraen en listado-saldos-datos.php independientemente del formato de salida. Luego se bifurca:

• Excel: Mapea datos a estructura de arrays simple
• PDF: Incluye template de renderizado HTML

Enriquecimiento de datos: Se obtienen consultas relacionadas (ordiva, ordven) y se mapean en memoria para evitar queries N+1.

Defaults automáticos: Si no viene tipo_cuenta en el request, usa Cliente (Deudor) por defecto.

---

Parámetros del request

{
  "codReporte": 2,
  "modo": 1,
  "formato": "excel",
  "fechaHasta": "2025-12-23",
  "clienteDesde": {
    "id": 1,
    "nombre": "Consumidor Final"
  },
  "clienteHasta": {
    "id": 9,
    "nombre": "aaaaa"
  },
  "clientesPorSeleccion": [],
  "carterasPorSeleccion": [],
  "saldosMayores": -999999999,
  "ordenamiento": 1,
  "nombre_mulcta": "Cliente",
  "tipo_cuenta": {
    "tabla_movimientos": "ordcta",
    "tabla_cliente": "ordcon",
    "campo_codigo": "cnro",
    "campo_nombre": "cnom",
    "tipo": "D",
    "nombre": "Cliente"
  }
}

Parámetros principales

Parámetro	Tipo	Descripción
codReporte	int	2 para Listado de Saldos
modo	int	0=Prueba, 1=Oficial, 2=Consolidado
formato	string	"excel" o "pdf" (default: pdf)
fechaHasta	string	Fecha de corte (YYYY-MM-DD)
clienteDesde	object	Cliente inicial del rango
clienteHasta	object	Cliente final del rango
ordenamiento	int	1=Código, 2=Nombre, 3=Monto, 4=Fecha
carterasPorSeleccion	array	Array de carteras a filtrar (vacío = todas)
saldosMayores	number	Saldo mínimo a mostrar

---

Diferencias PDF vs Excel

Aspecto	PDF	Excel
Paginación	40 filas/página	Sin límite, todas las filas
Agrupación cartera	Encabezados + subtotales por página	Solo columna "Cartera"
Subtotales	Subtotal página + Total cartera + Total general	Solo Total general
Formato total	Texto HTML formateado	Fila con negrita y celdas unidas
Autofiltros	No	Sí, en todas las columnas

---

Criterios de aceptación

• [x] El Excel contiene todos los clientes con saldo en el período
• [x] El total general es correcto (suma de todos los saldos)
• [x] Los filtros (fecha, rango, saldos mínimos) funcionan igual que en PDF
• [x] Los campos CUIT, Cond. IVA y Vendedor se muestran correctamente
• [x] La columna Cartera aparece solo si hay carteras seleccionadas
• [x] El ordenamiento se aplica correctamente (código/nombre/monto/fecha)
• [x] El Excel tiene autofiltros en todas las columnas
• [x] La fila de total tiene formato especial (negrita, celdas unidas)
• [x] El CUIT se guarda como texto (no se pierden los ceros a la izquierda)
• [x] El PDF sigue funcionando como antes (sin cambios en formato o datos)
• [x] Ambos formatos (PDF y Excel) muestran exactamente los mismos datos

---

Ejemplo de uso desde Postman

Método: POST URL: http://tu-servidor/informes/index.php

Headers:

Content-Type: application/json
Authorization: Bearer {JWT_TOKEN}
X-Schema: {SCHEMA}

Body (Excel):

{
  "codReporte": 2,
  "modo": 1,
  "formato": "excel",
  "fechaHasta": "2025-12-23",
  "clienteDesde": {"id": 1, "nombre": "Inicio"},
  "clienteHasta": {"id": 999, "nombre": "Fin"},
  "clientesPorSeleccion": [],
  "carterasPorSeleccion": [],
  "saldosMayores": 0,
  "ordenamiento": 1,
  "nombre_mulcta": "Cliente"
}

Body (PDF):

{
  "codReporte": 2,
  "modo": 1,
  "fechaHasta": "2025-12-23",
  "clienteDesde": {"id": 1, "nombre": "Inicio"},
  "clienteHasta": {"id": 999, "nombre": "Fin"},
  "clientesPorSeleccion": [],
  "carterasPorSeleccion": [],
  "saldosMayores": 0,
  "ordenamiento": 1,
  "nombre_mulcta": "Cliente"
}

---

Historial de cambios

Fecha	Versión	Descripción
2025-12-23	1.0	Implementación completa: separación datos/render, bifurcación Excel/PDF, enriquecimiento de datos (CUIT, IVA, Vendedor)

---

Referencias

• Guía de exportación Excel - Proceso General
• Funciones helper Excel
• Subdiario de Compras - Patrón similar
• Arquitectura de Informes