Doctor Role: Schedules and Clinical Records

Doctors in MELIKA do not self-register. An administrator creates each doctor account and the platform delivers an invitation email containing a one-time activation token. Once activated, the doctor gains access to a dedicated dashboard where they can configure their weekly availability, track their daily agenda, and build a longitudinal clinical record for every patient they treat.

Account Activation

Admin creates the doctor

An administrator fills in the doctor’s profile and submits a POST /medicos request. MELIKA stores the record and immediately dispatches an invitation email to the doctor’s address containing a unique activation token. The account is created in an inactive (activo = FALSE, verificado = FALSE) state.

Doctor clicks the activation link

The invitation email contains a link that embeds the activation token. Clicking it opens the MELIKA password-setup screen at /activar-cuenta?token=<token> in the browser. The token expires after 72 hours. If the doctor does not activate in time, an administrator must issue a new invitation.

Doctor sets their password

The activation form sends a POST to /medicos/activar with the token and the chosen password:

{
  "token": "a3f9c2e1b8d47...",
  "nueva_password": "SecurePassword123!"
}

The body field is nueva_password (not password). The password must be at least 6 characters long. On success, the account is set to activo = TRUE and verificado = TRUE, the token is marked as used, and the doctor can log in.

Activation tokens are single-use. Once the token has been consumed or has expired, it cannot be reused. An administrator must create a new invitation from the admin panel.

Doctor Profile

Each doctor’s profile is accessible via GET /medico/perfil. The response joins the medicos record with the linked usuario and especialidad rows, exposing the following fields:

Field	Type	Description
`id_especialidad`	`integer`	Linked medical specialty
`numero_registro`	`string`	Professional registration number
`tarifa`	`decimal`	Consultation fee
`calificacion`	`decimal`	Average rating from patients
`acepta_teleconsulta`	`boolean`	Whether remote consultations are offered
`acepta_presencial`	`boolean`	Whether in-person consultations are offered
`biografia`	`text`	Short professional biography
`anos_experiencia`	`integer`	Years of clinical experience

GET /medico/perfil
Authorization: Bearer <token>

Schedule Management

Doctors control their own availability by creating and managing time slots (franjas). Each slot is exactly 40 minutes long. Patients can only book appointments into slots that are marked as available (disponible = true).

Creating Slots

The POST /medico/franjas endpoint generates all 40-minute slots for a given date range automatically, with an optional break window:

POST /medico/franjas
Authorization: Bearer <token>
Content-Type: application/json

{
  "fecha": "2025-08-18",
  "hora_inicio": "08:00",
  "hora_fin": "12:00",
  "inicio_descanso": "10:00",
  "fin_descanso": "10:40"
}

The doctor’s identity is taken from the JWT — no id_medico field should be included in the body. MELIKA generates consecutive 40-minute windows from hora_inicio to hora_fin, skipping any window that overlaps the inicio_descanso–fin_descanso range. Duplicate slots (same doctor, date, and hora_inicio) are silently skipped. The response includes insertadas (slots newly created) and duplicadas (slots that already existed):

{
  "mensaje": "Se crearon 5 franja(s) de 40 minutos exitosamente.",
  "insertadas": 5,
  "duplicadas": 0,
  "franjas_intentadas": 5
}

Listing Slots by Date

GET /medico/franjas?fecha=2025-08-18
Authorization: Bearer <token>

Returns all slots for the specified date, each including its disponible status and any linked appointment ID (cita_id).

Editing a Slot

Only slots without an active appointment (disponible = true) can be edited. The request body must include fecha, hora_inicio, and hora_fin:

PATCH /medico/franjas/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "fecha": "2025-08-18",
  "hora_inicio": "08:40",
  "hora_fin": "09:20"
}

The slot must have a duration of exactly 40 minutes. Attempting to edit a slot that already has a reserved appointment returns a 400 error. Attempting to create a time overlap with another existing slot for the same doctor and date returns a 409 Conflict error.

Deleting a Slot

DELETE /medico/franjas/:id
Authorization: Bearer <token>

Deletion is permitted only when disponible = true (i.e., the slot is free). Slots with a confirmed or pending appointment return a 400 error and cannot be removed.

Daily and Range Agenda

Daily Agenda
Range Agenda

Retrieves every appointment for a single date — ideal for the doctor’s daily schedule view.

GET /medico/agenda?fecha=2025-08-18
Authorization: Bearer <token>

The response lists appointments in chronological order with patient name and surname, appointment status, consultation type (presencial / teleconsulta), and a reference to the linked clinical history record (historia_id) if one exists.

Returns FullCalendar-compatible event objects for a date range. Used to populate the interactive calendar on the doctor dashboard.

GET /medico/agenda/rango?inicio=2025-08-01&fin=2025-08-31
Authorization: Bearer <token>

The response merges two sets of events: booked appointments (colour-coded by status — amber for pendiente, green for completada, grey for no_asistio) and free available slots (light green, labelled Disponible (sin reservar)). Each event carries an extendedProps object with tipo, estado, and esFranjaDisponible for use in calendar popovers.

Managing Appointment Outcomes

After a scheduled appointment time passes, the doctor records its outcome via:

PATCH /medico/citas/:id/gestionar
Authorization: Bearer <token>
Content-Type: application/json

{
  "estado": "completada",
  "notas_medicas": "Patient presented with mild hypertension. BP 145/90."
}

The estado field accepts exactly two values:

Value	Meaning
`completada`	The patient attended and the consultation was carried out
`no_asistio`	The patient did not attend

The notas_medicas field is optional. Cancelled appointments (estado = 'cancelada') cannot be managed through this endpoint and return a 400 error. Setting the outcome to completada unlocks the clinical record creation form for that appointment.

Clinical Records

Doctors create and maintain structured clinical histories linked to specific appointments.

Create Record
Update Record
Add Clarification

Once an appointment is marked completada, the doctor can create the initial clinical record:

POST /historias
Authorization: Bearer <token>
Content-Type: application/json

{
  "id_cita": 88,
  "motivo_consulta": "Persistent headache for two weeks",
  "anamnesis": "Patient reports daily frontal headache of moderate intensity...",
  "diagnostico_cie10": "G44.2",
  "descripcion_diagnostico": "Tension-type headache",
  "plan_tratamiento": "Ibuprofen 400 mg every 8 h for 5 days",
  "observaciones": "Follow-up in 2 weeks if no improvement"
}

Evolution notes and updates to an existing record are submitted via PUT:

PUT /historias/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "plan_tratamiento": "Switched to naproxen 500 mg — better tolerance",
  "observaciones": "Patient reports improvement after 3 days"
}

When a doctor needs to annotate a previously filed record without overwriting it, they add a clarification note:

POST /historias/:id/aclaracion
Authorization: Bearer <token>
Content-Type: application/json

{
  "motivo_consulta": "Laboratory results received after consultation confirm diagnosis. No medication change required.",
  "medico_nombre_firma": "Ana Ramírez",
  "medico_rethus_firma": "1234567"
}

Clarifications are appended as immutable entries, preserving the original record’s integrity. The motivo_consulta field (the body of the note) and the legal closure fields (medico_nombre_firma, medico_rethus_firma) are required.

The FormularioAclaracion component is mounted globally in the frontend (at the root level of App.jsx), not inside individual route pages. This means the clarification modal can be triggered from any screen within the doctor’s authenticated session — for example, directly from the agenda view — without requiring a full page navigation to the record detail.

Dashboard and Route Guard

The doctor dashboard is served at /dashboard-medico. The RutaMedico guard in App.jsx verifies that the JWT rol claim equals medico before rendering any nested route. Patients or administrators hitting a doctor-only route are redirected to their respective dashboards.

Get Started

Core Features

User Roles

Doctor Role: Schedules and Clinical Records

Account Activation

Doctor Profile

Schedule Management

Creating Slots

Listing Slots by Date

Editing a Slot

Deleting a Slot

Daily and Range Agenda

Managing Appointment Outcomes

Clinical Records

Dashboard and Route Guard

Build docs developers (and LLMs) love

Get Started

Core Features

User Roles

Documentation Index

​Account Activation

​Doctor Profile

​Schedule Management

​Creating Slots

​Listing Slots by Date

​Editing a Slot

​Deleting a Slot

​Daily and Range Agenda

​Managing Appointment Outcomes

​Clinical Records

​Dashboard and Route Guard

Build docs developers (and LLMs) love

Account Activation

Doctor Profile

Schedule Management

Creating Slots

Listing Slots by Date

Editing a Slot

Deleting a Slot

Daily and Range Agenda

Managing Appointment Outcomes

Clinical Records

Dashboard and Route Guard