Saltar al contenido
Facturador

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:

  1. Solicitar el reporte: POST reports/<tipo>/export con los filtros en el cuerpo JSON. Responde 202 Accepted con data.id y data.status = "IN_PROCESS".
  2. Consultar el estado: GET download-tray/{id} hasta que data.ready sea true (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. Si status es ERROR o FAILED, el reporte no se pudo generar: vuelve a solicitarlo (revisa los filtros, p. ej. un rango de fechas muy amplio).
  3. Descargar: GET download-tray/{id}/download (o la URL de data.download_url). Devuelve el archivo (PDF, Excel o ZIP). Antes de terminar responde 409.

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.