Reportes

Prefijo: /api/reportes
Requiere Auth: Sí
Permiso requerido: reportes, *

Módulo de reportes para análisis financiero y operativo. Retorna datos agregados y crudos listos para dashboards, exportaciones Excel/PDF y conciliaciones contables. Todos los endpoints filtran automáticamente por tenant_id del usuario autenticado.

GET `/api/reportes/ventas` `[NUEVO]`

Descripción: Reporte general de todas las ventas del tenant con información de IVA/INC calculada por detalle. Agrupa por venta y suma impuestos. Ideal para dashboard de ventas totales y exportación contable mensual.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno (filtra por tenant_id del JWT)

Comportamiento / Casos de uso:

Dashboard principal: “Ventas totales del mes” con desglose de impuestos
Exportación contable: base imponible, IVA, INC por venta
Conciliación: cruza con ventas-iva e ventas-inc para validar totales

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "cliente": "Cliente Ejemplo",
    "vendedor": "Juan Pérez",
    "total": 10000,
    "montoRecibido": 12000,
    "vueltos": 2000,
    "descuento": 0,
    "totalf": "10000",
    "tipo_consumo": "SITIO",
    "medioPago": "Efectivo",
    "tipoPago": "CONTADO",
    "fecha": "2025-01-15",
    "hora": "14:30:00",
    "tipo_impuesto": "IVA",
    "codigo_impuesto": "01",
    "valor_impuesto": 1900.0,
    "valor_base": 8100.0
  }
]

Errores:

Código	Causa	Solución
401	Token inválido/expirado	Re-login
403	Sin permiso `reportes, leer`	Solicitar a admin

cURL:

curl "http://localhost/api/reportes/ventas" -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/reportes/ventas", headers={"Authorization": f"Bearer :token"})
ventas = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/reportes/ventas', {
  headers: {'Authorization': `Bearer $:token`}
});
const ventas = await resp.json();

GET `/api/reportes/ventas-inc` `[NUEVO]`

Descripción: Reporte de ventas con impuesto INC (Impuesto Nacional al Consumo). Filtra solo tipo_consumo = 'SITIO' y suma valor_impuesto donde tipo_impuesto = 'INC'. Requerido para declaración de impuestos al consumo en Colombia.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Declaración mensual de Impuesto al Consumo (Formulario 110)
Solo ventas en sitio (restaurante, bar) — excluye llevar/domicilio
Base para cálculo de retención en la fuente si aplica

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "cliente": "Cliente Ejemplo",
    "vendedor": "Juan Pérez",
    "subtotal": 8100,
    "valor_inc": 810.0,
    "total": "10000",
    "tipo_consumo": "SITIO",
    "medioPago": "Efectivo",
    "tipoPago": "CONTADO",
    "fecha": "2025-01-15",
    "hora": "14:30:00"
  }
]

Errores: 401, 403 (igual que /ventas)

cURL:

curl "http://localhost/api/reportes/ventas-inc" -H "Authorization: Bearer <token>"

GET `/api/reportes/ventas-iva` `[NUEVO]`

Descripción: Reporte de ventas con IVA. Filtra solo tipo_consumo = 'LLEVAR' y usa campos directos de la venta (valor_iva, totalf). Para ventas para llevar/domicilio donde el IVA se calcula en cabecera, no en detalle.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Declaración IVA bimestral (Formulario 300)
Ventas para llevar/domicilio — el IVA viene en venta.valor_iva
Complementa ventas-inc para cobertura 100% de ventas

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "cliente": "Cliente Ejemplo",
    "vendedor": "Juan Pérez",
    "subtotal": 8403,
    "valor_iva": 1597.0,
    "total": "10000",
    "tipo_consumo": "LLEVAR",
    "medioPago": "Transferencia",
    "tipoPago": "CONTADO",
    "fecha": "2025-01-15",
    "hora": "14:30:00"
  }
]

cURL:

curl "http://localhost/api/reportes/ventas-iva" -H "Authorization: Bearer <token>"

GET `/api/reportes/ventas-electronicas` `[NUEVO]`

Descripción: Reporte de facturación electrónica (DIAN). Solo ventas con tipoPago = 'Electronico'. Incluye CUFE, Número de Factura, IVA desglosado. Base para envío a contabilidad y validación de facturas emitidas.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Validar que todas las facturas electrónicas tengan CUFE y NumeroFact
Conciliar con portal DIAN: cruzar CUFE vs recibidos
Exportar para contador: cliente, fecha, CUFE, total, IVA

Respuesta exitosa: 200 OK

Response:

[
  {
    "cliente": "Empresa ABC S.A.S.",
    "vendedor": "Juan Pérez",
    "total": 500000,
    "totalf": "500000",
    "medioPago": "Transferencia",
    "iva_venta": 19.0,
    "valor_iva": 80000.0,
    "precio_iva": 580000.0,
    "NumeroFact": "SETP990000123",
    "cufe": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "fecha": "2025-01-15",
    "hora": "14:30:00"
  }
]

Errores: 401, 403

cURL:

curl "http://localhost/api/reportes/ventas-electronicas" -H "Authorization: Bearer <token>"

GET `/api/reportes/ventas-electronicas-mes-actual` `[NUEVO]`

Descripción: Igual a /ventas-electronicas pero filtrado al mes actual (desde día 1 hasta hoy). Útil para dashboard en tiempo real del mes en curso.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Dashboard gerencial: “Facturas electrónicas este mes”
Alertas: si count = 0 a mitad de mes, revisar conexión DIAN
Cierre preliminar antes de fin de mes

Respuesta exitosa: 200 OK (mismo schema que ventas-electronicas)

cURL:

curl "http://localhost/api/reportes/ventas-electronicas-mes-actual" -H "Authorization: Bearer <token>"

GET `/api/reportes/ventas-por-fecha` `[NUEVO]`

Descripción: Reporte de ventas de una fecha exacta (YYYY-MM-DD). Incluye monto recibido, descuentos, vueltos. Para cierre de caja diario y conciliación de arqueo.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
`fecha`	date	✅	Fecha a consultar	`2025-01-15`

Comportamiento / Casos de uso:

Cierre de caja: el cajero valida que su arqueo cuadra con este reporte
Conciliación diaria: admin revisa ventas del día anterior
Detección de anomalías: vueltos altos, descuentos inusuales

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "cliente": "Cliente Ejemplo",
    "vendedor": "Juan Pérez",
    "montoRecibido": 12000,
    "subtotal": 10000,
    "descuento": 0,
    "vueltos": 2000,
    "totalf": "10000",
    "medioPago": "Efectivo",
    "tipoPago": "CONTADO",
    "fecha": "2025-01-15",
    "hora": "14:30:00"
  }
]

Errores:

Código	Causa	Solución
400	Formato fecha inválido	Usar YYYY-MM-DD
401, 403	Auth/permiso	Ver arriba

cURL:

curl "http://localhost/api/reportes/ventas-por-fecha?fecha=2025-01-15" -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/reportes/ventas-por-fecha",
    params={"fecha": "2025-01-15"},
    headers={"Authorization": f"Bearer :token"})
ventas_dia = resp.json()

GET `/api/reportes/ventas-por-mes` `[NUEVO]`

Descripción: Reporte de ventas de un mes/año específico con IVA desglosado (iva_venta, valor_iva, precio_iva). Para declaraciones tributarias mensuales y análisis de tendencias.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción	Valores
`mes`	int	✅	Mes (1-12)	`1` = Enero
`anio`	int	✅	Año (4 dígitos)	`2025`

Comportamiento / Casos de uso:

Declaración IVA bimestral: agrupa 2 meses
Análisis estacional: comparar enero vs diciembre
Presupuesto: proyección basada en histórico mensual

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "cliente": "Cliente Ejemplo",
    "vendedor": "Juan Pérez",
    "subtotal": 8403,
    "iva_venta": 19.0,
    "valor_iva": 1597.0,
    "precio_iva": 10000.0,
    "montoRecibido": 12000,
    "vueltos": 2000,
    "descuento": 0,
    "totalf": "10000",
    "medioPago": "Efectivo",
    "tipoPago": "CONTADO",
    "fecha": "2025-01-15",
    "hora": "14:30:00"
  }
]

Errores:

Código	Causa	Solución
400	Mes fuera de rango (1-12) o año inválido	Validar params
401, 403	Auth/permiso	Ver arriba

cURL:

curl "http://localhost/api/reportes/ventas-por-mes?mes=1&anio=2025" -H "Authorization: Bearer <token>"

GET `/api/reportes/ventas-electronica-por-mes` `[NUEVO]`

Descripción: Reporte de facturación electrónica filtrado por mes/año. Mismo schema que ventas-electronicas pero con filtro temporal. Para auditoría DIAN por período.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción	Valores
`mes`	int	✅	Mes (1-12)	`1`
`anio`	int	✅	Año (4 dígitos)	`2025`

Comportamiento / Casos de uso:

Auditoría DIAN: “Todas las facturas de enero 2025”
Conciliación mensual contable
Verificar secuencia de numeración (no saltos en NumeroFact)

Respuesta exitosa: 200 OK (schema ReporteVentaElectronicaRow[])

cURL:

curl "http://localhost/api/reportes/ventas-electronica-por-mes?mes=1&anio=2025" -H "Authorization: Bearer <token>"

GET `/api/reportes/egresos` `[NUEVO]`

Descripción: Lista todos los egresos/gastos del tenant con detalle completo (categoría, descripción, método de pago, responsable, proveedor). Para control de gastos, presupuestos y deducibles de renta.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Control de gastos por categoría (servicios, insumos, nómina, etc.)
Gastos deducibles para renta: filtrar por tipo_movimiento = 'EGRESO'
Flujo de caja: cruzar con ventas para ver entrada vs salida

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "categoria": "Servicios Públicos",
    "descripcionPago": "Pago energía enero",
    "fechaPago": "2025-01-15",
    "metodoPago": "Transferencia",
    "montoPagado": 250000,
    "recibePago": "EPM",
    "responsablePago": "Juan Pérez"
  }
]

cURL:

curl "http://localhost/api/reportes/egresos" -H "Authorization: Bearer <token>"

GET `/api/reportes/productos` `[NUEVO]`

Descripción: Catálogo completo de productos con stock actual, precios, utilidad, proveedor y categoría. Incluye IVA calculado (valor_iva, precio_iva). Para inventario, lista de precios, reposición y análisis de rentabilidad.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Inventario físico: comparar stock real vs sistema
Lista de precios para vendedores (precio con IVA incluido)
Productos por agotar: filtrar stock < 10
Rentabilidad: utilidad = precio - precioC, margen = utilidad/precio

Respuesta exitosa: 200 OK

Response:

[
  {
    "codigo": "PROD001",
    "nombre": "Café Latte",
    "proveedor": "Café Colombia S.A.S.",
    "categoria": "Bebidas Calientes",
    "stock": 50.0,
    "precioC": 1500,
    "precio": 3500,
    "utilidad": 2000,
    "iva": 19.0,
    "valor_iva": 665.0,
    "precio_iva": 4165.0
  }
]

cURL:

curl "http://localhost/api/reportes/productos" -H "Authorization: Bearer <token>"

GET `/api/reportes/cierre` `[NUEVO]`

Descripción: Reporte de cierres de caja agregados con ventas del día. Une Caja + Venta por fecha. Muestra: base, gastos, cierre, efectivo, crédito, total, vueltos totales, dinero recibido total. Para conciliación de caja y detección de descuadres.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Conciliación diaria: ¿cuadre de caja? cierre - base - gastos = efectivo + credito + transferencia
Detección de hurtos/erres: dinero_recibido_total vs cierre
Reporte gerencial: evolución de efectivo vs crédito en el tiempo

Respuesta exitosa: 200 OK

Response:

[
  {
    "base": 500000,
    "gastos": 50000,
    "cierre": 1200000,
    "efectivo": 800000,
    "credito": 100000,
    "total": 1150000,
    "fecha": "2025-01-15",
    "vueltos_totales": 25000,
    "dinero_recibido_total": 1250000
  }
]

cURL:

curl "http://localhost/api/reportes/cierre" -H "Authorization: Bearer <token>"

GET `/api/reportes/detalle` `[NUEVO]`

Descripción: Detalle crudo de todas las líneas de venta (items) del tenant. Incluye código producto, cantidad, precio, venta padre y fecha. Para análisis de mix de productos, costo de mercancía vendida y auditoría de precios.
Requiere Auth: Sí
Permiso requerido: reportes, leer

Parámetros query: Ninguno

Comportamiento / Casos de uso:

Análisis ABC de productos: Top 20% que genera 80% ingresos
Costo de mercancía vendida (CMV): SUM(cantidad * precioC) por producto
Auditoría: detectar precios anómalos (precio = 0 o precio >> normal)
Exportación a BI (Power BI, Metabase) para dashboards avanzados

Respuesta exitosa: 200 OK

Response:

[
  {
    "cod_pro": "PROD001",
    "cantidad": 2.0,
    "tamano": "",
    "precio": 3500,
    "id_venta": 1,
    "fecha": "2025-01-15"
  }
]

Nota: Campo tamano siempre retorna "" (vacío) — reservado para futura variante de producto.

cURL:

curl "http://localhost/api/reportes/detalle" -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/reportes/detalle", headers={"Authorization": f"Bearer :token"})
detalles = resp.json()
# Análisis rápido: productos más vendidos
from collections import Counter
top = Counter(d['cod_pro'] for d in detalles).most_common(10)

Notas de Uso Comunes

Paginación y Límites

Estos endpoints no tienen paginación — retornan todo el dataset del tenant. Para tenants grandes (>10k registros), considerar:

Filtrar en frontend tras descargar
Implementar paginación en backend (futuro)
Usar /ventas-por-fecha o /ventas-por-mes para reducir volumen

Zona Horaria

Todas las fechas (fecha, fechaPago) están en hora Colombia (UTC-5, sin DST). No convertir a UTC.

Soft Delete

Ventas y egresos con deleted_at NO aparecen en estos reportes (filtrados en query).

Relación entre Reportes de Ventas

/ventas          → TODAS (base general)
/ventas-inc      → Solo SITIO con INC (restaurante/bar)
/ventas-iva      → Solo LLEVAR con IVA (domicilio/llevar)
/ventas-electronicas → Solo tipoPago=Electronico (con CUFE)

Suma de los 3 filtrados ≈ Total general (puede haber边界 cases sin tipo_consumo)

Permisos

Requieren reportes, leer. El rol Asistente (2) NO tiene este permiso por defecto — solo Administrador (1) y Superadmin (3).

Reportes

Reportes

GET /api/reportes/ventas [NUEVO]

GET /api/reportes/ventas-inc [NUEVO]

GET /api/reportes/ventas-iva [NUEVO]

GET /api/reportes/ventas-electronicas [NUEVO]

GET /api/reportes/ventas-electronicas-mes-actual [NUEVO]

GET /api/reportes/ventas-por-fecha [NUEVO]

GET /api/reportes/ventas-por-mes [NUEVO]

GET /api/reportes/ventas-electronica-por-mes [NUEVO]

GET /api/reportes/egresos [NUEVO]

GET /api/reportes/productos [NUEVO]

GET /api/reportes/cierre [NUEVO]

GET /api/reportes/detalle [NUEVO]

Notas de Uso Comunes

Paginación y Límites

Zona Horaria

Soft Delete

Relación entre Reportes de Ventas

Permisos

GET `/api/reportes/ventas` `[NUEVO]`

GET `/api/reportes/ventas-inc` `[NUEVO]`

GET `/api/reportes/ventas-iva` `[NUEVO]`

GET `/api/reportes/ventas-electronicas` `[NUEVO]`

GET `/api/reportes/ventas-electronicas-mes-actual` `[NUEVO]`

GET `/api/reportes/ventas-por-fecha` `[NUEVO]`

GET `/api/reportes/ventas-por-mes` `[NUEVO]`

GET `/api/reportes/ventas-electronica-por-mes` `[NUEVO]`

GET `/api/reportes/egresos` `[NUEVO]`

GET `/api/reportes/productos` `[NUEVO]`

GET `/api/reportes/cierre` `[NUEVO]`

GET `/api/reportes/detalle` `[NUEVO]`