Saltar a contenido

Módulo 14 · Citas

← Módulo 13 · Inicio · Módulo 15 →

Nivel: intermedio · Duración: 75 minutos · Necesitas: módulos 10 y 11

Lo que vas a aprender

  1. Cómo se modela una agenda en FHIR: Schedule, Slot y Appointment.
  2. A reservar un cupo y confirmar la asistencia (AppointmentResponse).
  3. El ciclo de vida de una cita: reservada, cumplida o cancelada.
  4. Por qué un servidor puede devolver una búsqueda desactualizada (caché).

La historia

Después de la cirugía (módulo 13), Luis empieza la quimioterapia en el Hospital de Día de Oncología, que tiene una agenda de julio a septiembre de 2025.

  • El 20 de junio se agenda el ciclo 1 para el 2 de julio a las 09:00. El 30 de junio, Luis confirma por teléfono. El 2 de julio se cumple.
  • Se agenda el ciclo 2 para el 23 de julio. Pero el control de hemograma muestra neutropenia (pocos neutrófilos, un efecto de la quimioterapia), y la cita se cancela para reprogramarla.

El prototipo Agenda FHIR usa exactamente estos recursos en una aplicación de R y Shiny: verás el calendario que se construye con Schedule, Slot y Appointment.


Cómo se modela una agenda

Schedule (la agenda del hospital de día, jul–sep)
   └── Slot (cupos: 2-jul 09:00–11:00, 23-jul 09:00–11:00, …)  free / busy
          └── Appointment (la cita de Luis en ese cupo)  booked → fulfilled / cancelled
                 └── AppointmentResponse (Luis confirma)
Recurso Responde a...
Schedule ¿De quién es la agenda y para qué periodo?
Slot ¿Qué cupos hay y si están libres u ocupados?
Appointment ¿Quién viene, cuándo y a qué?
AppointmentResponse ¿Qué respondió cada participante?
Encounter (módulo 05) ¿Qué pasó realmente cuando vino?

Ficha del recurso: Schedule

¿Qué es? Un contenedor de cupos: la agenda de un profesional, de un lugar, de un equipo (un ecógrafo) o de un servicio, para un periodo.

Elemento Card. Tipo Para qué sirve
identifier 0..* Identifier Identificador de la agenda.
active ⚑ 0..1 boolean Si está en uso.
serviceCategory 0..* CodeableConcept Categoría de servicio.
serviceType 0..* CodeableConcept Qué servicio se agenda.
specialty 0..* CodeableConcept Especialidad.
actor 1..* Reference(Patient | Practitioner | PractitionerRole | RelatedPerson | …) De quién es la agenda: lugar, profesional, equipo.
planningHorizon 0..1 Period El periodo que cubre.
comment 0..1 string Comentarios.

Ficha del recurso: Slot

¿Qué es? Un intervalo de tiempo de una agenda que puede reservarse.

Elemento Card. Tipo Para qué sirve
identifier 0..* Identifier Identificador del cupo.
serviceType 0..* CodeableConcept Qué servicio se presta en el cupo.
specialty 0..* CodeableConcept Especialidad.
appointmentType 0..1 CodeableConcept Tipo de cita.
schedule 1..1 Reference(Schedule) La agenda a la que pertenece.
status 1..1 code free, busy, busy-unavailable, busy-tentative o entered-in-error.
start 1..1 instant Inicio.
end 1..1 instant Fin.
overbooked 0..1 boolean Si se aceptó más de una cita en el cupo.
comment 0..1 string Comentarios.

Ficha del recurso: Appointment

¿Qué es? Una cita: el acuerdo de que ciertos participantes (paciente, profesional, lugar) se reúnan en un momento para una atención.

¿Para qué se usa? Para agendar consultas, procedimientos, sesiones de tratamiento. Cuando el paciente llega, la atención se registra como un Encounter, que puede apuntar a la cita con appointment.

Elemento Card. Tipo Para qué sirve
identifier 0..* Identifier Número de la cita.
status ⚑ 1..1 code proposed, pending, booked, arrived, fulfilled, cancelled, noshow...
cancelationReason 0..1 CodeableConcept Por qué se canceló.
serviceType 0..* CodeableConcept Qué servicio.
specialty 0..* CodeableConcept Especialidad.
appointmentType 0..1 CodeableConcept Tipo de cita: primera vez, control, urgencia.
reasonCode 0..* CodeableConcept Motivo, codificado.
reasonReference 0..* Reference(Condition | Procedure | Observation | ImmunizationRecommendation) Motivo, como referencia a una Condition.
description 0..1 string Descripción breve.
start 0..1 instant Inicio.
end 0..1 instant Fin.
slot 0..* Reference(Slot) Los cupos que ocupa.
created 0..1 dateTime Cuándo se agendó.
comment 0..1 string Comentarios.
patientInstruction 0..1 string Indicaciones para el paciente (ayuno, documentos).
basedOn 0..* Reference(ServiceRequest) La orden que la originó.
participant 1..* BackboneElement Los participantes.
participant.actor 0..1 Reference(Patient | Practitioner | PractitionerRole | RelatedPerson | …) El paciente, el profesional, el lugar.
participant.required 0..1 code Si su presencia es obligatoria.
participant.status 1..1 code Si aceptó: accepted, declined, tentative o needs-action.

Una regla de Appointment (app-3): una cita que no está proposed ni cancelled debe tener start y end. Una cita reservada sin hora no tiene sentido.

Ficha del recurso: AppointmentResponse

¿Qué es? La respuesta de un participante a una cita: la acepta, la rechaza o propone otra hora.

Elemento Card. Tipo Para qué sirve
appointment 1..1 Reference(Appointment) La cita.
start 0..1 instant Una hora alternativa propuesta.
end 0..1 instant Fin de la hora alternativa.
actor 0..1 Reference(Patient | Practitioner | PractitionerRole | RelatedPerson | …) Quién responde.
participantStatus ⚑ 1..1 code accepted, declined, tentative o needs-action.
comment 0..1 string Comentario.

El hospital de día

Es un Location como el consultorio del módulo 10. Lo que cambia:

{
  "identifier": [
    {
      "system": "https://f-slg.github.io/aprende-fhir/sid/ubicacion",
      "value": "HGDE-HDO"
    }
  ],
  "name": "Hospital de Día de Oncología",
  "type": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
          "code": "ONCL",
          "display": "Medical oncology clinic"
        }
      ],
      "text": "Hospital de día de oncología"
    }
  ],
  "physicalType": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
        "code": "wa",
        "display": "Ward"
      }
    ],
    "text": "Área"
  }
}

ONCL es una consulta de oncología y wa (ward), un área. Solución: 14a_location_hospital_dia.json.

Paso a paso: la agenda

Paso 1 · El mínimo: de quién es la agenda

{
  "resourceType": "Schedule",
  "actor": [
    {
      "reference": "Location/{{dayHospitalLocationId}}",
      "display": "Hospital de Día de Oncología"
    },
    {
      "reference": "PractitionerRole/{{oncologistRoleId}}",
      "display": "Dr. Ruiz · Oncología clínica"
    }
  ]
}

actor es lo único obligatorio: la agenda es del hospital de día y del rol del oncólogo.

Paso 2 · Qué servicio ofrece y en qué periodo

{
  "active": true,
  "serviceType": [
    {
      "text": "Quimioterapia ambulatoria"
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "394593009",
          "display": "Medical oncology"
        }
      ],
      "text": "Oncología clínica"
    }
  ],
  "planningHorizon": {
    "start": "2025-07-01T07:00:00-05:00",
    "end": "2025-09-30T19:00:00-05:00"
  }
}

Paso 3 · Comentario, identificador y narrativa

{
  "comment": "Sillones de quimioterapia, de lunes a viernes de 07:00 a 19:00.",
  "identifier": [
    {
      "system": "https://f-slg.github.io/aprende-fhir/sid/agenda",
      "value": "AG-HDO-2025-3"
    }
  ],
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Agenda de quimioterapia del Hospital de Día de Oncología, julio a septiembre de 2025.</p></div>"
  }
}

Solución: 14b_schedule_quimioterapia.json.

Paso a paso: el cupo

Paso 1 · El mínimo: agenda, estado, inicio y fin

{
  "resourceType": "Slot",
  "schedule": {
    "reference": "Schedule/{{scheduleId}}",
    "display": "Agenda de quimioterapia"
  },
  "status": "free",
  "start": "2025-07-02T09:00:00-05:00",
  "end": "2025-07-02T11:00:00-05:00"
}

Un cupo libre (free) de dos horas.

Paso 2 · Qué servicio y la narrativa

{
  "serviceType": [
    {
      "text": "Quimioterapia ambulatoria"
    }
  ],
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Cupo libre: 2 de julio de 2025, 09:00 a 11:00.</p></div>"
  }
}

Solución: 14c_slot_ciclo1.json.

Paso a paso: la cita del ciclo 1

Paso 1 · El mínimo: estado, participantes, inicio y fin

{
  "resourceType": "Appointment",
  "status": "booked",
  "participant": [
    {
      "actor": {
        "reference": "Patient/{{patientId}}",
        "display": "Luis Alberto Paredes Cevallos"
      },
      "required": "required",
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "PractitionerRole/{{oncologistRoleId}}",
        "display": "Dr. Ruiz · Oncología clínica"
      },
      "required": "required",
      "status": "accepted"
    },
    {
      "actor": {
        "reference": "Location/{{dayHospitalLocationId}}",
        "display": "Hospital de Día de Oncología"
      },
      "required": "required",
      "status": "accepted"
    }
  ],
  "start": "2025-07-02T09:00:00-05:00",
  "end": "2025-07-02T11:00:00-05:00"
}

Tres participantes, todos required y accepted: el paciente, el rol del oncólogo y el hospital de día. Por la regla app-3, una cita booked debe tener start y end desde el inicio.

Paso 2 · Qué cupo ocupa y cuándo se agendó

{
  "slot": [
    {
      "reference": "Slot/{{slot1Id}}",
      "display": "Cupo del ciclo 1"
    }
  ],
  "created": "2025-06-20T10:00:00-05:00"
}

Paso 3 · Qué atención es y por qué

{
  "serviceType": [
    {
      "text": "Quimioterapia ambulatoria"
    }
  ],
  "appointmentType": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
        "code": "FOLLOWUP",
        "display": "A follow up visit from a previous appointment"
      }
    ],
    "text": "Ciclo de tratamiento"
  },
  "reasonReference": [
    {
      "reference": "Condition/{{conditionCancerId}}",
      "display": "Carcinoma ductal infiltrante de mama izquierda"
    }
  ],
  "description": "Quimioterapia con doxorrubicina, ciclo 1 de 4",
  "identifier": [
    {
      "system": "https://f-slg.github.io/aprende-fhir/sid/cita",
      "value": "CITA-2025-QT1"
    }
  ],
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Cita: quimioterapia ciclo 1 de 4, 2 de julio de 2025, 09:00.</p></div>"
  }
}

Solución: 14e_appointment_ciclo1.json.

El cupo pasa a ocupado. Reservar la cita no cambia el cupo automáticamente: hay que actualizarlo con PUT. Lo que cambia:

{
  "id": "{{slot1Id}}",
  "status": "busy"
}

Paso a paso: la confirmación

Paso 1 · El mínimo: la cita, quién responde y su respuesta

{
  "resourceType": "AppointmentResponse",
  "appointment": {
    "reference": "Appointment/{{appointment1Id}}",
    "display": "Quimioterapia ciclo 1"
  },
  "actor": {
    "reference": "Patient/{{patientId}}",
    "display": "Luis Alberto Paredes Cevallos"
  },
  "participantStatus": "accepted"
}

La regla apr-1 exige decir quién responde (actor) o qué tipo de participante es.

Paso 2 · Un comentario y la narrativa

{
  "comment": "Confirmado por teléfono el 30 de junio de 2025.",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Luis confirma su asistencia a la cita del ciclo 1.</p></div>"
  }
}

Solución: 14f_appointmentresponse_paciente.json.

El ciclo de vida de la cita

Se cumple. El 2 de julio Luis recibe el ciclo 1: la cita pasa a fulfilled. Lo que cambia:

{
  "id": "{{appointment1Id}}",
  "status": "fulfilled"
}

Se cancela. La cita del ciclo 2 (14i) se cancela por neutropenia. Lo que cambia:

{
  "id": "{{appointment2Id}}",
  "status": "cancelled",
  "cancelationReason": {
    "text": "Neutropenia: el recuento de neutrófilos no permite administrar el ciclo"
  },
  "comment": "Se reprograma para el 30 de julio, con un nuevo control de hemograma."
}

cancelationReason con text, porque la lista de motivos de FHIR no tiene uno clínico tan específico. La cita no se borra: queda como cancelada, para saber qué pasó y medir, por ejemplo, cuántos ciclos se postergan por toxicidad.


Ejercicios en el servidor

Paso Petición Guarda
14a POST /Location (hospital de día) dayHospitalLocationId
14b POST /Schedule scheduleId
14c POST /Slot (libre) slot1Id
14d GET /Slot?schedule=Schedule/{{scheduleId}}&status=free
14e POST /Appointment (ciclo 1) appointment1Id
14f PUT /Slot/{{slot1Id}} (ocupado)
14g GET cupos libres otra vez, sin caché (abajo)
14h POST /AppointmentResponse
14i PUT /Appointment/{{appointment1Id}} (cumplida)
14j POST /Slot (ciclo 2, ocupado) slot2Id
14k POST /Appointment (ciclo 2) appointment2Id
14l PUT /Appointment/{{appointment2Id}} (cancelada)
14m GET /Appointment?patient=Patient/{{patientId}}&_sort=date

14d y 14g · Los cupos libres, y la caché del servidor

En el paso 14d buscas los cupos libres: aparece el del 2 de julio. En 14e reservas la cita y en 14f marcas el cupo como ocupado. Si repites exactamente la misma búsqueda enseguida, HAPI puede devolver el cupo todavía como libre.

No es un error del recurso: es la caché de búsquedas del servidor. Para responder más rápido, HAPI reutiliza durante un minuto el resultado de una búsqueda idéntica. Para pedir un resultado fresco se envía el encabezado estándar de HTTP Cache-Control: no-cache:

GET {{FHIRURL}}/Slot?schedule=Schedule/{{scheduleId}}&status=free
Cache-Control: no-cache

Ahora sí: 0 cupos libres. Ten esto en cuenta en cualquier sistema que consulte disponibilidad justo después de reservar.

14m · Las citas del paciente

Verás las dos: el 2 de julio fulfilled y el 23 de julio cancelled.

14n y 14o · Error a propósito: la cita sin participantes

Si el servidor acepta la creación, guarda inmediatamente el id devuelto como errorAppointmentId, junto con la dirección del servidor. Postman y los scripts guardan esa variable por ti. Conserva cada ID si repites el intento; si el servidor rechaza la creación, no borres un recurso de un intento anterior.

Envía (14e1_cita_sin_participantes.json) una cita con estado, hora y descripción, pero sin participant. El servidor responde 201 Created. El validador lo detecta:

Appointment.participant: minimum required = 1, but only found 0

Una cita sin participantes no dice quién viene. Bórrala con DELETE {{FHIRURL}}/Appointment/{{errorAppointmentId}}.

Tras el borrado, conserva la respuesta 200 o 204 y comprueba GET {{FHIRURL}}/Appointment/{{errorAppointmentId}}: en HAPI se espera 410. Un 404 por sí solo no confirma que hayas borrado en el servidor correcto.

Para pensar

Para medir el ausentismo a las citas de quimioterapia, ¿qué búsqueda harías? ¿Y para la oportunidad de la atención (días entre la derivación del módulo 10 y la primera cita con oncología)? (Pista: status=noshow y los elementos created y start.)

Autoevaluación

1. ¿Qué diferencia hay entre un Slot y un Appointment?

El Slot es un intervalo disponible de una agenda; el Appointment es la cita concreta de un paciente, que ocupa uno o más cupos.

2. Al reservar la cita, ¿cambia solo el estado del cupo?

No necesariamente. Muchos servidores no actualizan el Slot por su cuenta: el sistema que agenda debe marcarlo como busy, como en el paso 14f.

3. ¿Appointment o Encounter para "Luis recibió el ciclo 1"?

Las dos cosas: la cita pasa a fulfilled y la atención se registra como un Encounter (con la administración del medicamento del módulo 15).

Resumen

  • Schedule es la agenda; Slot, cada cupo; Appointment, la cita; AppointmentResponse, la respuesta de un participante.
  • Una cita pasa de booked a fulfilled, cancelled o noshow; no se borra.
  • El cupo se marca como ocupado por separado.
  • Los servidores pueden reutilizar búsquedas recientes: usa Cache-Control: no-cache cuando necesites el dato fresco.

Ejecutar este módulo

  • Postman: carpeta 14 · Citas.
  • curl: curl/taller.sh 14
  • R:
citas <- fhir_buscar("Appointment?patient=Patient/{{patientId}}&_sort=date")
fhir_tabla(citas, list(
  fecha  = function(r) substr(r$start, 1, 16),
  que    = function(r) r$description,
  estado = function(r) r$status
))