Conectando tu HCE a una API de extracción de laboratorio

Integrar una API de extracción de datos de laboratorio con un sistema de Historia Clínica Electrónica (HCE) existente es un proyecto que requiere planificación cuidadosa en tres dimensiones: técnica, organizativa y regulatoria. Esta guía proporciona un recorrido práctico por las decisiones de diseño, los patrones de integración y las trampas comunes que los equipos de informática clínica deben considerar al conectar una API como MedExtract con su infraestructura de HCE.

Patrones de integración

Existen tres patrones principales para integrar una API de extracción con un HCE. La elección depende de la arquitectura existente, el volumen de documentos y los requisitos de latencia.

Patrón 1: integración directa punto a punto

En este patrón, el HCE llama directamente a la API de extracción cuando recibe un documento nuevo. Es el patrón más simple pero también el más acoplado.

Usuario sube PDF → HCE → API MedExtract → HCE almacena resultados

Ventajas: simplicidad, baja latencia, implementación rápida. Desventajas: acoplamiento fuerte, sin tolerancia a fallos de la API, el HCE debe gestionar el flujo asíncrono si la extracción tarda más de unos segundos.

Este patrón funciona bien para volúmenes bajos (menos de 50 informes diarios) y cuando el HCE tiene capacidad de realizar llamadas HTTP salientes.

Patrón 2: integración mediante cola de mensajes

Un middleware de integración (integration engine) recibe los documentos del HCE, los envía a la API de extracción y devuelve los resultados al HCE. Este patrón desacopla ambos sistemas.

HCE → Cola de mensajes → Worker → API MedExtract → Cola → HCE

Ventajas: desacoplamiento, tolerancia a fallos, reintentos automáticos, escalabilidad horizontal. Desventajas: mayor complejidad, latencia adicional, infraestructura de mensajería necesaria.

Este es el patrón recomendado para volúmenes medios y altos (más de 50 informes diarios). Los motores de integración sanitaria como Mirth Connect, Rhapsody o Iguana implementan este patrón de forma nativa.

Patrón 3: integración FHIR nativa

Si el HCE soporta FHIR R4 de forma nativa, la integración puede realizarse íntegramente a través de recursos FHIR. La API de extracción produce un Bundle FHIR que se envía directamente al endpoint FHIR del HCE.

Documento → API MedExtract → Bundle FHIR → FHIR Server del HCE

Ventajas: estandarización total, portabilidad, conformidad con EEDS. Desventajas: requiere que el HCE tenga un servidor FHIR operativo, lo cual no siempre es el caso.

Este patrón es ideal para organizaciones con infraestructura FHIR madura y es el modelo al que el ecosistema sanitario europeo convergerá con la implementación del EEDS.

Flujo de datos detallado

Recepción del documento

El primer paso es la captura del documento. Los informes de laboratorio pueden llegar al HCE por múltiples canales:

• Escáner integrado: el personal sanitario escanea el informe en papel directamente desde la interfaz del HCE.
• Carga manual: el usuario sube un archivo PDF o imagen a través de un formulario web.
• Correo electrónico: un buzón monitorizado recibe informes de laboratorios externos y los redirige al sistema.
• Integración HL7: el laboratorio envía un mensaje HL7 v2 con el informe adjunto como documento embebido.
• FHIR DocumentReference: el laboratorio publica un recurso DocumentReference con el informe como attachment.

Envío a la API de extracción

Una vez capturado el documento, se envía a la API de MedExtract para su procesamiento. La llamada básica es una solicitud HTTP POST multipart:

import httpx

async def send_to_extraction(
    file_bytes: bytes,
    filename: str,
    content_type: str,
) -> dict:
    """Envía un documento a la API de MedExtract."""
    async with httpx.AsyncClient(timeout=60.0) as client:
        response = await client.post(
            "https://api.medextract.io/v1/extract",
            headers={
                "Authorization": f"Bearer {API_KEY}",
            },
            files={
                "file": (filename, file_bytes, content_type),
            },
            data={
                "output_format": "fhir_bundle",
                "include_confidence": "true",
                "language": "es",
            },
        )
        response.raise_for_status()
        return response.json()

Procesamiento de la respuesta

La API devuelve los resultados estructurados que incluyen:

• Datos del paciente identificados (nombre, ID, fecha de nacimiento)
• Datos del laboratorio emisor
• Fecha del informe
• Lista de resultados con código LOINC, valor, unidad, rango de referencia e indicador de anormalidad
• Puntuación de confianza global y por resultado individual
• Opcionalmente, un Bundle FHIR listo para importación

Reconciliación con el paciente

Antes de almacenar los resultados en el HCE, es necesario reconciliar la identidad del paciente extraída del informe con el paciente registrado en el HCE. Este paso es crítico para evitar almacenar resultados en la historia clínica incorrecta.

La reconciliación puede realizarse mediante:

• Identificador exacto: si el informe contiene el número de historia clínica del HCE, el matching es directo.
• Datos demográficos: comparación de nombre, fecha de nacimiento y otros identificadores.
• MPI (Master Patient Index): consulta al índice maestro de pacientes de la organización.
• Confirmación manual: en caso de ambigüedad, un operador confirma la asociación.

def reconcile_patient(
    extracted_name: str | None,
    extracted_id: str | None,
    extracted_dob: str | None,
    ehr_client: EHRClient,
) -> str | None:
    """Reconcilia el paciente extraído con el registro del HCE."""
    # Intento 1: búsqueda por identificador exacto
    if extracted_id:
        patient = ehr_client.find_patient_by_id(extracted_id)
        if patient:
            return patient.id

    # Intento 2: búsqueda por datos demográficos
    if extracted_name and extracted_dob:
        candidates = ehr_client.search_patients(
            name=extracted_name,
            birthdate=extracted_dob,
        )
        if len(candidates) == 1:
            return candidates[0].id

    # Sin coincidencia unívoca: requiere revisión manual
    return None

Detección de duplicados

Los informes de laboratorio pueden llegar por múltiples canales (fax, correo, portal del laboratorio), lo que puede generar duplicados. El sistema debe detectar y gestionar duplicados antes de almacenar los resultados:

• Comparar la combinación de laboratorio + fecha + lista de pruebas con resultados existentes
• Calcular un hash del contenido del documento para detectar documentos idénticos
• Comprobar si ya existe un DiagnosticReport FHIR con el mismo identificador externo

Almacenamiento en el HCE

Los resultados validados y reconciliados se almacenan en el HCE. Dependiendo de la arquitectura del HCE, esto puede implicar:

• Inserción FHIR: enviar el Bundle FHIR al servidor FHIR del HCE mediante una transacción POST.
• Inserción HL7 v2: generar un mensaje ORU^R01 con los resultados y enviarlo al motor de interfaces del HCE.
• API propietaria: utilizar la API específica del HCE para crear observaciones de laboratorio.
• Base de datos directa: en casos excepcionales, insertar directamente en las tablas de resultados del HCE (no recomendado).

Gestión de errores y casos especiales

Resultados de baja confianza

Cuando la API de extracción reporta baja confianza en un resultado, el sistema debe enrutar ese caso a una cola de revisión humana en lugar de insertarlo automáticamente en el HCE. La interfaz de revisión debe mostrar el documento original junto con los resultados extraídos, permitiendo al operador corregir o confirmar cada campo.

Informes parcialmente procesados

Si la API no puede procesar algunas páginas o secciones del informe (por ejemplo, por calidad de imagen insuficiente), el sistema debe almacenar los resultados procesados exitosamente y marcar el informe como "parcialmente procesado", generando una alerta para que un operador revise las secciones no procesadas.

Formatos de informe no reconocidos

Algunos informes de laboratorio pueden tener formatos que el sistema de extracción no reconoce. En estos casos, el flujo debe degradarse de forma elegante: el documento se almacena como adjunto del paciente en el HCE y se marca para procesamiento manual, sin bloquear el flujo general.

Seguridad y cumplimiento

Autenticación y autorización

La comunicación entre el HCE y la API de extracción debe estar protegida con:

• TLS 1.2+: cifrado en tránsito obligatorio.
• API Key / OAuth 2.0: autenticación del cliente.
• IP whitelisting: restricción de acceso por IP de origen (recomendado en entornos hospitalarios).
• Rate limiting: protección contra uso abusivo o accidental.

Trazabilidad

Cada operación de extracción debe generar un registro de auditoría que incluya:

• Identificador del documento de entrada
• Timestamp de la solicitud y la respuesta
• Identificador de la sesión de usuario que inició el proceso
• Resultado de la extracción (éxito, fallo parcial, error)
• Resultado de la reconciliación de paciente
• Resultado del almacenamiento en el HCE

Este registro de auditoría es un requisito del RGPD y una buena práctica de gobernanza de datos sanitarios.

Contrato de encargo de tratamiento

La integración con una API externa para procesar datos de salud requiere un contrato de encargo de tratamiento conforme al Art. 28 del RGPD. Este contrato debe establecer las responsabilidades de cada parte, las medidas de seguridad aplicables y las condiciones de retención y supresión de datos.

Pruebas y validación

Fase de pruebas

Antes de poner la integración en producción, es esencial un periodo de pruebas que cubra:

1. Pruebas unitarias: verificar que cada componente de la integración funciona correctamente de forma aislada.
2. Pruebas de integración: verificar el flujo completo desde la carga del documento hasta el almacenamiento en el HCE.
3. Pruebas de carga: verificar que el sistema maneja el volumen esperado sin degradación.
4. Pruebas de fallo: verificar el comportamiento cuando la API no está disponible, cuando la red falla o cuando el HCE rechaza la inserción.

Validación paralela

La mejor práctica es ejecutar el sistema en modo paralelo durante 1-3 meses: los informes se procesan tanto manual como automáticamente, y los resultados se comparan para medir la tasa de concordancia. Una tasa de concordancia superior al 98% en los campos principales (LOINC, valor, unidad) indica que el sistema está listo para producción.

Monitorización continua

En producción, el sistema debe monitorizarse continuamente para detectar degradaciones de rendimiento:

• Tasa de éxito de extracciones
• Latencia media de procesamiento
• Porcentaje de resultados enviados a revisión humana
• Tasa de concordancia con entradas manuales (si existe flujo paralelo)

Conclusión

Conectar un HCE a una API de extracción de laboratorio como MedExtract es un proyecto con un retorno claro: automatiza un proceso manual intensivo en tiempo y propenso a errores, y habilita la interoperabilidad que regulaciones como el EEDS están haciendo obligatoria. La clave del éxito es elegir el patrón de integración adecuado para la arquitectura existente, implementar una reconciliación de pacientes robusta, y mantener la trazabilidad y la seguridad en cada paso del flujo de datos.

Para organizaciones que están comenzando, el tutorial de pipeline en Python proporciona un punto de partida funcional que puede adaptarse a las necesidades específicas de cada HCE.