Saltar a contenido

logo de Aprende FHIR

Aprende FHIR desde cero

Taller práctico de HL7 FHIR R4 con un caso clínico ecuatoriano

Recursos validados FHIR R4 En español

Abrir el sitio web del taller

Empezar · Módulos · El caso · Validar


In English. Aprende FHIR desde cero ("Learn FHIR from scratch") is a hands-on HL7 FHIR R4 (4.0.1) workshop in Spanish. You create, search, fix and link 36 resource types while following a single Ecuadorian patient, from the first visit to the International Patient Summary (IPS) they take abroad. Each module has a card per resource and exercises for Postman, R or curl, and every example resource is validated in CI. Open the workshop site.

Un recorrido para aprender FHIR haciendo, paso a paso: crearás, buscarás, corregirás y enlazarás 36 tipos de recursos siguiendo a un mismo paciente, desde su primera consulta hasta el resumen internacional (IPS) que lleva de viaje.

En cada módulo:

  • una ficha de cada recurso: qué es, para qué se usa, cuándo usar otro y sus elementos principales, con la cardinalidad y el tipo tomados de la especificación oficial;
  • la construcción paso a paso: del recurso mínimo al completo, campo por campo, explicando cada decisión (todas las versiones intermedias son válidas);
  • errores a propósito, con la respuesta real del servidor, para aprender a leerlos;
  • autoevaluación y resumen.

  • Para quién: profesionales de salud, epidemiólogos, estudiantes y equipos técnicos que se acercan por primera vez a FHIR. No hace falta saber programar.

  • Tres formas de practicar con el mismo contenido: Postman, R/RStudio o curl.
  • Recursos validados: las 80 soluciones y sus 133 versiones intermedias se revisan con el validador oficial de HL7 en cada cambio, y el taller completo se ejecuta en un servidor HAPI FHIR.

Solo datos ficticios. Las personas, las cédulas (empiezan con 99, un código de provincia que no existe) y los establecimientos son inventados. Si usas un servidor público, todo lo que envíes será visible para cualquiera: nunca subas datos reales de pacientes.

Elige tu camino

Ideal si... Cómo empezar
Postman Es tu primera vez con FHIR o no programas. Ves cada petición y cada respuesta. Instala Postman, importa postman/aprende-fhir.postman_collection.json y ejecuta las peticiones en orden. Cada POST guarda el id creado para las siguientes.
R / RStudio Trabajas con datos y quieres convertir los resultados en tablas. Abre aprende-fhir.Rproj, instala httr2, jsonlite y uuid, y sigue r/primeros_pasos.R. Con source("r/taller.R") ejecutas todo.
curl Prefieres la terminal o quieres automatizar. curl/taller.sh ejecuta todo el taller; curl/taller.sh 05 solo hasta el módulo 05. Requiere curl, jq y Python 3.

Los tres caminos usan los mismos archivos JSON y la misma lista de pasos (herramientas/pasos.json).

Guardar los ID y limpiar los recursos de prueba

Después de cada creación, guarda inmediatamente el id devuelto, el tipo de recurso y la dirección del servidor, antes de enviar otra petición. Conserva también los ID de intentos preliminares: los necesitarás para leer o borrar exactamente lo que creaste. Las variables automáticas del taller no sustituyen un registro de todos los intentos si repites pasos o cierras la sesión.

Los módulos 01, 06, 08, 12, 14, 15 y 19 incluyen recursos con errores intencionales que se eliminan al terminar el ejercicio. Usa únicamente el ID de tu propia respuesta de creación. Un borrado con 200 o 204 indica éxito; en HAPI, una lectura posterior suele devolver 410. No uses un ID de un error de duplicado ni borres recursos encontrados solo por nombre o por la cédula ficticia compartida. Si pierdes el ID, revisa la respuesta o el registro de tu cliente; si no lo recuperas, deja la limpieza como no confirmada.

Conserva los recursos válidos del caso mientras avanzas: los módulos siguientes los referencian. Los cuestionarios y recursos canónicos creados de forma condicional pueden estar compartidos con otros participantes.

Los servidores

Por defecto se usa el servidor público de HAPI FHIR: https://hapi.fhir.org/baseR4 (variable FHIRURL). El módulo 18 usa además el servidor de terminología de HL7, https://tx.fhir.org/r4 (variable TXURL). Para cambiarlos, edita las variables en Postman, o en R y curl:

FHIRURL=http://localhost:8080/fhir curl/taller.sh

Si tienes Docker o Podman puedes levantar tu propio servidor en un minuto:

docker run -p 8080:8080 hapiproject/hapi:latest

y usar http://localhost:8080/fhir.

Desde VS Code con Postman

El repositorio viene preconfigurado para VS Code. Ábrelo con code aprende-fhir y acepta instalar las extensiones recomendadas (Postman, R, vista previa de Mermaid y herramientas FHIR).

  1. En la barra lateral, abre Postman e inicia sesión (la extensión usa tu cuenta de Postman, la gratuita basta).
  2. Importa la colección desde Postman web. La extensión de VS Code puede fallar al importar colecciones ("Could not import collection"), pero usa tu misma cuenta: lo que importes en la web aparece solo en VS Code.
  3. Abre https://go.postman.co, entra en My Workspace y pulsa Import (icono junto a Collections, o Ctrl+O). No uses el buscador de arriba.
  4. Pega el enlace de la colección: https://raw.githubusercontent.com/f-slg/aprende-fhir/main/postman/aprende-fhir.postman_collection.json
  5. Si prefieres partes más pequeñas, en postman/niveles/ está la misma colección dividida en básico, intermedio y avanzado.
  6. Importa también un entorno de la carpeta postman/ (desde la web o desde la extensión, con Import → File; los entornos sí entran desde VS Code):
  7. hapi-publico.postman_environment.json: servidor público de HAPI.
  8. hapi-local.postman_environment.json: tu HAPI en http://localhost:8080/fhir.
  9. Selecciona el entorno arriba a la derecha y ejecuta las peticiones en orden con Send. Cada POST guarda el id en el entorno seleccionado, así que los módulos siguientes (aunque estén en otra parte) ya lo encuentran. Para correrla entera, usa Run sobre la colección.

Con el README del módulo abierto a un lado (vista previa: Ctrl+Shift+V) y Postman al otro, sigues la explicación y ejecutas cada paso sin salir del editor.

En Terminal → Ejecutar tarea… tienes atajos para lo demás:

Tarea Qué hace
HAPI local: iniciar / detener Levanta o detiene un HAPI FHIR con Podman o Docker y espera a que responda
Taller: ejecutar la colección de Postman (newman) Corre la colección completa desde la terminal y muestra qué paso falla
Taller: ejecutar con curl curl/taller.sh, todo o hasta el módulo que elijas
Taller: ejecutar con R r/taller.R, todo o hasta el módulo que elijas
Validar con el validador oficial de HL7 herramientas/validar.sh
Actualizar pasos, fichas y colección de Postman herramientas/actualizar.py
Sitio web: vista previa El sitio en http://127.0.0.1:8000

Módulos

El taller tiene tres niveles y 19 módulos, que se siguen en orden.

Nivel básico

Módulo Recursos Aprendes a...
01 Fundamentos CapabilityStatement, OperationOutcome Qué es FHIR, los tipos de datos, la cardinalidad, la API REST y los dos tipos de error
02 Patient Patient Construir un paciente paso a paso; crear, leer, buscar, actualizar y ver el historial
03 Transacciones Bundle transaction Enviar varios recursos a la vez, todo o nada, sin duplicados
04 Profesionales y organizaciones Practitioner, Organization Modelar a la médica y la jerarquía de establecimientos
05 Diagnóstico y encuentro Condition, Encounter Codificar con CIE-10 y SNOMED CT y traer recursos con _include
06 Observaciones Observation Signos vitales con LOINC y UCUM, y los tipos de value[x]

Nivel intermedio

Módulo Recursos Aprendes a...
07 Antecedentes AllergyIntolerance, MedicationStatement, FamilyMemberHistory Registrar alergias, medicación habitual y antecedentes familiares
08 Vacunación Immunization Registrar vacunas aplicadas y diferidas, con lote y dosis del esquema
09 Documentos clínicos Composition, Bundle document Crear un documento autocontenido e inmutable
10 Órdenes y derivación Location, PractitionerRole, ServiceRequest Pedir estudios, derivar y cerrar el ciclo orden → resultado con _revinclude
11 Anatomía patológica BodyStructure, Specimen, DiagnosticReport Registrar una biopsia, corregir resultados y emitir un informe
12 Plan y consentimiento CareTeam, Goal, CarePlan, Consent Registrar el comité de tumores, sus metas, el plan y el consentimiento informado
13 Procedimientos Procedure Registrar una cirugía con su motivo y resultado
14 Citas Schedule, Slot, Appointment, AppointmentResponse Agendar, confirmar, cumplir y cancelar citas, y entender la caché del servidor
15 Medicamentos MedicationRequest, MedicationAdministration Prescribir, administrar y suspender un tratamiento
16 Seguimiento Questionnaire, QuestionnaireResponse Definir y responder un cuestionario, extraer datos y ver todo con $everything

Nivel avanzado

Módulo Recursos Aprendes a...
17 Búsquedas avanzadas y versiones — Tipos de parámetros, prefijos, modificadores, búsquedas encadenadas e inversas (_has), paginación, versiones y If-Match
18 Terminologías y perfiles CodeSystem, ValueSet, StructureDefinition $lookup, $validate-code, $expand, $subsumes; escribir un perfil y validar con $validate
19 Resumen del paciente (IPS) Composition IPS, Bundle document Armar el IPS de Luis, usar $document y validar contra la guía oficial IPS

El caso

Luis Alberto Paredes Cevallos, 46 años, nacido en Riobamba y residente en Quito, consulta en el Hospital General Docente Ejemplo por dolor abdominal, náuseas y diarrea. La Dra. Andrea Salazar diagnostica una intoxicación alimentaria y, en la anamnesis, registra su alergia a la penicilina, el losartán que toma por hipertensión y un dato importante: su madre tuvo cáncer de mama. Como Luis tiene fiebre, las vacunas se difieren; dos semanas después recibe la de la influenza y el refuerzo de Td.

En abril, Luis se palpa un nódulo en la mama izquierda. La ecografía es sospechosa y una biopsia confirma un carcinoma ductal infiltrante con receptor de estrógeno positivo. El comité de tumores define el plan: cirugía, quimioterapia con doxorrubicina y hormonoterapia con tamoxifeno. Los cuestionarios de seguimiento muestran que el tamoxifeno le provoca sofocos y dolor articular, y se suspende. En febrero de 2026, antes de viajar, Luis recibe su resumen internacional del paciente (IPS).

Fecha Qué pasa Módulos
20-mar-2025 Consulta: diagnóstico, signos vitales, antecedentes, vacunas diferidas 02 a 08
03-abr-2025 Vacunatorio: influenza y Td 08
22 a 28-abr-2025 Nódulo en la mama: ecografía BI-RADS 4, orden de biopsia y derivación a oncología 10
06 a 13-may-2025 Biopsia, informe de patología y diagnóstico de cáncer 11
20 y 27-may-2025 Comité de tumores: plan, metas y consentimiento informado 12
10-jun-2025 Mastectomía parcial 13
jul-2025 Citas de quimioterapia; el ciclo 2 se cancela por neutropenia 14
02-jul-2025 Primer ciclo de doxorrubicina 15
15-oct-2025 → feb-2026 Tamoxifeno, suspendido por intolerancia 15
oct-2025 y ene-2026 Cuestionarios de seguimiento: aparecen los sofocos y el dolor articular 16
15-feb-2026 Resumen internacional del paciente (IPS) para su viaje 19

Así se enlazan los recursos que crearás:

flowchart LR
  P([Patient<br/>Luis Paredes])
  Dr([Practitioner<br/>Dra. Salazar])
  H([Organization<br/>Hospital]) -->|partOf| Red([Organization<br/>Red de servicios])
  E[Encounter<br/>consulta] --> P
  E --> Dr
  E --> H
  E -->|diagnosis| C1[Condition<br/>intoxicación]
  Al[AllergyIntolerance<br/>penicilina] --> P
  MS[MedicationStatement<br/>losartán] --> P
  FH[FamilyMemberHistory<br/>madre y padre] --> P
  Im[Immunization<br/>influenza y Td] --> P
  Im --> En([Practitioner<br/>enfermera])
  SV[Observation<br/>signos vitales] --> E
  Doc[Composition<br/>nota de signos vitales] --> SV
  BS[BodyStructure<br/>tumor] --> P
  S[Specimen<br/>biopsia] --> P
  OT[Observation<br/>tamaño del tumor] -->|focus| BS
  OT -->|specimen| S
  RE[Observation<br/>receptor de estrógeno] -->|specimen| S
  DR[DiagnosticReport<br/>patología] -->|result| OT
  DR -->|result| RE
  C2[Condition<br/>cáncer de mama] -->|evidence| DR
  Pr[Procedure<br/>mastectomía] -->|reason| C2
  MR[MedicationRequest<br/>doxorrubicina y tamoxifeno] -->|reason| C2
  MA[MedicationAdministration] -->|request| MR
  SR[ServiceRequest<br/>ecografía y biopsia] --> P
  DR -->|basedOn| SR
  S -->|request| SR
  CP[CarePlan<br/>plan del comité] -->|addresses| C2
  CP --> G[Goal<br/>metas]
  CP --> CT[CareTeam<br/>comité]
  Pr -->|basedOn| CP
  Ap[Appointment<br/>ciclos de quimioterapia] -->|slot| Sl[Slot] -->|schedule| Sc[Schedule]
  QR[QuestionnaireResponse<br/>seguimiento] --> P

Validar tus recursos

Cuando escribas tus propias soluciones, valídalas con el validador oficial de HL7. Necesitas tener Java instalado:

herramientas/validar.sh

El script descarga el validador la primera vez y valida contra FHIR R4 (estructura, cardinalidades, reglas y códigos LOINC, SNOMED CT, CIE-10 y CVX) todas las soluciones y versiones intermedias. Además comprueba que el validador detecte cada error a propósito, y valida contra el perfil del taller (módulo 18) y contra la guía oficial IPS (módulo 19). Agrega --avisos al final para ver también las advertencias. También puedes validar un recurso suelto en https://validator.fhir.org/.

Preguntas frecuentes

¿Por qué el servidor aceptó un recurso con errores? Muchos servidores no validan todo al guardar: descartan elementos desconocidos o aceptan recursos a los que les falta algo obligatorio. El módulo 01 lo explica y cada módulo tiene un error a propósito de cada tipo. Valida siempre tus recursos.

¿Por qué aparece varias veces el mismo paciente? Cada POST crea un recurso nuevo. Si ejecutas el taller dos veces, tendrás dos "Luis". Es un buen motivo para conocer la creación condicional del módulo 03. En HAPI público, una creación idéntica también puede ser rechazada con HAPI-2840. El UUID del módulo 01 resuelve la repetición de ese ejercicio; no hace repetible automáticamente todo el taller. Para practicar de nuevo desde cero, usa una instancia local nueva y conserva los ID de cada ejecución.

¿Los códigos son reales? Sí. LOINC, SNOMED CT, CIE-10 y UCUM son las terminologías reales, y el validador revisa cada código y su nombre. Lo ficticio son las personas, los identificadores y los establecimientos.

¿Los system de los identificadores son oficiales? No. Usamos direcciones didácticas (https://f-slg.github.io/aprende-fhir/sid/...). En un proyecto real se usan las que defina la guía de implementación nacional.

Estructura del repositorio

modulos/NN-tema/README.md       explicación, ejercicios y pistas
modulos/NN-tema/soluciones/     recursos FHIR de solución (JSON)
modulos/NN-tema/pasos/          versiones intermedias de la construcción paso a paso
modulos/NN-tema/errores/        errores a propósito
postman/                        colección completa y entornos de Postman (público y local)
postman/niveles/                la misma colección en tres partes (básico, intermedio, avanzado)
.vscode/                        tareas y extensiones recomendadas para VS Code
r/                              funciones y scripts para R/RStudio
curl/                           script para la terminal
herramientas/pasos.json         lista ordenada de pasos del taller (y errores esperados)
herramientas/construccion.json  qué campos agrega cada paso de la construcción
herramientas/actualizar.py      genera los pasos, las fichas y Postman
herramientas/validar.sh         validación con el validador oficial de HL7
herramientas/sitio/             sitio web (MkDocs Material) a partir de los README

El sitio web (https://f-slg.github.io/aprende-fhir/) se arma con los mismos README y se publica solo en cada cambio. Para verlo en tu equipo: pip install -r herramientas/sitio/requisitos.txt y python3 herramientas/sitio/construir.py --servir.

Si cambias una solución, un paso o un README, ejecuta python3 herramientas/actualizar.py: regenera las versiones intermedias, rellena en los README las fichas (con la cardinalidad y el tipo de la especificación oficial) y los bloques de cada paso, y actualiza la colección de Postman. Después, valida con herramientas/validar.sh.

Contribuir

¿Encontraste un error o tienes una idea para un módulo nuevo? Abre un issue. Las propuestas de mejora son bienvenidas.

Licencia y aviso

  • El contenido del taller (textos, casos y recursos JSON) se distribuye bajo CC BY 4.0: puedes usarlo y adaptarlo citando la fuente.
  • El código (scripts de R, curl y herramientas) se distribuye bajo licencia MIT.

HL7® y FHIR® son marcas registradas de Health Level Seven International. Este taller es un proyecto educativo independiente y no implica afiliación ni aval de HL7.

Autor: Dr. Fabricio Salas Guerrero · LinkedIn · Más proyectos