Reports API — Accounting Reports and KPI Dashboard - PortalHub

The Reports API covers four distinct resource groups: accounting reports authored by Asesores, an executive KPI dashboard aggregating platform-wide metrics for Admins, announcements broadcast to all authenticated users, and advisor ratings submitted by Clientes. All data is read from the live MySQL database with no caching layer.

Role IDs: Admin = 1, Asesor = 2, Cliente = 3. The crear.php endpoint for reports is restricted to the Asesor role; the list, detail, and dashboard endpoints are open to any authenticated user.

GET /backend/modules/reportes/listar.php

Returns the list of accounting reports. Admin and Cliente users see every report in the system; Asesor users see only the reports they authored (id_asesor = session user). The Asesor filter is applied automatically server-side. Required role: Any authenticated user Query parameters: None

id_reporte

integer

Primary key of the report.

id_asesor

integer

User ID of the Asesor who created the report.

titulo

string

Short title of the report.

descripcion

string

Summary description of the report’s scope or findings.

contenido

string | null

Full report body. May be null for drafts that have not yet had content added.

tipo

string

Report period type. One of Mensual, Trimestral, Anual, or Especial.

estado

string

Publication state. One of Borrador, Publicado, or Archivado.

fecha_creacion

timestamp

UTC timestamp when the report row was inserted.

fecha_actualizacion

timestamp

UTC timestamp of the last update (updated automatically by MySQL).

correo_asesor

string

Email address of the authoring Asesor.

nombre_asesor

string | null

Full name from perfiles.nombre_completo for the authoring Asesor, if a profile exists.

curl -s \
  --cookie "PHPSESSID=<your_session_id>" \
  "https://your-domain.com/backend/modules/reportes/listar.php"

Response 200

{
  "status": 200,
  "message": "Reportes obtenidos correctamente",
  "data": [
    {
      "id_reporte": 5,
      "id_asesor": 7,
      "titulo": "Cierre Trimestral Q3 2024",
      "descripcion": "Resumen de movimientos contables del tercer trimestre.",
      "contenido": "...",
      "tipo": "Trimestral",
      "estado": "Publicado",
      "fecha_creacion": "2024-09-30 18:00:00",
      "fecha_actualizacion": "2024-09-30 18:05:00",
      "correo_asesor": "asesor@example.com",
      "nombre_asesor": "Ana García"
    }
  ]
}

Error responses

Code	Message
`403`	Acceso denegado
`500`	Error en el servidor

POST /backend/modules/reportes/crear.php

Creates a new accounting report. Only the Asesor role may call this endpoint. The server automatically sets id_asesor from the session — it cannot be overridden in the request body. Required role: Asesor (id_rol = 2)

titulo

string

required

Short title of the report. Cannot be empty.

descripcion

string

required

Summary description. Cannot be empty.

contenido

string

Full report body text. Optional; defaults to an empty string for Borrador reports.

tipo

string

Report period type. Allowed values: Mensual (default), Trimestral, Anual, Especial.

estado

string

Initial publication state. Allowed values: Borrador (default), Publicado.

Archivado is a valid database state but cannot be set on creation — it is reserved for administrative archival operations.

id_reporte

integer

Auto-incremented ID of the newly created report.

curl -s -X POST \
  --cookie "PHPSESSID=<asesor_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Análisis Mensual Agosto 2024",
    "descripcion": "Análisis de ingresos y egresos correspondiente a agosto 2024.",
    "tipo": "Mensual",
    "estado": "Borrador"
  }' \
  "https://your-domain.com/backend/modules/reportes/crear.php"

Response 201

{
  "status": 201,
  "message": "Reporte creado exitosamente",
  "data": {
    "id_reporte": 12
  }
}

Error responses

Code	Message
`400`	Faltan campos requeridos: titulo, descripcion
`400`	Tipo no válido. Opciones: Mensual, Trimestral, Anual, Especial
`400`	Estado no válido. Opciones: Borrador, Publicado
`400`	Título y descripción no pueden estar vacíos
`403`	Acceso denegado
`405`	Método no permitido
`500`	Error en el servidor

GET /backend/modules/reportes/detalle.php

Fetches a single report by its primary key. Access control: an Asesor can only retrieve reports they authored; an Admin can retrieve any report. Required role: Any authenticated user (with role-based record-level access) Query parameters

integer

required

Primary key (id_reporte) of the report to retrieve.

id_reporte

integer

Primary key of the report.

id_asesor

integer

User ID of the authoring Asesor.

titulo

string

Title of the report.

descripcion

string

Summary description.

contenido

string | null

Full report body.

tipo

string

Period type: Mensual, Trimestral, Anual, or Especial.

estado

string

State: Borrador, Publicado, or Archivado.

fecha_creacion

timestamp

Creation timestamp.

fecha_actualizacion

timestamp

Last modification timestamp.

correo_asesor

string

Email of the authoring Asesor.

nombre_asesor

string | null

Full name of the authoring Asesor from perfiles.

especialidad

string | null

Asesor’s declared specialty from perfiles.especialidad.

curl -s \
  --cookie "PHPSESSID=<your_session_id>" \
  "https://your-domain.com/backend/modules/reportes/detalle.php?id=5"

Response 200

{
  "status": 200,
  "message": "Reporte obtenido correctamente",
  "data": {
    "id_reporte": 5,
    "id_asesor": 7,
    "titulo": "Cierre Trimestral Q3 2024",
    "descripcion": "Resumen de movimientos contables del tercer trimestre.",
    "contenido": "Los ingresos brutos totalizaron $320,000 MXN...",
    "tipo": "Trimestral",
    "estado": "Publicado",
    "fecha_creacion": "2024-09-30 18:00:00",
    "fecha_actualizacion": "2024-09-30 18:05:00",
    "correo_asesor": "asesor@example.com",
    "nombre_asesor": "Ana García",
    "especialidad": "Contabilidad fiscal"
  }
}

Error responses

Code	Message
`400`	ID de reporte requerido
`403`	No tienes permiso para ver este reporte
`404`	Reporte no encontrado
`500`	Error en el servidor

GET /backend/modules/reportes/dashboard.php

Returns aggregated KPI data across users, appointments, accounting services, and billing. All counts are computed with fresh SQL queries on every request. Useful for the admin dashboard overview panel. Required role: Any authenticated user Query parameters: None

usuarios

object

Show usuario fields

usuarios.total

integer

Total number of user accounts in usuarios.

usuarios.activos

integer

Users with estado = 'activo'.

usuarios.inactivos

integer

Users with estado = 'inactivo'.

usuarios.clientes

integer

Users with id_rol = 3.

usuarios.asesores

integer

Users with id_rol = 2.

citas

object

Show citas fields

citas.total

integer

Total rows in citas.

citas.programadas

integer

Appointments with estado = 'Programada'.

citas.canceladas

integer

Appointments with estado = 'Cancelada'.

servicios

object

Show servicios fields

servicios.total

integer

Total rows in servicios_contables.

servicios.pendientes

integer

Services with estado = 'Pendiente'.

servicios.en_proceso

integer

Services with estado = 'En proceso'.

servicios.completados

integer

Services with estado = 'Completado'.

pagos

object

Show pagos fields

pagos.total

integer

Total rows in pagos_facturacion.

pagos.pendientes

integer

Payments with estado_pago = 'Pendiente'.

pagos.aprobados

integer

Payments with estado_pago = 'Aprobado'.

pagos.monto_total

decimal

Sum of all monto values in pagos_facturacion. Returns 0 when no payments exist.

curl -s \
  --cookie "PHPSESSID=<admin_session_id>" \
  "https://your-domain.com/backend/modules/reportes/dashboard.php"

Response 200

{
  "status": 200,
  "message": "Reporte dashboard obtenido correctamente",
  "data": {
    "usuarios": {
      "total": 52,
      "activos": 48,
      "inactivos": 4,
      "clientes": 40,
      "asesores": 10
    },
    "citas": {
      "total": 130,
      "programadas": 22,
      "canceladas": 8
    },
    "servicios": {
      "total": 95,
      "pendientes": 14,
      "en_proceso": 23,
      "completados": 58
    },
    "pagos": {
      "total": 80,
      "pendientes": 9,
      "aprobados": 65,
      "monto_total": "485000.00"
    }
  }
}

Error responses

Code	Message
`401`	No autenticado
`500`	Error al generar reporte

GET /backend/modules/anuncios/listar.php

Returns the 10 most recent active announcements, ordered newest first. Available to every authenticated user regardless of role. Required role: Any authenticated user Query parameters: None

id_anuncio

integer

Primary key of the announcement.

id_autor

integer

User ID of the Admin who created the announcement.

titulo

string

Announcement headline.

contenido

string

Full announcement body text.

fecha_creacion

timestamp

UTC timestamp when the announcement was published.

Only rows with activo = 1 are returned. Deactivated announcements are silently excluded.

curl -s \
  --cookie "PHPSESSID=<your_session_id>" \
  "https://your-domain.com/backend/modules/anuncios/listar.php"

Response 200

{
  "status": 200,
  "message": "OK",
  "data": [
    {
      "id_anuncio": 3,
      "id_autor": 1,
      "titulo": "Nuevas tarifas 2025",
      "contenido": "A partir del 1 de enero de 2025 entran en vigor las nuevas tarifas de servicios contables.",
      "fecha_creacion": "2024-12-01 09:00:00"
    }
  ]
}

Error responses

Code	Message
`401`	No autenticado
`500`	Error

POST /backend/modules/anuncios/crear.php

Creates a new platform-wide announcement. Only Admin may call this endpoint. The new row is inserted with activo = 1 (the database default), making it immediately visible via the list endpoint. Required role: Admin (id_rol = 1)

titulo

string

required

Announcement headline. Cannot be empty.

contenido

string

required

Full announcement body text. Cannot be empty.

id_anuncio

integer

Auto-incremented ID of the newly created announcement.

curl -s -X POST \
  --cookie "PHPSESSID=<admin_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Cierre por asueto",
    "contenido": "Las oficinas permanecerán cerradas el 20 de noviembre por asueto oficial."
  }' \
  "https://your-domain.com/backend/modules/anuncios/crear.php"

Response 201

{
  "status": 201,
  "message": "Anuncio creado",
  "data": {
    "id_anuncio": 7
  }
}

Error responses

Code	Message
`400`	Faltan campos requeridos (titulo, contenido)
`400`	Título y contenido no pueden estar vacíos
`403`	Acceso denegado
`405`	Método no permitido
`500`	Error

POST /backend/modules/calificaciones/crear.php

Allows a Cliente to rate their currently assigned Asesor on a 1–5 integer scale. The server resolves id_asesor automatically from the active cliente_asesor row — the client does not need to supply the advisor’s ID. A maximum of one rating per client per calendar day is enforced. Required role: Cliente (id_rol = 3)

puntuacion

integer

required

Rating score. Must be an integer between 1 and 5 inclusive.

The Asesor ID is resolved server-side from the cliente_asesor table. There is no id_asesor field in the request body.

curl -s -X POST \
  --cookie "PHPSESSID=<cliente_session_id>" \
  -H "Content-Type: application/json" \
  -d '{ "puntuacion": 5 }' \
  "https://your-domain.com/backend/modules/calificaciones/crear.php"

Response 201

{
  "status": 201,
  "message": "Calificación registrada",
  "data": null
}

Error responses

Code	Message
`400`	Puntuación debe ser entre 1 y 5
`400`	No tienes un asesor asignado activo
`400`	Ya has calificado a tu asesor hoy
`403`	Acceso denegado
`405`	Método no permitido
`500`	Error

GET /backend/modules/calificaciones/estadisticas.php

Returns aggregated rating statistics for every Asesor who has at least one rating and currently holds an active client assignment. Results are ordered by promedio DESC. Required role: Admin (id_rol = 1) Query parameters: None

id_usuario

integer

User ID of the Asesor.

correo

string

Email address of the Asesor.

nombre

string

Full name from perfiles.nombre_completo. Falls back to correo when no profile name is set.

total_calificaciones

integer

Number of individual ratings received by this Asesor.

promedio

decimal

Average rating rounded to one decimal place (e.g. 4.3).

ultima_calificacion

timestamp | null

Timestamp of the most recent rating received.

curl -s \
  --cookie "PHPSESSID=<admin_session_id>" \
  "https://your-domain.com/backend/modules/calificaciones/estadisticas.php"

Response 200

{
  "status": 200,
  "message": "OK",
  "data": [
    {
      "id_usuario": 7,
      "correo": "asesor@example.com",
      "nombre": "Ana García",
      "total_calificaciones": 18,
      "promedio": "4.7",
      "ultima_calificacion": "2024-09-28 11:30:00"
    }
  ]
}

Error responses

Code	Message
`403`	Acceso denegado
`500`	Error

Overview

Endpoints

Reports API — Accounting Reports and KPI Dashboard

GET /backend/modules/reportes/listar.php

POST /backend/modules/reportes/crear.php

GET /backend/modules/reportes/detalle.php

GET /backend/modules/reportes/dashboard.php

GET /backend/modules/anuncios/listar.php

POST /backend/modules/anuncios/crear.php

POST /backend/modules/calificaciones/crear.php

GET /backend/modules/calificaciones/estadisticas.php

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /backend/modules/reportes/listar.php

​POST /backend/modules/reportes/crear.php

​GET /backend/modules/reportes/detalle.php

​GET /backend/modules/reportes/dashboard.php

​GET /backend/modules/anuncios/listar.php

​POST /backend/modules/anuncios/crear.php

​POST /backend/modules/calificaciones/crear.php

​GET /backend/modules/calificaciones/estadisticas.php

Build docs developers (and LLMs) love

GET /backend/modules/reportes/listar.php

POST /backend/modules/reportes/crear.php

GET /backend/modules/reportes/detalle.php

GET /backend/modules/reportes/dashboard.php

GET /backend/modules/anuncios/listar.php

POST /backend/modules/anuncios/crear.php

POST /backend/modules/calificaciones/crear.php

GET /backend/modules/calificaciones/estadisticas.php