Skip to main content

​
Overview

NOT IMPLEMENTED: The CitaController is empty in the source code. These endpoints are architectural documentation only and will return 404 errors if called. Only the Especialidad endpoints are currently functional.
The Citas (Appointments) resource is architecturally designed to provide CRUD operations for managing medical appointments. The data model is defined with status tracking (Pending, Confirmed, Cancelled, Completed), but the controller endpoints are not yet implemented.

​
Endpoints

​
List All Appointments

Retrieve a list of all medical appointments. 
GET /api/Cita
Response: 200 OK
​
appointments
array
Array of appointment objects
Example Request: 
curl -X GET "https://localhost:5001/api/Cita" \
  -H "Content-Type: application/json"
Example Response: 
[
  {
    "id": 1,
    "pacienteId": 1,
    "medicoId": 1,
    "costo": 150.00,
    "motivo": "Consulta de control cardiológico",
    "fechaInicio": "2026-03-15T09:00:00",
    "fechaFin": "2026-03-15T09:30:00",
    "observaciones": "Paciente reporta dolor en el pecho ocasional",
    "estado": "Confirmada"
  },
  {
    "id": 2,
    "pacienteId": 2,
    "medicoId": 2,
    "costo": 120.00,
    "motivo": "Control pediátrico",
    "fechaInicio": "2026-03-16T14:00:00",
    "fechaFin": "2026-03-16T14:30:00",
    "observaciones": null,
    "estado": "Pendiente"
  }
]

​
Get Appointment by ID

Retrieve a specific appointment by its unique identifier. 
GET /api/Cita/{id}
​
id
integer
required
The unique identifier of the appointment
Response: 200 OK Returns the appointment object (same structure as above). Response: 404 Not Found Returned when the appointment with the specified ID doesn’t exist. Example Request: 
curl -X GET "https://localhost:5001/api/Cita/1" \
  -H "Content-Type: application/json"
Example Response: 
{
  "id": 1,
  "pacienteId": 1,
  "medicoId": 1,
  "costo": 150.00,
  "motivo": "Consulta de control cardiológico",
  "fechaInicio": "2026-03-15T09:00:00",
  "fechaFin": "2026-03-15T09:30:00",
  "observaciones": "Paciente reporta dolor en el pecho ocasional",
  "estado": "Confirmada"
}

​
Create Appointment

Create a new medical appointment. 
POST /api/Cita
Request Body
​
pacienteId
integer
required
ID of the patient for this appointment (must exist in the system)
​
medicoId
integer
required
ID of the doctor for this appointment (must exist in the system)
​
costo
decimal
required
Cost of the appointment (must be a positive number)
​
motivo
string
required
Reason or purpose for the appointment
​
fechaInicio
string
required
Start date and time in ISO 8601 format (e.g., “2026-03-15T09:00:00”)
​
fechaFin
string
required
End date and time in ISO 8601 format (e.g., “2026-03-15T09:30:00”)
​
observaciones
string
Additional notes or observations (optional)
Response: 201 Created Returns the created appointment object with the assigned ID. The appointment status is automatically set to Pendiente (Pending). Response: 400 Bad Request Returned when validation fails (e.g., invalid date format, negative cost, missing required fields). Response: 404 Not Found Returned when the referenced patient or doctor doesn’t exist. Example Request: 
curl -X POST "https://localhost:5001/api/Cita" \
  -H "Content-Type: application/json" \
  -d '{
    "pacienteId": 1,
    "medicoId": 1,
    "costo": 150.00,
    "motivo": "Consulta de control cardiológico",
    "fechaInicio": "2026-03-15T09:00:00",
    "fechaFin": "2026-03-15T09:30:00",
    "observaciones": "Primera consulta del año"
  }'
Example Response: 
{
  "id": 3,
  "pacienteId": 1,
  "medicoId": 1,
  "costo": 150.00,
  "motivo": "Consulta de control cardiológico",
  "fechaInicio": "2026-03-15T09:00:00",
  "fechaFin": "2026-03-15T09:30:00",
  "observaciones": "Primera consulta del año",
  "estado": "Pendiente"
}

​
Update Appointment

Update an existing appointment’s information. 
PUT /api/Cita/{id}
​
id
integer
required
The unique identifier of the appointment to update
Request Body Same structure as Create Appointment (all fields required).
​
pacienteId
integer
required
ID of the patient for this appointment
​
medicoId
integer
required
ID of the doctor for this appointment
​
costo
decimal
required
Cost of the appointment (must be a positive number)
​
motivo
string
required
Reason or purpose for the appointment
​
fechaInicio
string
required
Start date and time in ISO 8601 format
​
fechaFin
string
required
End date and time in ISO 8601 format
​
observaciones
string
Additional notes or observations (optional)
Response: 200 OK Returns the updated appointment object. Response: 404 Not Found Returned when the appointment with the specified ID doesn’t exist, or when the referenced patient/doctor doesn’t exist. Response: 400 Bad Request Returned when validation fails. Example Request: 
curl -X PUT "https://localhost:5001/api/Cita/3" \
  -H "Content-Type: application/json" \
  -d '{
    "pacienteId": 1,
    "medicoId": 1,
    "costo": 175.00,
    "motivo": "Consulta de control cardiológico - Seguimiento",
    "fechaInicio": "2026-03-15T10:00:00",
    "fechaFin": "2026-03-15T10:30:00",
    "observaciones": "Horario reprogramado a solicitud del paciente"
  }'
Example Response: 
{
  "id": 3,
  "pacienteId": 1,
  "medicoId": 1,
  "costo": 175.00,
  "motivo": "Consulta de control cardiológico - Seguimiento",
  "fechaInicio": "2026-03-15T10:00:00",
  "fechaFin": "2026-03-15T10:30:00",
  "observaciones": "Horario reprogramado a solicitud del paciente",
  "estado": "Pendiente"
}

​
Delete Appointment

Delete an appointment record. 
DELETE /api/Cita/{id}
​
id
integer
required
The unique identifier of the appointment to delete
Response: 204 No Content Returned when the appointment is successfully deleted. Response: 404 Not Found Returned when the appointment with the specified ID doesn’t exist.
Consider implementing soft deletion or status updates instead of hard deletion to maintain appointment history and audit trails.
Example Request: 
curl -X DELETE "https://localhost:5001/api/Cita/3" \
  -H "Content-Type: application/json"

​
Appointment Status (CitaEstado)

Appointments use the CitaEstado enum to track their current status:
​
Pendiente
0
The appointment is scheduled but not yet confirmed
​
Confirmada
1
The appointment has been confirmed by the patient or office staff
​
Cancelada
2
The appointment has been cancelled
​
Completada
3
The appointment has been completed

​
Status Workflow

Typical appointment lifecycle:
  1. Created → Status: Pendiente (automatically set on creation)
  2. Confirmed → Status updated to: Confirmada
  3. Completed → Status updated to: Completada
Alternatively:
  • Cancelled → Status updated to: Cancelada (can happen at any stage)
Example Status Values in Responses: 
{
  "estado": "Pendiente"    // or 0 as integer
}

​
Validation Rules

​
PacienteId

  • Required: Yes
  • Type: Integer
  • Validation: Must reference an existing patient in the system

​
MedicoId

  • Required: Yes
  • Type: Integer
  • Validation: Must reference an existing doctor in the system

​
Costo (Cost)

  • Required: Yes
  • Type: Decimal
  • Range: Must be 0 or greater
  • Error Message: “El costo debe ser un número positivo.”

​
Motivo (Reason)

  • Required: Yes
  • Type: String
  • Validation: Cannot be empty

​
FechaInicio (Start Date/Time)

  • Required: Yes
  • Format: ISO 8601 DateTime (e.g., “2026-03-15T09:00:00”)
  • Validation: Must be a valid date and time

​
FechaFin (End Date/Time)

  • Required: Yes
  • Format: ISO 8601 DateTime (e.g., “2026-03-15T09:30:00”)
  • Validation: Must be a valid date and time
  • Note: Should be after FechaInicio (validation may be implemented in service layer)

​
Observaciones (Observations)

  • Required: No
  • Type: String (nullable)
  • Validation: None
The Citas resource uses several DTOs for different purposes:

​
CitaDto

Enriched appointment DTO used for display with embedded patient and doctor summaries: 
{
  "id": 1,
  "paciente": {
    "id": 1,
    "nombreCompleto": "Juan Pérez",
    "dni": "12345678"
  },
  "medico": {
    "id": 1,
    "nombreCompleto": "Ana Martínez",
    "especialidad": "Cardiología"
  },
  "fechaHora": "2026-03-15T09:00:00",
  "motivo": "Consulta de control cardiológico",
  "estado": "Confirmada"
}
This DTO includes:
  • PacienteResumenDto - Patient summary with full name and DNI
  • MedicoResumenDto - Doctor summary with full name and specialty
  • Simplified date field (fechaHora instead of separate start/end times)

​
CreateCitaDto

Used for creating and updating appointments (structure shown in request examples above).

​
Entity Definition

The Cita entity is defined in Models/Entities/Cita.cs: 
public class Cita
{
    public int Id { get; set; }
    public int PacienteId { get; set; }
    public int MedicoId { get; set; }
    public decimal Costo { get; set; }
    public required string Motivo { get; set; }
    public DateTime FechaInicio { get; set; }
    public DateTime FechaFin { get; set; }
    public string? Observaciones { get; set; }
    public CitaEstado Estado { get; set; }
}

​
Business Logic Considerations

​
Scheduling Conflicts

The API does not currently validate for scheduling conflicts. You may want to implement logic to prevent:
  • Double-booking doctors at the same time
  • Double-booking patients at the same time
  • Overlapping appointment times

​
Date Validation

Consider implementing:
  • End time must be after start time
  • Appointments cannot be scheduled in the past
  • Business hours validation
  • Maximum appointment duration limits

​
Status Transitions

Consider implementing state machine logic:
  • Prevent invalid status transitions (e.g., Completada → Pendiente)
  • Audit trail for status changes
  • Notifications on status changes

Build docs developers (and LLMs) love

Get started for freeTalk to us