Guía de integración de APIs sanitarias

Las APIs (Application Programming Interfaces) son el tejido conectivo del ecosistema sanitario digital moderno. Permiten que sistemas dispares — historias clínicas electrónicas, sistemas de información de laboratorio, plataformas de imagen, aplicaciones de pacientes y herramientas de análisis — intercambien datos de forma programática, segura y estandarizada. Sin embargo, la integración de APIs en sanidad presenta complejidades únicas derivadas de la sensibilidad de los datos, los requisitos regulatorios y la diversidad de estándares del sector.

Esta guía cubre de forma exhaustiva los conceptos, estándares, patrones de diseño y mejores prácticas para integrar APIs sanitarias, con especial atención a las APIs de datos de laboratorio y al estándar FHIR.

Fundamentos de las APIs sanitarias

REST como paradigma dominante

La mayoría de las APIs sanitarias modernas siguen la arquitectura REST (Representational State Transfer). REST utiliza los verbos HTTP estándar (GET, POST, PUT, DELETE) para operar sobre recursos identificados por URLs. En el contexto sanitario, los recursos son entidades clínicas: pacientes, observaciones, informes diagnósticos, medicaciones, etc.

Las APIs RESTful sanitarias operan sobre JSON como formato de serialización principal, aunque algunas APIs legacy todavía utilizan XML. La transición hacia JSON ha sido acelerada por FHIR, que adoptó JSON como formato primario junto con XML.

FHIR R4: el estándar de facto

FHIR (Fast Healthcare Interoperability Resources) R4 se ha convertido en el estándar de facto para APIs sanitarias. Define un conjunto de recursos (Patient, Observation, DiagnosticReport, Bundle, etc.) con una estructura JSON estandarizada, operaciones RESTful predefinidas y un modelo de búsqueda consistente.

Para datos de laboratorio, los recursos clave de FHIR son:

• Observation: representa un resultado individual de prueba (valor, unidad, código LOINC, rango de referencia).
• DiagnosticReport: agrupa las observaciones de un informe completo.
• Bundle: empaqueta múltiples recursos en una transacción atómica.
• Patient: identifica al sujeto de las observaciones.

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "resource": {
        "resourceType": "DiagnosticReport",
        "status": "final",
        "code": {
          "coding": [{
            "system": "http://loinc.org",
            "code": "11502-2",
            "display": "Laboratory report"
          }]
        },
        "result": [
          {"reference": "Observation/obs-1"},
          {"reference": "Observation/obs-2"}
        ]
      },
      "request": {"method": "POST", "url": "DiagnosticReport"}
    }
  ]
}

HL7 v2: el estándar heredado

Antes de FHIR, HL7 v2 era el estándar dominante para el intercambio de datos sanitarios. Millones de mensajes HL7 v2 se intercambian diariamente en hospitales de todo el mundo. El formato es un protocolo de mensajería basado en texto con delimitadores de segmentos, campos y componentes (pipes y carets).

Para datos de laboratorio, el mensaje HL7 v2 relevante es el ORU^R01 (Observational Report Unsolicited), que contiene segmentos OBX (Observation) con los resultados de las pruebas.

Muchas integraciones sanitarias requieren manejar tanto HL7 v2 como FHIR, traduciendo entre ambos formatos según las capacidades del sistema receptor. Los motores de integración sanitaria (Mirth Connect, Rhapsody) facilitan esta traducción.

Autenticación y autorización

OAuth 2.0 y SMART on FHIR

El marco de autenticación estándar para APIs sanitarias es OAuth 2.0, con la extensión SMART on FHIR para el contexto clínico. SMART (Substitutable Medical Applications, Reusable Technologies) on FHIR define flujos de autorización que permiten a las aplicaciones acceder a datos sanitarios con el consentimiento del usuario y en el contexto de una sesión clínica.

Los flujos OAuth 2.0 más utilizados en sanidad son:

• Authorization Code Flow: para aplicaciones web que actúan en nombre de un usuario. El usuario se autentica en el servidor de autorización del HCE y autoriza a la aplicación a acceder a recursos específicos.
• Client Credentials Flow: para comunicación servidor a servidor sin contexto de usuario. La aplicación se autentica con sus propias credenciales (client_id y client_secret) y accede a recursos según los permisos asignados.
• SMART Launch: un flujo específico de SMART on FHIR que integra la autenticación con el contexto clínico del HCE, proporcionando automáticamente el paciente en contexto, el profesional sanitario y el encuentro.

import httpx

async def get_access_token(
    token_url: str,
    client_id: str,
    client_secret: str,
    scope: str = "system/*.read",
) -> str:
    """Obtiene un token OAuth 2.0 mediante Client Credentials."""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            token_url,
            data={
                "grant_type": "client_credentials",
                "client_id": client_id,
                "client_secret": client_secret,
                "scope": scope,
            },
        )
        response.raise_for_status()
        return response.json()["access_token"]

API Keys

Para APIs más simples o para comunicación entre sistemas de confianza dentro de la misma red, las API Keys siguen siendo un mecanismo válido. La clave se transmite como cabecera HTTP Authorization: Bearer <key> y el servidor la valida contra un registro de claves autorizadas.

Las API Keys son adecuadas para:

• Integraciones servidor a servidor en entornos controlados
• APIs de procesamiento de datos (como MedExtract) donde no hay contexto de usuario
• Entornos de desarrollo y pruebas

Mutual TLS (mTLS)

Para comunicaciones de alta seguridad entre sistemas sanitarios, el mutual TLS añade autenticación bidireccional: no solo el cliente verifica la identidad del servidor (como en TLS estándar), sino que el servidor también verifica la identidad del cliente mediante un certificado X.509. Este mecanismo es utilizado en infraestructuras como MyHealth@EU para la comunicación entre puntos nacionales de contacto.

Diseño de APIs sanitarias

Versionado

Las APIs sanitarias deben versionarse para permitir la evolución sin romper integraciones existentes. Los dos enfoques más comunes son:

• Versionado por URL: /v1/extract, /v2/extract. Claro y explícito, pero requiere mantener múltiples endpoints.
• Versionado por cabecera: Accept: application/fhir+json; fhirVersion=4.0. Más elegante pero menos visible en la documentación.

La recomendación para APIs sanitarias es el versionado por URL para APIs propietarias y el versionado por cabecera FHIR para endpoints FHIR estándar.

Paginación

Las APIs que devuelven colecciones de recursos deben implementar paginación para evitar respuestas excesivamente grandes. FHIR define un mecanismo de paginación estándar basado en enlaces next dentro del Bundle de búsqueda:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 150,
  "link": [
    {"relation": "self", "url": "...?_count=10&_offset=0"},
    {"relation": "next", "url": "...?_count=10&_offset=10"}
  ],
  "entry": [...]
}

Gestión de errores

Las APIs sanitarias deben devolver códigos de estado HTTP semánticos y mensajes de error estructurados. FHIR define el recurso OperationOutcome para comunicar errores:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "invalid",
    "diagnostics": "El código LOINC proporcionado no es válido"
  }]
}

Los códigos HTTP más relevantes para APIs sanitarias incluyen:

• 200 OK: operación exitosa
• 201 Created: recurso creado exitosamente
• 400 Bad Request: solicitud mal formada
• 401 Unauthorized: autenticación requerida
• 403 Forbidden: autenticación correcta pero sin permisos suficientes
• 404 Not Found: recurso no encontrado
• 409 Conflict: conflicto de versión (importante para actualizaciones concurrentes)
• 422 Unprocessable Entity: datos válidos sintácticamente pero no semánticamente
• 429 Too Many Requests: rate limiting
• 500 Internal Server Error: error del servidor

Rate limiting

Las APIs sanitarias deben implementar rate limiting para proteger tanto al servidor como a los clientes de uso excesivo. Las cabeceras estándar para comunicar los límites son:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 750
X-RateLimit-Reset: 1709294400
Retry-After: 60

En entornos sanitarios, el rate limiting debe considerar la criticidad clínica: las solicitudes de datos urgentes (resultados críticos de laboratorio) pueden necesitar una prioridad más alta que las consultas analíticas.

Patrones de integración avanzados

Webhooks para notificaciones en tiempo real

Los webhooks permiten que la API notifique al sistema receptor cuando ocurre un evento, en lugar de requerir polling constante. Para datos de laboratorio, un webhook podría notificar cuando un informe ha sido procesado y los resultados están disponibles:

{
  "event": "extraction.completed",
  "timestamp": "2026-02-05T10:30:00Z",
  "data": {
    "extraction_id": "ext-12345",
    "status": "success",
    "results_count": 22,
    "confidence": 0.97,
    "bundle_url": "https://api.medextract.io/v1/bundles/ext-12345"
  }
}

FHIR Subscriptions

FHIR R4 define un mecanismo de suscripción que permite a los clientes recibir notificaciones cuando los recursos que les interesan cambian. Un sistema de HCE podría suscribirse a nuevas Observations de laboratorio para un paciente específico:

{
  "resourceType": "Subscription",
  "status": "active",
  "criteria": "Observation?category=laboratory&patient=Patient/123",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://mi-hce.ejemplo.com/webhooks/fhir",
    "payload": "application/fhir+json"
  }
}

Procesamiento asíncrono

Las operaciones de extracción de documentos pueden tardar varios segundos, lo que excede las expectativas de latencia de una API síncrona. El patrón asíncrono más común es:

1. El cliente envía el documento y recibe inmediatamente un ID de tarea (202 Accepted).
2. El cliente consulta periódicamente el estado de la tarea (polling) o recibe una notificación por webhook.
3. Cuando la tarea se completa, el cliente recupera los resultados.

# Paso 1: enviar documento
response = await client.post("/v1/extract", files={"file": ...})
task_id = response.json()["task_id"]  # 202 Accepted

# Paso 2: consultar estado (o esperar webhook)
while True:
    status = await client.get(f"/v1/tasks/{task_id}")
    if status.json()["state"] == "completed":
        break
    await asyncio.sleep(2)

# Paso 3: obtener resultados
results = await client.get(f"/v1/tasks/{task_id}/results")

Batch processing

Para organizaciones que procesan grandes volúmenes de informes, las APIs deben soportar procesamiento por lotes (batch). Esto permite enviar múltiples documentos en una sola solicitud y recuperar los resultados de forma agregada, reduciendo la sobrecarga de red y simplificando la gestión de errores.

Interoperabilidad y estándares

Terminologías clínicas

Las APIs sanitarias que manejan datos clínicos deben utilizar terminologías estándar para garantizar la interoperabilidad:

• LOINC: para identificar pruebas de laboratorio y observaciones clínicas.
• SNOMED CT: para codificar hallazgos clínicos, procedimientos y diagnósticos.
• ICD-10: para codificar diagnósticos y motivos de consulta.
• UCUM: para unidades de medida.
• ATC: para medicamentos.

Una API de extracción de datos de laboratorio como MedExtract produce resultados codificados en estas terminologías estándar, eliminando la necesidad de que el integrador realice el mapeo manualmente.

Perfiles de implementación

Los perfiles de implementación FHIR definen restricciones y extensiones sobre los recursos base para adaptarlos a un contexto específico. Para datos de laboratorio en Europa, los perfiles relevantes incluyen:

• IPS (International Patient Summary): el perfil de resumen de paciente que incluye resultados de laboratorio.
• EU Laboratory Result: el perfil europeo para resultados de laboratorio definido por la red eHealth Network.
• Perfiles nacionales: cada estado miembro puede definir perfiles adicionales (por ejemplo, los perfiles españoles de SNOMED CT y LOINC publicados por el Ministerio de Sanidad).

Validación de conformidad

Las APIs sanitarias deben validar que los recursos que producen y consumen son conformes a los perfiles de implementación aplicables. Las herramientas de validación FHIR (como el validador oficial de HL7) verifican:

• Estructura correcta del recurso JSON
• Presencia de campos obligatorios
• Valores de terminología válidos (códigos LOINC existentes, unidades UCUM correctas)
• Conformidad con los perfiles declarados

Seguridad

Cifrado

Toda comunicación de API sanitaria debe estar cifrada con TLS 1.2 o superior. El uso de TLS 1.0/1.1 está desaconsejado por los estándares de seguridad actuales y prohibido por muchas regulaciones sanitarias.

Los datos en reposo (almacenados por la API) deben estar cifrados con AES-256 o un algoritmo equivalente. Las claves de cifrado deben gestionarse mediante un servicio de gestión de claves (KMS) que garantice la rotación periódica y el acceso controlado.

Registro de auditoría

El RGPD y las regulaciones sanitarias exigen un registro de auditoría completo de todos los accesos a datos de salud. Cada llamada a la API debe registrar:

• Identidad del cliente (quién)
• Recurso accedido (qué)
• Operación realizada (cómo)
• Timestamp (cuándo)
• Resultado de la operación (éxito/error)
• Dirección IP de origen

Los registros de auditoría deben ser inmutables (append-only) y conservarse durante el periodo exigido por la regulación aplicable.

Protección contra amenazas comunes

Las APIs sanitarias deben protegerse contra:

• Inyección: validar y sanitizar todas las entradas. Los parámetros de búsqueda FHIR son un vector de inyección potencial.
• Escalada de privilegios: verificar que cada solicitud solo accede a los recursos autorizados para ese cliente/usuario.
• CSRF: las APIs puras (sin cookies de sesión) son inmunes, pero las APIs que soportan sesión de navegador deben implementar tokens CSRF.
• Exfiltración masiva: detectar y bloquear patrones de acceso que sugieran una extracción masiva no autorizada de datos.

Documentación y experiencia del desarrollador

OpenAPI / Swagger

La documentación de APIs sanitarias debe seguir la especificación OpenAPI (Swagger), que define de forma estandarizada los endpoints, parámetros, tipos de datos, códigos de respuesta y modelos de autenticación. Las herramientas de generación de código pueden producir SDKs para múltiples lenguajes a partir de una especificación OpenAPI.

Entornos sandbox

Las APIs sanitarias deben proporcionar un entorno sandbox donde los integradores puedan probar sus integraciones sin riesgo de afectar datos reales. El sandbox debe simular el comportamiento de la API de producción, incluyendo:

• Los mismos endpoints y formato de respuesta
• Datos de prueba realistas pero ficticios
• Simulación de errores y casos límite
• Sin limitaciones de rate limiting restrictivas

SDKs y ejemplos

Proporcionar SDKs oficiales para los lenguajes más utilizados en informática sanitaria (Python, Java, C#, JavaScript) reduce significativamente la barrera de entrada para los integradores. Los ejemplos de código funcionales son más efectivos que la documentación abstracta.

# Ejemplo simplificado de SDK
from medextract import Client

client = Client(api_key="your-key")
result = client.extract("informe.pdf")

for test in result.tests:
    print(f"{test.name} ({test.loinc}): {test.value} {test.unit}")

Monitorización y observabilidad

Métricas clave

Las APIs sanitarias deben monitorizar:

• Latencia p50/p95/p99: los percentiles de latencia revelan la experiencia del usuario real.
• Tasa de errores: porcentaje de solicitudes que devuelven errores 4xx o 5xx.
• Throughput: solicitudes por segundo, para planificación de capacidad.
• Disponibilidad: uptime medido contra los SLAs comprometidos.
• Saturación: uso de CPU, memoria y conexiones de red.

Health checks

Las APIs sanitarias deben exponer un endpoint de health check que permita a los sistemas de monitorización verificar su estado:

GET /health

{
  "status": "healthy",
  "version": "2.1.0",
  "components": {
    "database": "healthy",
    "ocr_engine": "healthy",
    "loinc_matcher": "healthy"
  },
  "uptime_seconds": 864000
}

SLAs en sanidad

Los Service Level Agreements para APIs sanitarias deben considerar la criticidad clínica:

• Disponibilidad: 99.9% o superior para APIs que soportan flujos clínicos.
• Latencia: menos de 30 segundos para extracción de documentos, menos de 200ms para consultas de datos.
• RPO (Recovery Point Objective): pérdida máxima de datos aceptable en caso de fallo.
• RTO (Recovery Time Objective): tiempo máximo para restaurar el servicio tras un fallo.

El futuro de las APIs sanitarias

APIs basadas en IA

Las APIs sanitarias están incorporando cada vez más capacidades de inteligencia artificial: extracción de documentos, NLP clínico, predicción de riesgos y asistencia a la decisión clínica. Estas APIs presentan desafíos adicionales de explicabilidad (el sistema debe poder explicar sus resultados), determinismo (el mismo input debe producir resultados consistentes) y validación clínica.

EHDS y la convergencia europea

El EEDS impulsará la convergencia de las APIs sanitarias hacia estándares comunes en toda Europa. Las APIs que ya implementen FHIR R4 con perfiles europeos estarán mejor posicionadas para operar en el mercado paneuropeo.

APIs en tiempo real

La evolución hacia la medicina personalizada y los dispositivos de monitorización continua está impulsando la demanda de APIs sanitarias en tiempo real, capaces de procesar flujos de datos continuos (streaming) además de solicitudes puntuales. Las tecnologías como WebSockets, Server-Sent Events y gRPC están ganando relevancia en el ecosistema sanitario.

Conclusión

La integración de APIs sanitarias es un campo en el que la excelencia técnica debe combinarse con el rigor regulatorio y la conciencia clínica. Los estándares como FHIR R4, las terminologías como LOINC y SNOMED CT, y los marcos de seguridad como OAuth 2.0 y SMART on FHIR proporcionan los cimientos sobre los que construir integraciones robustas y conformes.

Para las organizaciones que buscan integrar capacidades de extracción de datos de laboratorio, la clave es elegir APIs que sean nativamente conformes con estos estándares. MedExtract está diseñada para producir directamente recursos FHIR R4 con codificación LOINC, lo que simplifica la integración con cualquier sistema sanitario que soporte estos estándares y prepara a la organización para los requisitos del EEDS.

La inversión en una integración bien diseñada se amortiza rápidamente: reduce la complejidad operativa, habilita la interoperabilidad y posiciona a la organización para aprovechar las oportunidades que la digitalización sanitaria europea está creando.