Reportes y descargas en cola: antes de empezar
Reportes grandes (ventas, compras, productos, kardex, inventario, finanzas y descarga masiva de comprobantes) que se generan en segundo plano. En lugar de esperar el archivo en la misma petición, se solicita, se consulta su estado y se descarga cuando está listo.
Flujo:
- Solicitar el reporte:
POST reports/<tipo>/exportcon los filtros en el cuerpo JSON. Responde202 Acceptedcondata.idydata.status = "IN_PROCESS". - Consultar el estado:
GET download-tray/{id}hasta quedata.readyseatrue(status = "FINISHED"). Polling recomendado: cada 5 segundos durante el primer minuto y luego cada 15–30 segundos; la mayoría de reportes termina en segundos, uno grande o una descarga masiva puede tardar varios minutos. SistatusesERRORoFAILED, el reporte no se pudo generar: vuelve a solicitarlo (revisa los filtros, p. ej. un rango de fechas muy amplio). - Descargar:
GET download-tray/{id}/download(o la URL dedata.download_url). Devuelve el archivo (PDF, Excel o ZIP). Antes de terminar responde409.
Tipos de reporte:
Tipo (<tipo>) |
Reporte | Formatos | Módulo requerido |
|---|---|---|---|
documents |
Comprobantes (facturas, boletas, notas) | pdf, xlsx |
Reportes |
sale-notes |
Notas de venta | pdf, xlsx |
Reportes |
purchases |
Compras | pdf, xlsx |
Reportes |
general-items |
Productos vendidos / comprados línea por línea | pdf, xlsx (o zip por lotes) |
Reportes |
sales-consolidated |
Consolidado de productos vendidos | pdf, xlsx |
Reportes |
massive-documents |
PDF de los comprobantes (descarga masiva) | pdf (o zip por lotes) |
— |
kardex |
Kardex de un producto | pdf (o zip desde 500 movimientos) |
Inventario |
inventory |
Stock actual por almacén | pdf, xlsx |
Inventario |
finance-movements |
Movimientos de ingresos y egresos | xlsx |
Finanzas |
global-payments |
Pagos y cobros por destino | xlsx |
Finanzas |
Fechas: todos los reportes con período reciben date_start y date_end en formato YYYY-MM-DD (ambos inclusive). El inventario no lleva fechas y en el kardex son opcionales.
Permisos: administradores y vendedores. Si el usuario tiene módulos asignados, necesita el del reporte (403 si no). Un vendedor solo obtiene lo suyo: el reporte se genera con su usuario, así que solo incluye sus comprobantes y movimientos aunque filtre por otro usuario. En la bandeja cada usuario ve solo sus reportes; el administrador ve todos.
Formato: las respuestas JSON son {success, data, message?}; los errores usan el código HTTP real: 403 sin permiso, 404 no existe, 409 el archivo aún no está listo o el reporte falló, 422 {success: false, message: {campo: [errores]}} validación de filtros (no se crea el reporte). La descarga responde el archivo.
Vigencia: los archivos quedan en la bandeja (también visibles en Reportes → Bandeja de descargas del panel web); si el archivo ya no está disponible, la descarga responde 404 y basta con solicitar el reporte otra vez.