Reportes

Tag: reports
Descripción: Operaciones para generación, consulta y gestión de reportes

---

1. Crear nuevo reporte (POST /reports)

• Descripción: Crea un nuevo reporte en el sistema asociado a un usuario y sucursal
• Operation ID: ReportsController_create
• Autenticación requerida: 🔒 Sí (ROLE_REPORT_WRITER)

Request Body

{
    "title": "Reporte Mensual de Ventas",
    "reportDate": "2023-05-15",
    "pdfUrl": "https://storage.example.com/reports/monthly-sales-202305.pdf",
    "userId": 1,
    "branchId": 3,
    "metadata": {
        "period": "monthly",
        "format": "pdf",
        "pages": 24
    }
}

Responses

Código	Descripción
201	Reporte creado exitosamente
400	Datos de entrada inválidos
401	No autorizado
404	Usuario o sucursal no encontrado

---

2. Listar todos los reportes (GET /reports)

• Descripción: Obtiene todos los reportes del sistema con paginación
• Operation ID: ReportsController_findAll
• Autenticación requerida: 🔒 Sí (ROLE_REPORT_READER)

Query Parameters

Parámetro	Tipo	Requerido	Descripción
page	integer	❌ No	Número de página (default: 1)
limit	integer	❌ No	Límite por página (default: 10)
branchId	integer	❌ No	Filtrar por ID de sucursal
userId	integer	❌ No	Filtrar por ID de usuario
startDate	string	❌ No	Fecha inicio (YYYY-MM-DD)
endDate	string	❌ No	Fecha fin (YYYY-MM-DD)

Responses

Código	Descripción
200	Lista de reportes obtenida
401	No autorizado

---

3. Obtener reporte por ID (GET /reports/:id)

• Descripción: Obtiene un reporte específico por su ID
• Operation ID: ReportsController_findOne
• Autenticación requerida: 🔒 Sí (ROLE_REPORT_READER)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del reporte

Responses

Código	Descripción
200	Reporte obtenido exitosamente
401	No autorizado
404	Reporte no encontrado

---

4. Descargar reporte PDF (GET /reports/:id/download)

• Descripción: Descarga el archivo PDF del reporte
• Operation ID: ReportsController_download
• Autenticación requerida: 🔒 Sí (ROLE_REPORT_READER)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del reporte

Responses

Código	Descripción
200	PDF del reporte
401	No autorizado
404	Reporte no encontrado

---

5. Actualizar reporte (PATCH /reports/:id)

• Descripción: Actualiza los metadatos de un reporte existente
• Operation ID: ReportsController_update
• Autenticación requerida: 🔒 Sí (ROLE_REPORT_ADMIN)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del reporte

Request Body

{
    "title": "Reporte Mensual Actualizado",
    "metadata": {
        "notes": "Incluye datos de nueva sucursal"
    }
}

Responses

Código	Descripción
200	Reporte actualizado exitosamente
400	Datos de entrada inválidos
401	No autorizado
404	Reporte no encontrado

---

6. Eliminar reporte (DELETE /reports/:id)

• Descripción: Elimina un reporte (soft delete)
• Operation ID: ReportsController_remove
• Autenticación requerida: 🔒 Sí (ROLE_REPORT_ADMIN)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID del reporte

Responses

Código	Descripción
200	Reporte eliminado exitosamente
401	No autorizado
404	Reporte no encontrado

---

Resumen de Endpoints de Reportes

Método	Endpoint	Descripción	Permiso Requerido
POST	/reports	Crear nuevo reporte	ROLE_REPORT_WRITER
GET	/reports	Listar reportes	ROLE_REPORT_READER
GET	/reports/:id	Obtener reporte por ID	ROLE_REPORT_READER
GET	/reports/:id/download	Descargar PDF del reporte	ROLE_REPORT_READER
PATCH	/reports/:id	Actualizar reporte	ROLE_REPORT_ADMIN
DELETE	/reports/:id	Eliminar reporte	ROLE_REPORT_ADMIN

Modelo de Datos

interface Report {
    id: number;
    title: string;
    reportDate: string; // ISO date
    pdfUrl: string;
    userId: number;
    branchId: number;
    externalId: string;
    metadata: Record<string, any>;
    createdAt: string; // ISO date
    updatedAt: string; // ISO date
    user?: User; // Populated relation
    branch?: Branch; // Populated relation
}

Ejemplo de Respuesta

{
    "id": 1,
    "title": "Reporte Mensual de Ventas",
    "reportDate": "2023-05-15T00:00:00.000Z",
    "pdfUrl": "https://storage.example.com/reports/monthly-sales-202305.pdf",
    "userId": 1,
    "branchId": 3,
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {
        "period": "monthly",
        "format": "pdf",
        "pages": 24
    },
    "createdAt": "2023-05-15T10:30:00.000Z",
    "updatedAt": "2023-05-15T10:30:00.000Z",
    "user": {
        "id": 1,
        "name": "Admin User"
    },
    "branch": {
        "id": 3,
        "name": "Sucursal Centro"
    }
}