Exportar un reporte CSV para Excel con Spring Boot

Un endpoint que descarga un reporte de ventas en CSV listo para Excel, con acentos, nombres con comas y comillas, y la explicación de cada detalle que suele salir mal.

Lo que pide un CSV para Excel

Muchos reportes terminan en Excel, y el formato más sencillo para llevarlos ahí es CSV: texto con una fila por línea y los campos separados por comas. Parece trivial, pero tiene tres trampas que aparecen con datos reales de México: los acentos, que Excel lee mal si no sabe que el archivo es UTF-8; las comas dentro de un campo, como en «Comercial El Águila, S.A.»; y las comillas, como en «Monitor 24″». Además, el navegador debe descargarlo como archivo, no mostrarlo en pantalla.

El controlador

Solo hace falta Spring Web. Escribimos directo en la respuesta, lo que también sirve para reportes de miles de filas, porque no se arma todo el texto en memoria:

package com.ejemplo.reportes;

import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.math.BigDecimal;
import java.nio.charset.StandardCharsets;
import java.time.LocalDate;
import java.util.List;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.ContentDisposition;
import org.springframework.http.HttpHeaders;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ReporteController {

    record Venta(LocalDate fecha, String cliente, String producto, BigDecimal total) {
    }

    private static final List<Venta> VENTAS = List.of(
            new Venta(LocalDate.of(2026, 11, 20), "Ana López", "Teclado mecánico", new BigDecimal("1299.00")),
            new Venta(LocalDate.of(2026, 11, 21), "Comercial \"El Águila\", S.A.", "Monitor 24\"", new BigDecimal("3299.00")),
            new Venta(LocalDate.of(2026, 11, 21), "Luis Pérez", "Cable USB-C, 2 m", new BigDecimal("159.00")));

    @GetMapping("/reportes/ventas.csv")
    public void ventas(HttpServletResponse respuesta) throws IOException {
        respuesta.setContentType("text/csv; charset=UTF-8");
        respuesta.setHeader(HttpHeaders.CONTENT_DISPOSITION,
                ContentDisposition.attachment().filename("ventas-noviembre.csv").build().toString());
        Writer w = new OutputStreamWriter(respuesta.getOutputStream(), StandardCharsets.UTF_8);
        w.write('\uFEFF');                                   // BOM: para que Excel lea bien los acentos
        w.write("fecha,cliente,producto,total\r\n");
        for (Venta v : VENTAS) {
            w.write(v.fecha() + "," + campo(v.cliente()) + "," + campo(v.producto()) + "," + v.total() + "\r\n");
        }
        w.flush();
    }

    /** Encierra en comillas el texto que trae comas, comillas o saltos de línea, y duplica las comillas. */
    static String campo(String texto) {
        if (texto.contains(",") || texto.contains("\"") || texto.contains("\n") || texto.contains("\r")) {
            return "\"" + texto.replace("\"", "\"\"") + "\"";
        }
        return texto;
    }
}
  • Content-Type: text/csv; charset=UTF-8 dice qué es y en qué codificación.
  • Content-Disposition: attachment le pide al navegador que lo descargue con el nombre ventas-noviembre.csv.
  • El BOM (\uFEFF) son tres bytes al inicio que no se ven, pero le avisan a Excel que el archivo es UTF-8. Sin ellos, Excel en Windows muestra «López» en vez de «López».
  • campo() aplica la regla del estándar CSV (RFC 4180): si un texto trae comas, comillas o saltos de línea, va entre comillas, y cada comilla de adentro se escribe doble. Los saltos de línea son \r\n, como pide el estándar.

Probarlo

terminal$ curl -s -i localhost:8080/reportes/ventas.csv | grep -iE "^HTTP|^Content-(Type|Disposition)"
HTTP/1.1 200 
Content-Disposition: attachment; filename="ventas-noviembre.csv"
Content-Type: text/csv;charset=UTF-8
$ curl -s localhost:8080/reportes/ventas.csv -o ventas.csv && od -An -c -N 8 ventas.csv
 357 273 277   f   e   c   h   a
$ cat ventas.csv
fecha,cliente,producto,total
2026-11-20,Ana López,Teclado mecánico,1299.00
2026-11-21,"Comercial ""El Águila"", S.A.","Monitor 24""",3299.00
2026-11-21,Luis Pérez,"Cable USB-C, 2 m",159.00

Las cabeceras están bien, los tres primeros bytes del archivo (357 273 277 en octal, EF BB BF en hexadecimal) son el BOM, y los campos con comas o comillas salieron entre comillas, con las comillas internas duplicadas. Así Excel lo abre con las columnas y los acentos correctos. Si tus reportes se abren en un Excel configurado en español que espera punto y coma, el separador se cambia en una sola línea; y si necesitas un archivo de Excel de verdad, con formatos y varias hojas, la biblioteca Apache POI lo genera.

Cuidado con las fórmulas. Si un campo viene de lo que escribió un usuario y empieza con =, +, - o @, Excel puede interpretarlo como fórmula al abrir el archivo (lo que se conoce como CSV injection). Para reportes con datos de terceros, antepón un apóstrofo a esos campos o quita esos caracteres iniciales.

Cada proyecto de esta página se compiló con Spring Boot 4.2.0, Java 25 (Temurin 25.0.5.1) y Maven 3.10.1 en un contenedor limpio y sin red, se arrancó y se probó con las peticiones de curl que ves; las respuestas y los registros están copiados de esa ejecución.