Doctors API — Profiles, Activation, and Admin Management

The Doctors API covers the full physician lifecycle in MELIKA: administrators register doctors and trigger invitation emails, doctors activate their accounts through a secure token flow, and once active, doctors can access their own profile and record appointment outcomes. All routes share the /medicos prefix for admin operations and /medico for doctor self-service actions. The server runs on PORT (default 3000).

Account Activation Flow

Before a doctor can log in, an administrator must first create their profile via POST /medicos. MELIKA then generates a short-lived invitation token (72-hour expiry) and emails it to the doctor. The doctor visits the activation link and submits their token alongside a chosen password to POST /medicos/activar, which sets their password, marks the usuario as active and verified, and marks the invitation token as used.

The invitation token is stored in the tokens_invitacion table and is single-use. Submitting an expired or already-used token returns an error.

Admin → POST /medicos → invitation email sent to doctor
Doctor → POST /medicos/activar (token + nueva_password) → account activated

Doctor Activation

Activate Doctor Account

This is the only public endpoint in the Doctors API — no authentication token is required.

POST /medicos/activar

Verifies the invitation token against the tokens_invitacion table, confirms it has not been used and has not expired, then updates the linked usuario record with a bcrypt-hashed password and sets activo = TRUE, verificado = TRUE. The token is marked as used immediately after a successful activation.

Request Body

token

string

required

The invitation token delivered to the doctor’s email address.

nueva_password

string

required

The password the doctor wants to set for their account. Must be at least 6 characters. Stored as a bcrypt hash.

Response

mensaje

string

Confirmation message: "Cuenta activada correctamente. Ya puedes iniciar sesión."

Errors

Status	Description
`400`	`token` or `nueva_password` missing, password shorter than 6 characters, token not found, already used, or expired.
`500`	Internal server error.

Example

curl -X POST http://localhost:3000/medicos/activar \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a3f8c1d2e9b74f05...",
    "nueva_password": "MiContraseñaSegura123!"
  }'

Admin — Doctor Management

All endpoints in this section require a valid Bearer token from an administrator account. Include the header Authorization: Bearer <token> on every request.

List All Doctors

GET /medicos

Returns a flat array of all doctor records, each joined with their linked usuario and especialidad rows. Useful for building directory listings or admin dashboards. Auth: verifyToken + isAdmin

Response

An array of doctor objects.

[]

array of objects

Show Doctor object fields

integer

Unique identifier of the medico record.

numero_registro

string

Official medical registration number.

tarifa

number

Consultation fee.

calificacion

number

Average rating score.

activo

boolean

Whether the doctor account is currently active.

acepta_teleconsulta

boolean

Whether the doctor accepts video/remote consultations.

acepta_presencial

boolean

Whether the doctor accepts in-person consultations.

biografia

string

Short professional biography.

anos_experiencia

integer

Years of professional experience.

foto_url

string

Profile photo URL, if set.

id_usuario

integer

ID of the linked usuarios record.

nombre

string

Doctor’s first name (from usuarios).

primer_apellido

string

Doctor’s first surname (from usuarios).

string

Doctor’s email address (from usuarios).

telefono

string

Phone number (from usuarios).

ciudad

string

City (from usuarios).

tipo_documento

string

Document type: CC, CE, or PASAPORTE (from usuarios).

numero_documento

string

Document number (from usuarios).

id_especialidad

integer

Specialty ID (from especialidades).

especialidad

string

Specialty name (from especialidades).

Errors

Status	Description
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not an administrator.
`500`	Internal server error.

Example

curl -X GET http://localhost:3000/medicos \
  -H "Authorization: Bearer <admin_token>"

Create Doctor Profile

POST /medicos

Creates a new medico record and its linked usuario shell with a temporary random password, generates a 72-hour invitation token, and dispatches an activation email to the provided address. The doctor completes registration by calling POST /medicos/activar with the token they receive. Auth: verifyToken + isAdmin

Request Body

nombre

string

required

Doctor’s first name.

primer_apellido

string

required

Doctor’s first surname.

string

required

Email address where the activation invitation will be sent. Must be unique in usuarios.

tipo_documento

string

required

Document type. Accepted values: CC, CE, or PASAPORTE.

numero_documento

string

required

Document number. Must be unique in usuarios.

numero_registro

string

required

Official medical license or registration number. Must be unique in medicos.

id_especialidad

integer

required

ID of the doctor’s medical specialty from the especialidades table.

ciudad

string

City of practice.

acepta_teleconsulta

boolean

Set to true if the doctor offers remote/video consultations. Defaults to true.

acepta_presencial

boolean

Set to true if the doctor accepts in-person appointments. Defaults to true.

biografia

string

Short professional biography displayed on the doctor’s public profile.

anos_experiencia

integer

Number of years of professional experience. Defaults to 0.

foto_url

string

URL of the doctor’s profile photo.

Response `201`

mensaje

string

Confirmation that the profile was created and the invitation email was dispatched (e.g. "Médico creado. Se envió un correo de activación a doctor@clinica.com.").

The 201 response contains only the mensaje string. The newly created record is not returned in the body — query GET /medicos or GET /medico/perfil after activation to retrieve the full profile.

Errors

Status	Description
`400`	Missing required fields or `tipo_documento` value is invalid.
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not an administrator.
`409`	`numero_registro`, `email`, or `numero_documento` already exists.
`500`	Internal server error (email dispatch failures are logged but do not block the `201` response).

Example

curl -X POST http://localhost:3000/medicos \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Carlos",
    "primer_apellido": "Herrera",
    "email": "carlos.herrera@clinica.com",
    "tipo_documento": "CC",
    "numero_documento": "9876543210",
    "numero_registro": "MED-00456",
    "id_especialidad": 3,
    "acepta_teleconsulta": true,
    "acepta_presencial": false,
    "biografia": "Especialista en medicina interna con 8 años de experiencia.",
    "anos_experiencia": 8
  }'

Update Doctor Profile

PUT /medicos/:id

Replaces the editable fields on both the medico record and its linked usuario row. The doctor’s email and document details cannot be changed through this endpoint. Auth: verifyToken + isAdmin

Path Parameters

integer

required

The numeric ID of the medico record to update.

Request Body

nombre

string

Updated first name.

primer_apellido

string

Updated first surname.

ciudad

string

Updated city.

id_especialidad

integer

Updated specialty ID.

tarifa

number

Updated consultation fee. Defaults to 0 if not provided.

acepta_teleconsulta

boolean

Updated teleconsultation preference.

acepta_presencial

boolean

Updated in-person preference.

biografia

string

Updated biography text.

anos_experiencia

integer

Updated years of experience.

foto_url

string

Updated profile photo URL.

Response

mensaje

string

Confirmation: "Médico actualizado correctamente."

Errors

Status	Description
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not an administrator.
`404`	No doctor found with the given ID.
`500`	Internal server error.

Example

curl -X PUT http://localhost:3000/medicos/7 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Carlos Alberto",
    "tarifa": 75.00,
    "acepta_presencial": true
  }'

Toggle Doctor Active Status

PATCH /medicos/:id/estado

Toggles the activo boolean on both the medico and linked usuario records. Deactivating a doctor prevents them from logging in and excludes them from patient-facing search results. Re-activating reverses this. Auth: verifyToken + isAdmin

Path Parameters

integer

required

The numeric ID of the medico record whose status should be toggled.

Response

mensaje

string

"Médico activado." if the account was just enabled, or "Médico desactivado." if it was just disabled.

Errors

Status	Description
`401`	Missing or invalid Bearer token.
`403`	Authenticated user is not an administrator.
`404`	No doctor found with the given ID.
`500`	Internal server error.

Example

curl -X PATCH http://localhost:3000/medicos/7/estado \
  -H "Authorization: Bearer <admin_token>"

Doctor Self-Service

The following endpoints are available to authenticated doctors only. Use the Bearer token issued at login with rol='medico'.

Get Own Profile

GET /medico/perfil

Returns the authenticated doctor’s full profile by joining their medico, usuario, and especialidad rows. Doctors use this to display their own information within the platform dashboard. Auth: verifyToken + isMedico

Response

A single flat profile object returned directly (not wrapped in a key).

integer

Unique identifier of the medico record.

numero_registro

string

Official medical registration number.

tarifa

number

Consultation fee.

calificacion

number

Average rating score.

acepta_teleconsulta

boolean

Whether the doctor accepts video/remote consultations.

acepta_presencial

boolean

Whether the doctor accepts in-person consultations.

biografia

string

Short professional biography.

anos_experiencia

integer

Years of professional experience.

foto_url

string

Profile photo URL, if set.

nombre

string

Doctor’s first name (from usuarios).

primer_apellido

string

Doctor’s first surname (from usuarios).

string

Email address (from usuarios).

telefono

string

Phone number (from usuarios).

ciudad

string

City (from usuarios).

especialidad

string

Specialty name (from especialidades).

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/perfil \
  -H "Authorization: Bearer <medico_token>"

Manage Appointment Outcome

PATCH /medico/citas/:id/gestionar

Allows the authenticated doctor to record the final outcome of an appointment. Only the two terminal states are accepted: completada (the patient attended) and no_asistio (the patient did not show up). Cancelled appointments cannot be gestioned. Auth: verifyToken + isMedico

Path Parameters

integer

required

The numeric ID of the cita (appointment) to update.

Request Body

estado

string

required

The outcome to record. Accepted values: "completada" or "no_asistio". Any other value returns a 400 error.

notas_medicas

string

Optional brief clinical notes for the appointment. If omitted, any existing notes are preserved.

Response

mensaje

string

Confirmation message:

"✅ Cita completada." when estado = 'completada'
"📋 Paciente ausente." when estado = 'no_asistio'

Errors

Status	Description
`400`	`estado` value is not `completada` or `no_asistio`.
`400`	Appointment is already `cancelada`.
`401`	Missing or invalid Bearer token.
`403`	Authenticated user has no doctor profile, or the appointment belongs to another doctor.
`404`	No appointment found with the given ID.
`500`	Internal server error.

Example

curl -X PATCH http://localhost:3000/medico/citas/42/gestionar \
  -H "Authorization: Bearer <medico_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "completada",
    "notas_medicas": "Paciente estable, se recomienda seguimiento en 30 días."
  }'

Authentication

Appointments

Doctors & Schedules

Clinical Records

Catalog

Admin

Documentation Index

​Account Activation Flow

​Doctor Activation

​Activate Doctor Account

​Request Body

​Response

​Errors

​Example

​Admin — Doctor Management

​List All Doctors

​Response

​Errors

​Example

​Create Doctor Profile

​Request Body

​Response 201

​Errors

​Example

​Update Doctor Profile

​Path Parameters

​Request Body

​Response

​Errors

​Example

​Toggle Doctor Active Status

​Path Parameters

​Response

​Errors

​Example

​Doctor Self-Service

​Get Own Profile

​Response

​Errors

​Example

​Manage Appointment Outcome

​Path Parameters

​Request Body

​Response

​Errors

​Example

Build docs developers (and LLMs) love

Account Activation Flow

Doctor Activation

Activate Doctor Account

Request Body

Response

Errors

Example

Admin — Doctor Management

List All Doctors

Response

Errors

Example

Create Doctor Profile

Request Body

Response `201`

Errors

Example

Update Doctor Profile

Path Parameters

Request Body

Response

Errors

Example

Toggle Doctor Active Status

Path Parameters

Response

Errors

Example

Doctor Self-Service

Get Own Profile

Response

Errors

Example

Manage Appointment Outcome

Path Parameters

Request Body

Response

Errors

Example