Specialties API — Medical Disciplines and Availability

The Specialties API is the entry point for appointment booking in MELIKA. It exposes the catalog of active medical disciplines, resolves which physicians practice each specialty, and provides availability data that integrates directly with FullCalendar for scheduling UIs. All specialties endpoints are public — no authentication token is required — making them suitable for patient-facing booking flows before a user is signed in.

Data Model

The especialidades table describes each medical discipline offered on the platform, including its pricing baseline and active status.

Field	Type	Notes
`id`	integer	Primary key
`nombre`	VARCHAR(100)	UNIQUE. Specialty name
`descripcion`	TEXT	Description of the discipline
`precio_base`	numeric(10,2)	Base consultation price. Default `0.00`
`imagen_url`	VARCHAR(255)	URL to the specialty’s cover image
`activa`	boolean	Only `TRUE` records appear in public listings. Default `TRUE`
`created_at`	timestamp	Auto-generated
`updated_at`	timestamp	Auto-updated

GET /especialidades returns only active specialties (activa = TRUE). Inactive disciplines are hidden from public listings and are accessible only via the admin route.

Endpoints

GET /especialidades

Returns the full list of active medical specialties available on the platform. This is the primary endpoint for populating specialty selector UIs in patient booking flows. Authentication: None (public)

[].id

integer

Specialty identifier.

[].nombre

string

Unique specialty name (e.g. "Cardiología", "Pediatría").

[].descripcion

string

Description of the medical discipline.

[].precio_base

number

Base consultation price for this specialty.

[].imagen_url

string

URL to the specialty’s cover image.

[].activa

boolean

Always true in this response (inactive specialties are filtered out).

curl -X GET http://localhost:3000/especialidades

Example response:

[
  {
    "id": 1,
    "nombre": "Cardiología",
    "descripcion": "Diagnóstico y tratamiento de enfermedades del corazón y sistema cardiovascular.",
    "precio_base": "75.00",
    "imagen_url": "https://storage.example.com/specialties/cardiologia.jpg",
    "activa": true
  },
  {
    "id": 2,
    "nombre": "Pediatría",
    "descripcion": "Atención médica integral para niños y adolescentes.",
    "precio_base": "60.00",
    "imagen_url": "https://storage.example.com/specialties/pediatria.jpg",
    "activa": true
  }
]

GET /especialidades/admin

Returns all specialties — including inactive ones — for administrative management interfaces. This route is intended for admin dashboards where operators need to view, enable, or disable disciplines. Authentication: None at route level (enforced at the admin layer)

[].id

integer

Specialty identifier.

[].nombre

string

Specialty name.

[].descripcion

string

Discipline description.

[].precio_base

number

Base consultation price.

[].imagen_url

string

Cover image URL.

[].activa

boolean

Active status — includes both true and false records.

curl -X GET http://localhost:3000/especialidades/admin

GET /especialidades/disponibilidad

Returns the available time slots (franjas_horarias) for a specific doctor on a given calendar day. Each slot is 40 minutes long. Only slots with disponible = TRUE are returned. Use this endpoint to populate a daily time-slot picker in the booking flow. Authentication: None (public)

medico_id

integer

required

The ID of the physician whose availability to query.

fecha

string

required

The target date in YYYY-MM-DD format.

[].id

integer

Time slot (franja) identifier.

[].hora_inicio

string

Slot start time (e.g. "09:00:00").

[].hora_fin

string

Slot end time (e.g. "09:40:00"). Always 40 minutes after hora_inicio.

[].disponible

boolean

Always true for slots returned by this endpoint.

curl -X GET "http://localhost:3000/especialidades/disponibilidad?medico_id=10&fecha=2025-02-14"

Example response:

[
  { "id": 201, "hora_inicio": "09:00:00", "hora_fin": "09:40:00", "disponible": true },
  { "id": 202, "hora_inicio": "09:40:00", "hora_fin": "10:20:00", "disponible": true },
  { "id": 203, "hora_inicio": "10:20:00", "hora_fin": "11:00:00", "disponible": true }
]

GET /especialidades/disponibilidad-rango

Returns all available time slots for a doctor within a date range, formatted as FullCalendar event objects. This endpoint is designed for direct consumption by FullCalendar’s events feed — each object includes id, title, start, end, backgroundColor, borderColor, textColor, and MELIKA-specific metadata in extendedProps. Authentication: None (public)

medico_id

integer

required

The ID of the physician whose availability to query.

inicio

string

required

Range start date in YYYY-MM-DD format (inclusive).

fin

string

required

Range end date in YYYY-MM-DD format (inclusive).

[].id

string

Event identifier — the string "franja-" prefixed to the slot’s numeric ID (e.g. "franja-201").

[].title

string

Human-readable start time label displayed on the calendar (e.g. "09:00").

[].start

string

ISO 8601 datetime string for the event start (e.g. "2025-02-10T09:00:00").

[].end

string

ISO 8601 datetime string for the event end (e.g. "2025-02-10T09:40:00").

[].backgroundColor

string

Hex color for the FullCalendar event background. Always #1A7A52 (MELIKA green).

[].borderColor

string

Hex color for the FullCalendar event border. Always #145C3E.

[].textColor

string

Always "#fff".

[].extendedProps

object

Show extendedProps fields

extendedProps.id_franja

integer

The underlying time-slot ID used for booking.

extendedProps.hora_inicio

string

Raw start time string (e.g. "09:00:00").

extendedProps.hora_fin

string

Raw end time string (e.g. "09:40:00").

extendedProps.fecha

string

Date of the slot in YYYY-MM-DD format.

Feed this endpoint’s response directly to FullCalendar’s events option when using a custom fetch. The extendedProps.id_franja value is what you pass to the appointment booking endpoint when a user selects a slot.

curl -X GET "http://localhost:3000/especialidades/disponibilidad-rango?medico_id=10&inicio=2025-02-10&fin=2025-02-16"

Example response:

[
  {
    "id": "franja-201",
    "title": "09:00",
    "start": "2025-02-10T09:00:00",
    "end": "2025-02-10T09:40:00",
    "backgroundColor": "#1A7A52",
    "borderColor": "#145C3E",
    "textColor": "#fff",
    "extendedProps": {
      "id_franja": 201,
      "hora_inicio": "09:00:00",
      "hora_fin": "09:40:00",
      "fecha": "2025-02-10"
    }
  },
  {
    "id": "franja-202",
    "title": "09:40",
    "start": "2025-02-10T09:40:00",
    "end": "2025-02-10T10:20:00",
    "backgroundColor": "#1A7A52",
    "borderColor": "#145C3E",
    "textColor": "#fff",
    "extendedProps": {
      "id_franja": 202,
      "hora_inicio": "09:40:00",
      "hora_fin": "10:20:00",
      "fecha": "2025-02-10"
    }
  }
]

GET /especialidades/:id/medicos

Returns all active physicians who practice a given specialty, along with their professional profile data. Use this endpoint to populate doctor selection UIs after a patient has chosen a specialty. Only doctors with medicos.activo = TRUE and usuarios.activo = TRUE are returned. Authentication: None (public)

integer

required

The specialty ID for which to retrieve the list of affiliated physicians.

[].id

integer

Doctor’s medicos.id (not usuarios.id).

[].nombre

string

Physician’s first name.

[].primer_apellido

string

Physician’s first surname.

[].tarifa

number

The physician’s individual consultation fee.

[].calificacion

number

Average patient rating score.

[].acepta_teleconsulta

boolean

Whether the physician offers teleconsultation appointments.

[].acepta_presencial

boolean

Whether the physician offers in-person appointments.

[].biografia

string

Short professional biography.

[].anos_experiencia

integer

Years of clinical experience.

[].foto_url

string

URL to the physician’s profile photo.

curl -X GET http://localhost:3000/especialidades/1/medicos

Example response:

[
  {
    "id": 3,
    "nombre": "María",
    "primer_apellido": "González",
    "tarifa": "80.00",
    "calificacion": "4.8",
    "acepta_teleconsulta": true,
    "acepta_presencial": true,
    "biografia": "Cardióloga con 12 años de experiencia en cardiopatías congénitas.",
    "anos_experiencia": 12,
    "foto_url": "https://storage.example.com/doctors/mgonzalez.jpg"
  }
]

POST /especialidades

Creates a new medical specialty entry. This operation is reserved for platform administrators and is exposed through the admin route layer. The request field icono maps to the imagen_url column in the database. Authentication: None at route level (enforced at the admin layer)

nombre

string

required

Unique specialty name. Returns an error if a specialty with this name already exists.

descripcion

string

Description of the discipline.

precio_base

number

Base consultation price for this specialty.

icono

string

URL to the specialty’s cover image. Stored as imagen_url in the database.

activa

boolean

Whether the specialty is immediately visible to patients. Defaults to true.

curl -X POST http://localhost:3000/especialidades \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Dermatología",
    "descripcion": "Diagnóstico y tratamiento de enfermedades de la piel.",
    "precio_base": 65.00,
    "icono": "https://storage.example.com/specialties/dermatologia.jpg",
    "activa": true
  }'

PUT /especialidades/:id

Fully updates an existing specialty record. All fields may be modified, including toggling activa to hide a specialty from public listings without deleting it. The request field icono maps to imagen_url in the database. Authentication: None at route level (enforced at the admin layer)

integer

required

The ID of the specialty to update.

nombre

string

required

Updated specialty name. Must remain unique across all specialties.

descripcion

string

Updated discipline description.

precio_base

number

Updated base consultation price.

icono

string

Updated cover image URL. Stored as imagen_url in the database.

activa

boolean

Set to false to deactivate and hide this specialty from public listings.

curl -X PUT http://localhost:3000/especialidades/3 \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Dermatología",
    "precio_base": 70.00,
    "activa": false
  }'

Authentication

Appointments

Doctors & Schedules

Clinical Records

Catalog

Admin

Specialties API — Medical Disciplines and Availability

Data Model

Endpoints

GET /especialidades

GET /especialidades/admin

GET /especialidades/disponibilidad

GET /especialidades/disponibilidad-rango

GET /especialidades/:id/medicos

POST /especialidades

PUT /especialidades/:id

Build docs developers (and LLMs) love

Authentication

Appointments

Doctors & Schedules

Clinical Records

Catalog

Admin

Documentation Index

​Data Model

​Endpoints

​GET /especialidades

​GET /especialidades/admin

​GET /especialidades/disponibilidad

​GET /especialidades/disponibilidad-rango

​GET /especialidades/:id/medicos

​POST /especialidades

​PUT /especialidades/:id

Build docs developers (and LLMs) love

Data Model

Endpoints

GET /especialidades

GET /especialidades/admin

GET /especialidades/disponibilidad

GET /especialidades/disponibilidad-rango

GET /especialidades/:id/medicos

POST /especialidades

PUT /especialidades/:id