Reports API — Generate and Export Sales Reports

The Reports API lets authorized users generate on-demand sales reports with rich filtering options — by date range, client, product, category, or vendor. Reports are persisted in the database so they can be retrieved, shared, and re-exported at any time. Master users can see every report ever generated; other roles see only their own. All endpoints on this API require a valid JWT in the Authorization header, and the account must be active (activo = 1).

GET /api/reportes/opciones

Returns the reference data needed to populate report filter dropdowns — the full list of active clients, products, distinct categories, and active users.

Requires: Authorization: Bearer <token>

Example request

curl http://localhost:3000/api/reportes/opciones \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example response

{
  "clientes": [
    { "id": 1, "nombre": "Tienda López" }
  ],
  "productos": [
    { "id": 1, "nombre": "Yakult Original 65ml", "categoria": "Bebida probiótica" }
  ],
  "categorias": ["Bebida probiótica", "General"],
  "vendedores": [
    { "id": 2, "nombre": "Ana García", "rol": "Master" }
  ]
}

clientes

array

List of active clients (id, nombre) for use in the clienteId filter.

productos

array

List of products (id, nombre, categoria) for use in the productoId filter.

categorias

array

Distinct category strings present in the catalog. Blank categories appear as "General".

vendedores

array

List of active users (id, nombre, rol) for use in the vendedorId filter.

Errors

Status	Reason
`401`	Missing or invalid Bearer token.
`403`	Account is inactive.

POST /api/reportes/ventas

Generates a new sales report, persists it, and returns the full report object. If fechaInicio or fechaFin are not provided, they default to the first day of the current month and today respectively.

Requires: Authorization: Bearer <token>

fechaInicio

string

Start of the reporting period in YYYY-MM-DD format. Defaults to the first day of the current month.

fechaFin

string

End of the reporting period in YYYY-MM-DD format. Must be on or after fechaInicio. Defaults to today.

nombre

string

Optional display name for this report, e.g. "Reporte Enero 2025". If omitted, a name is generated automatically from the date range.

clienteId

number

Filter results to orders from a specific client.

productoId

number

Filter results to orders containing a specific product.

categoria

string

Filter results to orders containing products in a specific category.

vendedorId

number

Filter results to orders created by a specific vendor.

agrupacion

string

Time-series grouping for the estadisticas array. One of dia, semana, mes, or anio. Defaults to dia.

Example request

curl -X POST http://localhost:3000/api/reportes/ventas \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Reporte Enero 2025",
    "fechaInicio": "2025-01-01",
    "fechaFin": "2025-01-31",
    "agrupacion": "dia"
  }'

Example response

{
  "id": 1,
  "nombre": "Reporte Enero 2025",
  "filtros": {
    "fechaInicio": "2025-01-01",
    "fechaFin": "2025-01-31",
    "clienteId": null,
    "productoId": null,
    "categoria": null,
    "vendedorId": null,
    "agrupacion": "dia"
  },
  "generadoPor": {
    "id": 1,
    "nombre": "Ana García",
    "rol": "Master"
  },
  "generadoEn": "2025-01-31T12:00:00.000Z",
  "resumen": {
    "totalVentas": 42,
    "unidadesVendidas": 840,
    "ingresosTotales": 10500.00
  },
  "ventas": [
    {
      "numeroVenta": 5,
      "fecha": "2025-01-15 10:23",
      "cliente": "Tienda López",
      "vendedor": "Ana García",
      "productosVendidos": "Yakult Original 65ml x20",
      "cantidad": 30,
      "total": 750.00
    }
  ],
  "productosMasVendidos": [
    {
      "id": 1,
      "nombre": "Yakult Original 65ml",
      "categoria": "Bebida probiótica",
      "cantidad": 500,
      "total": 6000.00
    }
  ],
  "estadisticas": [
    {
      "clave": "2025-01-01",
      "etiqueta": "01/01",
      "ventas": 3,
      "ingresos": 750.00,
      "unidades": 30
    }
  ],
  "ventasPorVendedor": [
    {
      "vendedor": "Ana García",
      "ingresos": 5000.00,
      "unidades": 400,
      "ventas": 20
    }
  ]
}

number

Auto-generated ID of the stored report.

nombre

string

Display name of the report.

filtros

object

The filter parameters used when generating this report.

Show filtros fields

fechaInicio

string

Start date (YYYY-MM-DD).

fechaFin

string

End date (YYYY-MM-DD).

clienteId

number

Client filter applied, or null.

productoId

number

Product filter applied, or null.

categoria

string

Category filter applied, or null.

vendedorId

number

Vendor filter applied, or null.

agrupacion

string

Time grouping: dia, semana, mes, or anio.

generadoPor

object

The user who generated the report (id, nombre, rol).

generadoEn

string

ISO 8601 timestamp of report generation.

resumen

object

High-level aggregates for the period.

Show resumen fields

totalVentas

number

Number of distinct orders in the period.

unidadesVendidas

number

Total product units sold.

ingresosTotales

number

Total revenue across all orders.

ventas

array

One row per order in the period.

Show ventas fields

numeroVenta

number

Order ID.

fecha

string

Order date and time formatted as YYYY-MM-DD HH:mm.

cliente

string

Client name.

vendedor

string

Vendor name, or "Sin vendedor" if unassigned.

productosVendidos

string

Comma-separated summary of products and quantities, e.g. "Yakult Original 65ml x20".

cantidad

number

Total units across all line items in the order.

total

number

Order total.

productosMasVendidos

array

Up to 10 products ranked by units sold, descending.

Show productosMasVendidos fields

number

Product ID.

nombre

string

Product name.

categoria

string

Product category. Blank categories appear as "General".

cantidad

number

Total units sold in the period.

total

number

Total revenue from this product.

estadisticas

array

Time-series data points grouped by the chosen agrupacion.

Show estadisticas fields

clave

string

Canonical sort key for the bucket (e.g. "2025-01-01" for dia).

etiqueta

string

Short display label for charts (e.g. "01/01").

ventas

number

Number of distinct orders in this bucket.

ingresos

number

Revenue in this bucket.

unidades

number

Units sold in this bucket.

ventasPorVendedor

array

Up to 8 vendors ranked by revenue, descending.

Show ventasPorVendedor fields

vendedor

string

Vendor display name, or "Sin vendedor" if unassigned.

ingresos

number

Total revenue generated by this vendor.

unidades

number

Total units sold by this vendor.

ventas

number

Number of orders created by this vendor.

Errors

Status	Reason
`400`	`fechaInicio` or `fechaFin` is not in `YYYY-MM-DD` format.
`400`	`fechaInicio` is after `fechaFin`.
`401`	Missing or invalid Bearer token.
`403`	Account is inactive.

GET /api/reportes/historial

Returns up to 50 previously generated reports ordered by creation date descending. Master users see all reports; all other roles see only reports they generated themselves.

Requires: Authorization: Bearer <token>

Example request

curl http://localhost:3000/api/reportes/historial \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example response

[
  {
    "id": 1,
    "nombre": "Reporte Enero 2025",
    "fechaInicio": "2025-01-01",
    "fechaFin": "2025-01-31",
    "agrupacion": "dia",
    "totalVentas": 42,
    "ingresosTotales": 10500.00,
    "generadoEn": "2025-01-31 12:00",
    "generadoPor": "Ana García"
  }
]

number

Unique report ID. Use this to retrieve the full report or export it.

nombre

string

Display name of the report.

fechaInicio

string

Start date of the reporting period (YYYY-MM-DD).

fechaFin

string

End date of the reporting period (YYYY-MM-DD).

agrupacion

string

Time grouping used: dia, semana, mes, or anio.

totalVentas

number

Number of orders captured in the report.

ingresosTotales

number

Total revenue captured in the report.

generadoEn

string

Timestamp of when the report was generated, formatted as YYYY-MM-DD HH:mm.

generadoPor

string

Display name of the user who generated the report.

Errors

Status	Reason
`401`	Missing or invalid Bearer token.
`403`	Account is inactive.

GET /api/reportes/:id

Retrieves the full stored report object for a given ID. Returns 403 if the requesting user does not own the report and is not a Master.

Requires: Authorization: Bearer <token>

number

required

Numeric ID of the report to retrieve.

Example request

curl http://localhost:3000/api/reportes/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example response See the full report object structure in the POST /api/reportes/ventas section above. Errors

Status	Reason
`401`	Missing or invalid Bearer token.
`403`	The report belongs to another user and the caller is not a Master, or account is inactive.
`404`	No report found with the given ID.

GET /api/reportes/:id/export/pdf

Downloads the report as a binary PDF file. The response uses Content-Disposition: attachment so browsers prompt the user to save the file.

Requires: Authorization: Bearer <token>

number

required

Numeric ID of the report to export.

Example request

curl http://localhost:3000/api/reportes/1/export/pdf \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --output reporte-enero-2025.pdf

Response headers

Header	Value
`Content-Type`	`application/pdf`
`Content-Disposition`	`attachment; filename="<slug>.pdf"`

Errors

Status	Reason
`401`	Missing or invalid Bearer token.
`403`	The report belongs to another user and the caller is not a Master, or account is inactive.
`404`	No report found with the given ID.

GET /api/reportes/:id/imprimir

Returns a browser-ready HTML page formatted for printing. Open in a browser tab and the system print dialog launches automatically.

Requires: Authorization: Bearer <token>

number

required

Numeric ID of the report to render.

Example request

curl http://localhost:3000/api/reportes/1/imprimir \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response headers

Header	Value
`Content-Type`	`text/html; charset=utf-8`

Errors

Status	Reason
`401`	Missing or invalid Bearer token.
`403`	The report belongs to another user and the caller is not a Master, or account is inactive.
`404`	No report found with the given ID.

Auth

Resources

Reports API — Generate and Export Sales Reports

GET /api/reportes/opciones

POST /api/reportes/ventas

GET /api/reportes/historial

GET /api/reportes/:id

GET /api/reportes/:id/export/pdf

GET /api/reportes/:id/imprimir

Build docs developers (and LLMs) love

Auth

Resources

Documentation Index

​GET /api/reportes/opciones

​POST /api/reportes/ventas

​GET /api/reportes/historial

​GET /api/reportes/:id

​GET /api/reportes/:id/export/pdf

​GET /api/reportes/:id/imprimir

Build docs developers (and LLMs) love

GET /api/reportes/opciones

POST /api/reportes/ventas

GET /api/reportes/historial

GET /api/reportes/:id

GET /api/reportes/:id/export/pdf

GET /api/reportes/:id/imprimir