Appointments API — Schedule and Manage Citas in PortalHub - PortalHub

The Appointments API manages citas — scheduled consulting sessions between clients and advisors. All endpoints require an active session. Appointment times are stored and expected as MySQL DATETIME strings (YYYY-MM-DD HH:MM:SS). The server enforces advisor availability at the exact fecha_hora value — two appointments for the same advisor at the same timestamp will be rejected with HTTP 409.

Appointment states

`estado`	Description
`Programada`	Initial state; the appointment is confirmed and upcoming. Set automatically on creation.
`Reprogramada`	The appointment’s `fecha_hora` has been changed via `modificar.php`.
`Cancelada`	The appointment was cancelled via `cancelar.php`. Cancelled appointments cannot be modified or re-cancelled.

The estado column is an ENUM defined in the citas table. The only valid values are the three listed above. The modificar.php endpoint updates only the fecha_hora column — it never modifies estado. An appointment rescheduled via modificar.php retains its existing estado value (e.g., Programada).

GET /backend/modules/citas/listar.php

Return appointments ordered by fecha_hora DESC. Authentication: Any authenticated user (checkAuth)

listar.php reads the role from $_SESSION['rol'], but the login endpoint sets only $_SESSION['id_rol']. Because $_SESSION['rol'] is never populated, the role filter conditions never match and all authenticated users receive all appointments in the system, regardless of role. The intended scoping below reflects the design intent; the actual runtime behaviour returns all records to every caller.

Caller role	Intended records	Actual runtime behaviour
`ROL_ADMIN` (`1`)	All appointments	All appointments
`ROL_ASESOR` (`2`)	Only where `id_asesor = session user`	All appointments
`ROL_CLIENTE` (`3`)	Only where `id_cliente = session user`	All appointments

Request

No request body or query parameters.

curl -X GET https://your-domain.com/backend/modules/citas/listar.php \
  -H "Cookie: PHPSESSID=<your_session_id>"

id_cita

integer

Auto-incremented primary key for the appointment.

id_cliente

integer

id_usuario of the client for this appointment.

id_asesor

integer

id_usuario of the assigned advisor.

fecha_hora

datetime

Scheduled date and time in YYYY-MM-DD HH:MM:SS format.

estado

enum

Current state: Programada, Reprogramada, or Cancelada.

motivo_cancelacion

string | null

Free-text cancellation reason. Only populated when estado = Cancelada.

Error responses

HTTP	Message
`401`	No autorizado. Inicie sesión Primero.
`500`	Error en la consulta

POST /backend/modules/citas/crear.php

Schedule a new appointment between a client and an advisor. The estado is set to "Programada" automatically. The server validates that the advisor has no other active appointment at the requested fecha_hora before inserting. On success, a notification is sent to the advisor via NotificationService. Authentication: Any authenticated user (checkAuth)

Advisor availability is checked at an exact datetime match. If you need to prevent scheduling conflicts within a time window, implement that logic on the client side before calling this endpoint.

Request body

id_cliente

integer

required

The id_usuario of the client for this appointment.

id_asesor

integer

required

The id_usuario of the advisor who will attend the appointment.

fecha_hora

string

required

Desired appointment time as a MySQL DATETIME string: "YYYY-MM-DD HH:MM:SS". The advisor must have no other non-cancelled appointment at this exact timestamp.

curl -X POST https://your-domain.com/backend/modules/citas/crear.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_cliente": 7,
    "id_asesor": 4,
    "fecha_hora": "2024-07-15 10:00:00"
  }'

id_cita

integer

The auto-incremented ID of the newly created appointment.

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`401`	No autorizado. Inicie sesión Primero.
`405`	Método no permitido
`409`	El asesor ya tiene una cita en ese horario
`500`	Error al crear cita

POST /backend/modules/citas/modificar.php

Reschedule an existing appointment by updating its fecha_hora. Cancelled appointments cannot be rescheduled. Authentication: Any authenticated user (checkAuth)

modificar.php reads the role from $_SESSION['rol'], but the login endpoint sets only $_SESSION['id_rol']. Because $_SESSION['rol'] is never populated, the ownership checks for ROL_CLIENTE and ROL_ASESOR never trigger, and any authenticated user can reschedule any appointment at runtime. The ownership table below reflects the design intent only.

Request body

id_cita

integer

required

The ID of the appointment to reschedule.

fecha_hora

string

required

The new appointment datetime as "YYYY-MM-DD HH:MM:SS". The advisor’s schedule is checked for conflicts, excluding the appointment being modified.

curl -X POST https://your-domain.com/backend/modules/citas/modificar.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_cita": 12,
    "fecha_hora": "2024-07-16 11:00:00"
  }'

Ownership rules (design intent)

Due to the $_SESSION['rol'] bug described above, these checks do not fire at runtime. They represent the intended access control logic.

Session role	Intended access
`ROL_ADMIN` (`1`)	Any appointment
`ROL_ASESOR` (`2`)	Only appointments where `id_asesor` matches the session user
`ROL_CLIENTE` (`3`)	Only appointments where `id_cliente` matches the session user

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`400`	No se puede modificar una cita cancelada
`401`	No autorizado. Inicie sesión Primero.
`403`	No tiene permisos para modificar esta cita
`404`	Cita no encontrada
`405`	Método no permitido
`409`	El asesor ya tiene una cita en ese horario
`500`	Error al modificar cita

POST /backend/modules/citas/cancelar.php

Cancel an appointment by setting its estado to "Cancelada" and recording a mandatory cancellation reason in motivo_cancelacion. A cancelled appointment cannot be cancelled again or rescheduled. Authentication: Any authenticated user (checkAuth)

Both id_cita and motivo_cancelacion are required. The cancellation reason is stored as free text in the citas table and is visible to all parties who can read the appointment.

cancelar.php reads the role from $_SESSION['rol'], but the login endpoint sets only $_SESSION['id_rol']. Because $_SESSION['rol'] is never populated, the ownership checks for ROL_CLIENTE and ROL_ASESOR never trigger, and any authenticated user can cancel any appointment at runtime. The ownership table below reflects the design intent only.

Request body

id_cita

integer

required

The ID of the appointment to cancel.

motivo_cancelacion

string

required

Free-text explanation for the cancellation. Stored verbatim in the motivo_cancelacion column.

curl -X POST https://your-domain.com/backend/modules/citas/cancelar.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_cita": 12,
    "motivo_cancelacion": "El cliente solicitó reprogramar para la próxima semana."
  }'

Ownership rules (design intent)

Due to the $_SESSION['rol'] bug described above, these checks do not fire at runtime. They represent the intended access control logic.

Session role	Intended access
`ROL_ADMIN` (`1`)	Any appointment
`ROL_ASESOR` (`2`)	Only appointments where `id_asesor` matches the session user
`ROL_CLIENTE` (`3`)	Only appointments where `id_cliente` matches the session user

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`400`	La cita ya se encuentra cancelada
`401`	No autorizado. Inicie sesión Primero.
`403`	No tiene permisos para cancelar esta cita
`404`	Cita no encontrada
`405`	Método no permitido
`500`	Error al cancelar cita

Overview

Endpoints

Appointments API — Schedule and Manage Citas in PortalHub

Appointment states

GET /backend/modules/citas/listar.php

Request

Error responses

POST /backend/modules/citas/crear.php

Request body

Error responses

POST /backend/modules/citas/modificar.php

Request body

Ownership rules (design intent)

Error responses

POST /backend/modules/citas/cancelar.php

Request body

Ownership rules (design intent)

Error responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Appointment states

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

​Request

​Error responses

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

​Request body

​Error responses

​POST /backend/modules/citas/modificar.php

​Request body

​Ownership rules (design intent)

​Error responses

​POST /backend/modules/citas/cancelar.php

​Request body

​Ownership rules (design intent)

​Error responses

Build docs developers (and LLMs) love

Appointment states

GET /backend/modules/citas/listar.php

Request

Error responses

POST /backend/modules/citas/crear.php

Request body

Error responses

POST /backend/modules/citas/modificar.php

Request body

Ownership rules (design intent)

Error responses

POST /backend/modules/citas/cancelar.php

Request body

Ownership rules (design intent)

Error responses