Generate and Export Yakult Sales Reports

The Reports module gives Yakult distributors a complete picture of sales performance across any time window. Masters can generate reports across all vendors, clients, and products, while Promotors and Repartidores can generate and revisit their own reports. Every report is saved automatically to the history the moment it is generated, so your team always has a full audit trail of past analyses. Supported outputs include an interactive data response, a branded PDF with charts, and a print-ready HTML page.

Authentication

All report endpoints are protected by JWT. Every request must include a valid bearer token in the Authorization header.

Authorization: Bearer <your_jwt_token>

Attempting to call any report endpoint without a valid token returns 401 Unauthorized.

Before building a report form or API call, retrieve the valid filter values from the options endpoint. This returns the full lists of clients, products, categories, and vendors that are available in the system.

GET /api/reportes/opciones

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": "Promotor" }
  ]
}

Always call GET /api/reportes/opciones first to populate your filter dropdowns with real IDs. Passing an id that does not exist in the system will produce an empty report rather than an error.

Generate a Report

Submit a POST request to create a new report. Only fechaInicio and fechaFin are required — all other filters are optional and default to null (no filter applied).

POST /api/reportes/ventas

Request Body

{
  "nombre": "Reporte Enero 2025",
  "fechaInicio": "2025-01-01",
  "fechaFin": "2025-01-31",
  "clienteId": null,
  "productoId": null,
  "categoria": null,
  "vendedorId": null,
  "agrupacion": "dia"
}

Filter Reference

fechaInicio / fechaFin

Required. Both dates must follow YYYY-MM-DD format, and fechaInicio cannot be after fechaFin.

clienteId

Optional. Limits results to a single client. Use the numeric id from the options endpoint.

productoId

Optional. Limits results to a single product SKU. Use the numeric id from the options endpoint.

categoria

Optional. Limits results to a product category string (e.g. "Bebida probiótica").

vendedorId

Optional. Limits results to a single vendor. Masters only — Promotors/Repartidores always see their own data.

agrupacion

Optional. Controls how the time-series statistics are bucketed. Defaults to dia.

Grouping (`agrupacion`) Values

Value	Buckets the time series by	Typical use case
`dia`	Individual calendar day	Short ranges — a week or single month
`semana`	ISO week number	Multi-month comparisons
`mes`	Calendar month	Quarterly or annual overviews
`anio`	Calendar year	Multi-year trend lines

Validation Rules

The API returns 400 Bad Request if any of the following conditions are violated:

fechaInicio or fechaFin is not in YYYY-MM-DD format.
fechaInicio is after fechaFin.

An unrecognized agrupacion value does not produce an error — it silently falls back to dia.

Example `curl` Request

curl -X POST https://your-api.com/api/reportes/ventas \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Reporte Enero 2025",
    "fechaInicio": "2025-01-01",
    "fechaFin": "2025-01-31",
    "clienteId": null,
    "productoId": null,
    "categoria": null,
    "vendedorId": null,
    "agrupacion": "dia"
  }'

Report Response Structure

A successful POST returns a fully populated report object. The response is divided into five sections described below.

{
  "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": "Admin", "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, Yakult Light x10",
      "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
    }
  ]
}

Section Breakdown

resumen — Totals

Three aggregate KPIs covering the full filtered period: totalVentas (number of transactions), unidadesVendidas (total product units), and ingresosTotales (revenue in local currency). These power the performance metrics card in the PDF export.

ventas — Transaction List

A flat list of every matching sale. Each entry includes the sale number, timestamp, client name, vendor name, a human-readable product summary, unit count, and the transaction total.

productosMasVendidos — Top Products

Up to 10 products ranked by units sold, including product ID, name, category, total units, and revenue. Rendered as the top products table in the PDF.

estadisticas — Time Series

One entry per time bucket (controlled by agrupacion). Each bucket contains a machine-readable clave, a display etiqueta, plus ventas, ingresos, and unidades for that period. Powers the bar chart in the PDF.

ventasPorVendedor — Vendor Breakdown

Aggregated revenue, unit count, and transaction count per vendor. Rendered as the vendor donut chart in the PDF.

Generating a report via POST /api/reportes/ventas saves it automatically. You do not need a separate save step. The returned id can be used immediately to retrieve, export, or print the report.

Report History

Retrieve a list of previously generated reports, ordered by creation date (most recent first). The endpoint returns up to 50 reports.

GET /api/reportes/historial

curl https://your-api.com/api/reportes/historial \
  -H "Authorization: Bearer <your_jwt_token>"

Role-Based Visibility

Role	Reports visible in historial
Master	All reports generated by any user in the system
Promotor	Only reports that user generated
Repartidor	Only reports that user generated

Retrieve a Single Report

Fetch the full data object for any saved report by its ID.

GET /api/reportes/:id

curl https://your-api.com/api/reportes/1 \
  -H "Authorization: Bearer <your_jwt_token>"

The response structure is identical to the generation response. If a non-Master user attempts to retrieve a report generated by a different user, the API returns 403 Forbidden.

Export as PDF

Download a professionally formatted PDF file for any saved report.

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

curl https://your-api.com/api/reportes/1/export/pdf \
  -H "Authorization: Bearer <your_jwt_token>" \
  --output reporte-enero-2025.pdf

The response uses Content-Type: application/pdf and includes a Content-Disposition: attachment header so browsers trigger a file download automatically.

PDF Contents

Header

YAKULT logo text, the report title “Reporte de Ventas”, and the date range (fechaInicio to fechaFin).

Performance Metrics Card

The three resumen KPIs displayed prominently — total sales, units sold, and total revenue.

Bar Chart

A visual time series using the estadisticas data, bucketed by the chosen agrupacion. Rendered in primary green #1B7A5E.

Period Breakdown Table

A tabular version of estadisticas — every time bucket with its sales count, units, and revenue.

Vendor Donut Chart

A proportional donut chart built from ventasPorVendedor, showing each vendor’s share of total revenue.

Top Products Table

The productosMasVendidos list formatted as a ranked table with product name, category, units, and revenue.

Print as HTML

Open a browser-print-ready HTML version of the report. The page includes a Print button and automatically triggers window.print() on load.

GET /api/reportes/:id/imprimir

curl https://your-api.com/api/reportes/1/imprimir \
  -H "Authorization: Bearer <your_jwt_token>"

The response is Content-Type: text/html. This endpoint is typically opened directly in a browser tab rather than consumed by an API client.

Endpoint Summary

Method	Endpoint	Description
`GET`	`/api/reportes/opciones`	Fetch valid filter values
`POST`	`/api/reportes/ventas`	Generate (and save) a report
`GET`	`/api/reportes/historial`	List saved reports (role-filtered)
`GET`	`/api/reportes/:id`	Retrieve a single saved report
`GET`	`/api/reportes/:id/export/pdf`	Download report as PDF
`GET`	`/api/reportes/:id/imprimir`	Open print-ready HTML page

Authentication

Sales Operations

Reports

Generate and Export Yakult Sales Reports | Yakult App

Authentication

Generate a Report

Request Body

Filter Reference

fechaInicio / fechaFin

clienteId

productoId

categoria

vendedorId

agrupacion

Grouping (`agrupacion`) Values

Validation Rules

Example `curl` Request

Report Response Structure

Section Breakdown

Report History

Role-Based Visibility

Retrieve a Single Report

Export as PDF

PDF Contents

Header

Performance Metrics Card

Bar Chart

Period Breakdown Table

Vendor Donut Chart

Top Products Table

Print as HTML

Endpoint Summary

Build docs developers (and LLMs) love

Authentication

Sales Operations

Reports

Documentation Index

​Authentication

​Fetch Available Filter Options

​Generate a Report

​Request Body

​Filter Reference

fechaInicio / fechaFin

clienteId

productoId

categoria

vendedorId

agrupacion

​Grouping (agrupacion) Values

​Validation Rules

​Example curl Request

​Report Response Structure

​Section Breakdown

​Report History

​Role-Based Visibility

​Retrieve a Single Report

​Export as PDF

​PDF Contents

Header

Performance Metrics Card

Bar Chart

Period Breakdown Table

Vendor Donut Chart

Top Products Table

​Print as HTML

​Endpoint Summary

Build docs developers (and LLMs) love

Authentication

Fetch Available Filter Options

Generate a Report

Request Body

Filter Reference

Grouping (`agrupacion`) Values

Validation Rules

Example `curl` Request

Report Response Structure

Section Breakdown

Report History

Role-Based Visibility

Retrieve a Single Report

Export as PDF

PDF Contents

Print as HTML

Endpoint Summary