Doctor Schedule API — Time Slots and Availability

MELIKA’s scheduling system is built around franjas horarias — fixed 40-minute availability blocks that doctors publish to open themselves up for patient bookings. Each franja represents one bookable slot on a specific date. Doctors manage their own franjas through the /medico/franjas routes and can inspect their booked schedule through two agenda views: a flat daily list and a FullCalendar-ready range response that encodes appointment state as colored events. All schedule endpoints require a valid doctor Bearer token.

Franja Horaria Data Model

A franja_horaria record represents a single 40-minute time slot.

Field	Type	Description
`id`	`integer`	Unique identifier for the slot.
`id_medico`	`integer`	Foreign key — the owning doctor’s ID.
`fecha`	`string`	Date of the slot in `YYYY-MM-DD` format.
`hora_inicio`	`string`	Slot start time in `HH:MM` format.
`hora_fin`	`string`	Slot end time in `HH:MM` format (exactly 40 minutes after `hora_inicio`).
`disponible`	`boolean`	`true` when no active appointment is attached; `false` once booked.
`created_at`	`string`	ISO 8601 timestamp of when the slot was created.

A slot can only be edited or deleted while disponible is true. Once a patient books an appointment against a franja, any attempt to modify or delete it will be rejected with a 400 error.

Agenda Views

Daily Agenda

GET /medico/agenda?fecha=YYYY-MM-DD

Returns all appointments for the authenticated doctor on the specified date, ordered by hora_inicio. Ideal for displaying a single day’s schedule in a list or timeline view. If fecha is omitted it defaults to today’s date. Auth: verifyToken + isMedico

Query Parameters

fecha

string

The date to query in YYYY-MM-DD format (e.g. 2025-07-21). Defaults to today if omitted.

Response

An object containing the queried date and an array of appointment objects for that day.

fecha

string

The date that was queried (YYYY-MM-DD).

citas

array

Array of appointment objects for the requested day, ordered by hora_inicio.

Show Appointment object fields

integer

Appointment ID.

fecha

string

Date of the appointment (YYYY-MM-DD), formatted via SQL TO_CHAR.

hora_inicio

string

Appointment start time (HH:MM).

tipo_consulta

string

presencial or teleconsulta.

motivo

string

Patient’s stated reason for the visit.

estado

string

Appointment state: pendiente, completada, cancelada, or no_asistio.

notas_medicas

string

Clinical notes added by the doctor, if any.

paciente_nombre

string

Patient’s first name.

paciente_apellido

string

Patient’s first surname.

paciente_telefono

string

Patient’s phone number.

especialidad

string

Specialty name.

historia_id

integer

ID of the linked historia_clinica record, if one exists.

Errors

Status	Description
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not a doctor.
`404`	Doctor profile not found for the authenticated user.
`500`	Internal server error.

Example

curl -X GET "http://localhost:3000/medico/agenda?fecha=2025-07-21" \
  -H "Authorization: Bearer <medico_token>"

Range Agenda (FullCalendar)

GET /medico/agenda/rango?inicio=YYYY-MM-DD&fin=YYYY-MM-DD

Returns all events within a date range as an array of FullCalendar event objects. The response merges two sets: booked appointments (excluding cancelled) and available unbooked franjas. Each event’s color encodes its state, making it straightforward to render directly in a FullCalendar instance without client-side transformation. Auth: verifyToken + isMedico

Both inicio and fin are required. Omitting either returns a 400 error. Available franjas appear first in the array, followed by booked appointment events.

Color Reference

State	Background	Border	Text	Meaning
`disponible`	`#D1FAE5`	`#1A7A52`	`#065F46`	Slot is open and bookable.
`pendiente`	`#B45309`	`#92400E`	`#fff`	Appointment booked, not yet attended.
`completada`	`#1A7A52`	`#145C3E`	`#fff`	Appointment successfully completed.
`no_asistio`	`#6B7280`	`#4B5563`	`#fff`	Patient did not attend.

Query Parameters

inicio

string

required

Start of the date range in YYYY-MM-DD format (inclusive).

fin

string

required

End of the date range in YYYY-MM-DD format (inclusive).

Response

An array of FullCalendar-compatible event objects. Available franja events appear before appointment events.

[]

array of objects

Show Available franja event fields

string

Prefixed string ID in the format "franja-{id}" (e.g. "franja-101").

title

string

"🟢 Disponible (sin reservar)".

start

string

ISO datetime string: "YYYY-MM-DDTHH:MM" (no seconds).

end

string

ISO datetime string: "YYYY-MM-DDTHH:MM" (no seconds).

backgroundColor

string

#D1FAE5 (light green).

borderColor

string

#1A7A52 (dark green).

textColor

string

#065F46 (very dark green).

display

string

Always "block".

extendedProps

object

Show extendedProps

esFranjaDisponible

boolean

Always true for available franjas.

Show Booked appointment event fields

string

Prefixed string ID in the format "cita-{id}" (e.g. "cita-42").

title

string

Display label: "{Estado} · {paciente_nombre} {paciente_apellido}" (e.g. "Pendiente · Sofía Ramos").

start

string

ISO datetime string: "YYYY-MM-DDTHH:MM" (no seconds).

backgroundColor

string

Hex fill color per appointment state (see color reference above).

borderColor

string

Darker hex border color per appointment state.

textColor

string

Always "#fff".

extendedProps

object

Show extendedProps

tipo

string

presencial or teleconsulta.

estado

string

Appointment state string.

esFranjaDisponible

boolean

Always false for booked appointments.

Errors

Status	Description
`400`	`inicio` or `fin` parameter is missing.
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not a doctor.
`404`	Doctor profile not found for the authenticated user.
`500`	Internal server error.

Example

curl -X GET "http://localhost:3000/medico/agenda/rango?inicio=2025-07-21&fin=2025-07-25" \
  -H "Authorization: Bearer <medico_token>"

Slot Management

List Slots by Date

GET /medico/franjas?fecha=YYYY-MM-DD

Returns all franja_horaria records owned by the authenticated doctor. Optionally filtered to a specific date via the fecha query parameter. Each record includes a cita_id column — the ID of any non-cancelled appointment linked to that slot. Auth: verifyToken + isMedico

Query Parameters

fecha

string

Optional date filter in YYYY-MM-DD format. If omitted, all franjas for the doctor are returned.

Response

Array of franja_horaria objects (see the data model above), each extended with:

cita_id

integer

ID of the active (non-cancelled) appointment linked to this slot. null when the slot is still available.

Errors

Status	Description
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not a doctor.
`404`	Doctor profile not found for the authenticated user.
`500`	Internal server error.

Example

curl -X GET "http://localhost:3000/medico/franjas?fecha=2025-07-21" \
  -H "Authorization: Bearer <medico_token>"

Create Slots

POST /medico/franjas

Generates multiple consecutive 40-minute availability slots from a given time window on a specific date. The controller internally calls generarFranjasConDescanso, splitting the hora_inicio→hora_fin range into 40-minute blocks and optionally skipping a break window. Slots that already exist for the same doctor, date, and start time are silently skipped (not duplicated). Auth: verifyToken + isMedico

This single endpoint replaces the need to create slots one by one. Supply the full working window (e.g. 08:00→17:00) with an optional lunch break, and all 40-minute slots are generated in one request.

Request Body

fecha

string

required

Date for the slots in YYYY-MM-DD format.

hora_inicio

string

required

Start of the working window in HH:MM format (e.g. "08:00"). Must be earlier than hora_fin.

hora_fin

string

required

End of the working window in HH:MM format (e.g. "17:00").

inicio_descanso

string

Start of an optional break period in HH:MM format (e.g. "12:00"). Slots overlapping the break window are skipped.

fin_descanso

string

End of the break period in HH:MM format (e.g. "13:00"). Required when inicio_descanso is provided.

Response `201`

mensaje

string

Human-readable summary (e.g. "Se crearon 10 franja(s) de 40 minutos exitosamente (2 ya existían).").

insertadas

integer

Number of new slots actually inserted into the database.

duplicadas

integer

Number of slots skipped because they already existed for this doctor/date/hora_inicio combination.

franjas_intentadas

integer

Total number of 40-minute blocks the generator attempted to create from the supplied window.

Errors

Status	Description
`400`	Missing required fields, `hora_inicio` ≥ `hora_fin`, or the time range produces no complete 40-minute blocks.
`401`	Missing or invalid Bearer token.
`403`	Authenticated user has no doctor profile.
`500`	Internal server error.

Example

curl -X POST http://localhost:3000/medico/franjas \
  -H "Authorization: Bearer <medico_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha": "2025-07-22",
    "hora_inicio": "08:00",
    "hora_fin": "12:00",
    "inicio_descanso": "10:00",
    "fin_descanso": "10:20"
  }'

Update a Slot

PATCH /medico/franjas/:id

Updates the date and/or time of an existing slot. Three constraints must all pass for the update to succeed:

The slot’s disponible must be true (no active appointment attached).
The new hora_fin must be exactly 40 minutes after the new hora_inicio.
The new time range must not overlap with any other slot belonging to the same doctor on the same date.

Auth: verifyToken + isMedico

Path Parameters

integer

required

The numeric ID of the franja_horaria to update.

Request Body

fecha

string

required

New date in YYYY-MM-DD format.

hora_inicio

string

required

New start time in HH:MM format.

hora_fin

string

required

New end time in HH:MM format. Must be exactly 40 minutes after hora_inicio.

Response

mensaje

string

Confirmation: "Franja actualizada correctamente."

franja

object

The updated franja_horaria record (same shape as the list response).

Errors

Status	Description
`400`	Missing required fields, `hora_inicio` ≥ `hora_fin`, duration is not exactly 40 minutes, or `disponible = false` (slot has an active appointment).
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not a doctor.
`404`	No slot found with the given ID, or it belongs to another doctor.
`409`	The new time range overlaps with another existing slot for this doctor and date.
`500`	Internal server error.

Example

curl -X PATCH http://localhost:3000/medico/franjas/115 \
  -H "Authorization: Bearer <medico_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha": "2025-07-22",
    "hora_inicio": "11:00",
    "hora_fin": "11:40"
  }'

Delete a Slot

DELETE /medico/franjas/:id

Permanently removes a time slot. The slot must have disponible = true; slots with an active (non-cancelled) appointment attached cannot be deleted. Auth: verifyToken + isMedico

Path Parameters

integer

required

The numeric ID of the franja_horaria to delete.

Response

mensaje

string

"Franja horaria eliminada correctamente." on success.

Errors

Status	Description
`400`	The slot has an active appointment (`disponible = false`): `"No puedes eliminar una franja con cita reservada."`
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not a doctor.
`404`	No slot found with the given ID, or it belongs to another doctor.
`500`	Internal server error.

Example

curl -X DELETE http://localhost:3000/medico/franjas/115 \
  -H "Authorization: Bearer <medico_token>"

Authentication

Appointments

Doctors & Schedules

Clinical Records

Catalog

Admin

Documentation Index

​Franja Horaria Data Model

​Agenda Views

​Daily Agenda

​Query Parameters

​Response

​Errors

​Example

​Range Agenda (FullCalendar)

​Color Reference

​Query Parameters

​Response

​Errors

​Example

​Slot Management

​List Slots by Date

​Query Parameters

​Response

​Errors

​Example

​Create Slots

​Request Body

​Response 201

​Errors

​Example

​Update a Slot

​Path Parameters

​Request Body

​Response

​Errors

​Example

​Delete a Slot

​Path Parameters

​Response

​Errors

​Example

Build docs developers (and LLMs) love

Franja Horaria Data Model

Agenda Views

Daily Agenda

Query Parameters

Response

Errors

Example

Range Agenda (FullCalendar)

Color Reference

Query Parameters

Response

Errors

Example

Slot Management

List Slots by Date

Query Parameters

Response

Errors

Example

Create Slots

Request Body

Response `201`

Errors

Example

Update a Slot

Path Parameters

Request Body

Response

Errors

Example

Delete a Slot

Path Parameters

Response

Errors

Example