Medical Specialties Catalog and Doctor Availability

MELIKA organizes its medical network around a specialty catalog that connects disciplines to their associated doctors and drives the entire availability-checking workflow. Every doctor in the system (medicos table) is linked to exactly one specialty via a foreign key (medicos.id_especialidad), and the platform exposes both single-day and date-range availability queries that integrate directly with FullCalendar on the frontend. Only specialties marked activa = TRUE are returned through the public API.

Available Specialties

MELIKA currently supports the following medical and health disciplines:

Cardiología

Dermatología

Ginecología

Medicina General

Neurología

Nutrición y Dietética

Oftalmología

Ortopedia y Traumatología

Otorrinolaringología

Pediatría

Psiquiatría

Urología

Specialty Data Model

Each specialty record exposes the following fields:

Field	Type	Description
`id`	`integer`	Unique identifier for the specialty
`nombre`	`varchar`	Display name of the specialty (e.g., `"Cardiología"`)
`descripcion`	`text`	Plain-language description of the discipline
`precio_base`	`numeric`	Base consultation price for this specialty
`imagen_url`	`varchar`	URL to the specialty’s cover image
`activa`	`boolean`	When `FALSE`, the specialty is hidden from all public endpoints

Listing Active Specialties

The specialties listing endpoint is public — no authentication is required. It returns only specialties where activa = TRUE, ordered by name.

GET /especialidades

Example response:

[
  {
    "id": 1,
    "nombre": "Cardiología",
    "descripcion": "Diagnóstico y tratamiento de enfermedades del corazón y sistema cardiovascular",
    "precio_base": "80000.00",
    "imagen_url": "/imagenes/especialidades/cardiologia.jpg",
    "activa": true
  },
  {
    "id": 2,
    "nombre": "Dermatología",
    "descripcion": "Diagnóstico y cuidado integral de patologías de la piel, pelo y uñas",
    "precio_base": "70000.00",
    "imagen_url": "/imagenes/especialidades/dermatologia.jpg",
    "activa": true
  }
]

Doctors per Specialty

To list all active doctors within a specialty, query the specialty’s doctor endpoint. Only doctors where both medicos.activo = TRUE and usuarios.activo = TRUE are returned, ordered by first name.

GET /especialidades/:id/medicos

Doctor Profile Fields

Field	Type	Description
`id`	`integer`	Doctor’s unique ID in the `medicos` table
`nombre`	`varchar`	Doctor’s first name (from `usuarios`)
`primer_apellido`	`varchar`	Doctor’s first surname (from `usuarios`)
`foto_url`	`varchar`	URL to the doctor’s profile photo
`tarifa`	`numeric`	Doctor’s per-consultation fee
`calificacion`	`numeric`	Average star rating (e.g., `4.8`)
`acepta_teleconsulta`	`boolean`	Whether the doctor offers video consultations
`acepta_presencial`	`boolean`	Whether the doctor accepts in-person visits
`biografia`	`text`	Short professional biography
`anos_experiencia`	`integer`	Years of clinical experience

Example response item:

{
  "id": 3,
  "nombre": "Laura",
  "primer_apellido": "Méndez",
  "foto_url": "https://storage.melika.app/medicos/laura-mendez.jpg",
  "tarifa": "130000.00",
  "calificacion": 4.9,
  "acepta_teleconsulta": true,
  "acepta_presencial": true,
  "biografia": "Cardióloga con 12 años de experiencia en cardiología intervencionista y prevención cardiovascular.",
  "anos_experiencia": 12
}

Checking Doctor Availability

MELIKA provides two availability endpoints — both powered by the franjas_horarias table. Only slots with disponible = TRUE are returned from either endpoint.

Single Day
Date Range

Returns available time slots for a specific doctor on a given date. Use this to power a day-level slot picker.

GET /especialidades/disponibilidad?medico_id=3&fecha=2025-08-15

Query parameters:

Parameter	Required	Description
`medico_id`	✅ Yes	The doctor’s ID from the `medicos` table
`fecha`	✅ Yes	Date to query in `YYYY-MM-DD` format

Example response:

[
  {
    "id": 14,
    "hora_inicio": "09:00:00",
    "hora_fin": "09:40:00",
    "disponible": true
  },
  {
    "id": 15,
    "hora_inicio": "09:40:00",
    "hora_fin": "10:20:00",
    "disponible": true
  }
]

All returned slots have disponible = true. Already-booked slots are excluded entirely — they do not appear in the response.

Returns FullCalendar-compatible event objects covering a span of dates. Use this to populate the booking calendar showing when a doctor is available across multiple weeks or months.

GET /especialidades/disponibilidad-rango?medico_id=3&inicio=2025-08-01&fin=2025-08-31

Query parameters:

Parameter	Required	Description
`medico_id`	✅ Yes	The doctor’s ID from the `medicos` table
`inicio`	✅ Yes	Range start date in `YYYY-MM-DD` format
`fin`	✅ Yes	Range end date in `YYYY-MM-DD` format

Example response item:

{
  "id": "franja-14",
  "title": "09:00",
  "start": "2025-08-15T09:00:00",
  "end": "2025-08-15T09:40:00",
  "backgroundColor": "#1A7A52",
  "borderColor": "#145C3E",
  "textColor": "#fff",
  "extendedProps": {
    "id_franja": 14,
    "hora_inicio": "09:00:00",
    "hora_fin": "09:40:00",
    "fecha": "2025-08-15"
  }
}

Pass the array directly to FullCalendar’s events prop for a fully rendered availability calendar. The extendedProps.id_franja value is what gets submitted as id_franja in the booking request.

How Specialties Connect to the Booking Flow

The specialty catalog is the entry point for every appointment booking. The connection between specialties, doctors, slots, and appointments follows this hierarchy:

Select a Specialty

Patient browses GET /especialidades and picks a discipline. The id and precio_base are retained for display in the booking summary.

Choose a Doctor

Patient calls GET /especialidades/:id/medicos to see available physicians, their ratings, fees, and consultation modalities.

Query Available Slots

Patient calls GET /especialidades/disponibilidad-rango to populate the booking calendar, then GET /especialidades/disponibilidad on day selection to retrieve the granular slot list for that date.

Book the Appointment

Patient submits POST /citas with id_especialidad, id_medico, id_franja, fecha, and hora_inicio. The franja_horaria is reserved immediately with database-level concurrency protection.

When building the booking UI, call the range availability endpoint first to show a calendar overview, then switch to the single-day endpoint when the user selects a specific date to display the granular slot picker.

Get Started

Core Features

User Roles

Medical Specialties Catalog and Doctor Availability

Available Specialties

Cardiología

Dermatología

Ginecología

Medicina General

Neurología

Nutrición y Dietética

Oftalmología

Ortopedia y Traumatología

Otorrinolaringología

Pediatría

Psiquiatría

Urología

Specialty Data Model

Listing Active Specialties

Doctors per Specialty

Doctor Profile Fields

Checking Doctor Availability

How Specialties Connect to the Booking Flow

Build docs developers (and LLMs) love

Get Started

Core Features

User Roles

Documentation Index

​Available Specialties

Cardiología

Dermatología

Ginecología

Medicina General

Neurología

Nutrición y Dietética

Oftalmología

Ortopedia y Traumatología

Otorrinolaringología

Pediatría

Psiquiatría

Urología

​Specialty Data Model

​Listing Active Specialties

​Doctors per Specialty

​Doctor Profile Fields

​Checking Doctor Availability

​How Specialties Connect to the Booking Flow

Build docs developers (and LLMs) love

Available Specialties

Specialty Data Model

Listing Active Specialties

Doctors per Specialty

Doctor Profile Fields

Checking Doctor Availability

How Specialties Connect to the Booking Flow