--- { "title": "Automatice la traducción terminológica con Aidbox TX Engine", "description": "Los sistemas sanitarios intercambian constantemente datos utilizando diferentes conjuntos de códigos, lo que genera miles de traducciones terminológicas diarias. Aidbox TX Engine automatiza este proceso con FHIR ConceptMap y $translate, eliminando hojas de cálculo, scripts personalizados y errores de integración.", "date": "2025-12-08", "author": "Guillermo Rodríguez", "reading-time": "7 minutes", "tags": [ "Terminology", "Aidbox" ] } --- > For the complete documentation index, see [llms.txt](https://www.health-samurai.io/llms.txt). > Use it to discover all available pages before guessing URLs. --- ## La falta de concordancia terminológica Las organizaciones se enfrentan a un reto de integración persistente: la falta de concordancia [terminológica](/blog/introducing-hybrid-terminology-engine) entre sistemas. Las interfaces y los datos HL7v2 heredados, las [implementaciones FHIR](/articles/how-to-create-a-fhir-implementation-guide) modernas, los catálogos internos de procedimientos y los requisitos de terceros crean una compleja red de necesidades de traducción de códigos. Un sistema de laboratorio envía resultados utilizando códigos internos mientras que el HCE requiere LOINC. Radiología utiliza códigos de procedimiento propietarios mientras que la facturación exige CPT. Cada discordancia requiere traducción y, a escala, estas traducciones se multiplican hasta alcanzar miles de conversiones diarias. Los enfoques manuales se rompen rápidamente. Mantener hojas de cálculo con mapeos de códigos se vuelve propenso a errores a medida que varios equipos actualizan diferentes versiones. La lógica de traducción personalizada integrada en los motores de integración crea desafíos técnicos y hace que las actualizaciones sean costosas. Sin una gestión sistemática de mapeos, las organizaciones se enfrentan a fallos de integración, problemas de calidad de los datos y costes de mantenimiento crecientes. El recurso `ConceptMap` de FHIR y la operación `$translate` proporcionan una forma estructurada e interoperable de gestionar los mapeos terminológicos. `ConceptMap` define las relaciones entre conceptos de diferentes sistemas de códigos, creando reglas de mapeo reutilizables y con control de versiones. La operación `$translate` ejecuta estos mapeos de forma programática, permitiendo traducciones automatizadas y consistentes en todo su ecosistema. Este artículo explora cómo utilizar `ConceptMap` y `$translate` para la traducción automatizada de códigos y su comportamiento al operar en un entorno híbrido. ## Comprensión de los conceptos básicos ### ¿Qué es un `ConceptMap`? [ConceptMap](https://build.fhir.org/conceptmap.html) es un recurso FHIR que define cómo se mapean los códigos de un sistema terminológico a los de otro. Piense en él como un diccionario de traducción para códigos médicos — legible por máquina, versionado y compartible. Por ejemplo, su hospital podría tener códigos de laboratorio internos que necesiten mapearse a LOINC para compartirlos externamente: - Código hospitalario: GLU-FAST-001 → LOINC: 1558-6 (glucosa en ayunas) - Código hospitalario: HBA1C-TOTAL → LOINC: 4548-4 (hemoglobina A1c) Cada mapeo incluye un tipo de relación — como «equivalent» (mismo significado) o «source-is-broader-than-target» (el destino es más específico), de modo que los sistemas consumidores entiendan con qué precisión se alinean los códigos. Con estas definiciones establecidas, un `ConceptMap` se convierte en una única fuente de verdad que es reutilizable, con control de versiones y que puede compartirse en toda su organización o incluso publicarse para que otros la utilicen. ### ¿Qué es `$translate`? La operación [$translate](https://build.fhir.org/conceptmap-operation-translate.html) es una API FHIR que utiliza `ConceptMaps` para traducir automáticamente códigos de un sistema a otro. En lugar de escribir lógica de búsqueda personalizada, realiza una simple solicitud HTTP: Entrada: «Traducir el código GLU-FAST-001 de nuestro sistema hospitalario a LOINC» Salida: «Código 1558-6 en LOINC, con relación: equivalent» En segundo plano, la operación gestiona toda la complejidad — encontrando los `ConceptMaps` relevantes, buscando el código, filtrando por sistema de destino y devolviendo resultados estructurados. Como resultado, obtiene traducciones consistentes y fiables sin necesidad de mantener código personalizado en múltiples sistemas. ### Ejemplo sencillo de solicitud/respuesta A continuación se muestra el aspecto de una solicitud de traducción básica: ```javascript POST /fhir/ConceptMap/$translate Content-Type: application/json { "resourceType": "Parameters", "parameter": [ { "name": "sourceCode", "valueCode": "female" }, { "name": "sourceSystem", "valueUri": "http://hl7.org/fhir/administrative-gender" }, { "name": "targetSystem", "valueUri": "http://terminology.hl7.org/CodeSystem/v2-0001" } ] } ``` La respuesta indica si se encontró una traducción (result: true) y proporciona el código de destino: ```javascript { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equal" }, { "name": "concept", "valueCoding": { "system": "http://terminology.hl7.org/CodeSystem/v2-0001", "code": "F", "display": "F" } }, { "name": "source", "valueUri": "http://hl7.org/fhir/ConceptMap/cm-administrative-gender-v2" } ] } ] } ``` ## Múltiples coincidencias En cuanto comience a utilizar `ConceptMap` en escenarios del mundo real, observará que algunos códigos aparecen en múltiples contextos de mapeo. Esto es especialmente frecuente con códigos de estado genéricos o conceptos administrativos que son reutilizados por diferentes recursos FHIR e IGs. En tales casos, `$translate` se comporta de forma predecible: en lugar de elegir el «mejor» mapeo, devuelve todas las coincidencias relevantes para que los clientes puedan decidir cómo gestionarlas. El uso más básico de `$translate` se produce cuando se intenta encontrar coincidencias de mapeo para una codificación. Los usuarios pueden especificar únicamente el sistema y el código, y translate es capaz de localizar los `ConceptMaps` aplicables y las entradas coincidentes. Ese es el caso del ejemplo anterior. Puede haber situaciones en las que el concepto que se está traduciendo coincida con mapeos definidos en diferentes sistemas de códigos. Suponiendo que tenemos múltiples `ConceptMaps` en nuestra instancia de Aidbox, incluyendo el mapeo para `http://hl7.org/fhir/event-status|completed`, obtenemos todas las coincidencias procedentes de los diferentes `ConceptMaps`. **Solicitud** ```javascript POST /fhir/ConceptMap/$translate Content-Type: application/json { "resourceType": "Parameters", "parameter": [ { "name": "sourceCode", "valueCode": "completed" }, { "name": "sourceSystem", "valueUri": "http://hl7.org/fhir/event-status" } ] } ``` ```javascript { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "http://hl7.org/fhir/resource-status", "code": "complete", "display": "complete" } }, { "name": "source", "valueUri": "http://hl7.org/fhir/ConceptMap/sc-clinicalimpression-status" } ] }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "http://hl7.org/fhir/resource-status", "code": "complete", "display": "complete" } }, { "name": "source", "valueUri": "http://hl7.org/fhir/ConceptMap/sc-event-status" } ] }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "http://hl7.org/fhir/resource-status", "code": "complete", "display": "complete" } }, { "name": "source", "valueUri": "http://hl7.org/fhir/ConceptMap/sc-immunization-status" } ] } ] } ``` ## ConceptMap conocido ConceptMap define grupos de mapeos. Cada grupo tiene un sistema `source` y un sistema `target` que representan, respectivamente, el sistema de origen donde está definido el código a mapear y el sistema de destino donde se mapeará el concepto. En algunos casos, ya sabe qué `ConceptMap` desea utilizar. Quizás esté implementando un perfil específico o siguiendo las reglas de mapeo de un IG particular. En lugar de depender de una búsqueda a nivel de sistema, puede indicar a `$translate` que utilice un `ConceptMap` único y conocido. Esto reduce el alcance de la traducción y garantiza resultados predecibles y específicos al contexto — especialmente valioso cuando múltiples `ConceptMaps` definen mapeos similares. **Solicitud** ```javascript POST /fhir/ConceptMap/$translate Content-Type: application/json { "resourceType": "Parameters", "parameter": [ { "name": "url", "valueUri": "http://hl7.org/fhir/ConceptMap/sc-composition-status" }, { "name": "sourceCode", "valueCode": "preliminary" }, { "name": "sourceSystem", "valueUri": "http://hl7.org/fhir/composition-status" } ] } ``` El parámetro `url` especifica el `ConceptMap` que se utilizará durante la traducción. Se indica al servidor que utilice ese contenedor de mapeo específico durante la traducción. **Respuesta** ```javascript { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "http://hl7.org/fhir/resource-status", "code": "draft", "display": "draft" } }, { "name": "source", "valueUri": "http://hl7.org/fhir/ConceptMap/sc-composition-status" } ] } ] } ``` ## La ventaja híbrida Crear `ConceptMaps` para las necesidades específicas de su organización, como los códigos internos mapeados a LOINC, tiene todo el sentido. Usted conoce sus códigos, controla los mapeos y puede actualizarlos según sea necesario. Pero crear todos los `ConceptMaps` posibles no es realista. De forma similar a los sistemas de códigos externos o estándar, existen `ConceptMaps` que definen datos de traducción para escenarios comunes. Veamos algunos ejemplos: - Códigos administrativos FHIR → HL7 V2 - Todos los ConceptMaps de US Core - ICD-10 → SNOMED CT - Mapas regionales y específicos por especialidad Aquí es donde brilla el enfoque híbrido de Aidbox. Aidbox comprueba primero sus `ConceptMaps` locales. Si se encuentra una traducción, la devuelve inmediatamente, de forma rápida y local. Si no se encuentra ninguna traducción y no existe ningún `ConceptMap` local para ese sistema de origen, Aidbox delega automáticamente la traducción al [servidor de terminología externo](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/hybrid#external-terminology-servers) configurado (como tx.health-samurai.io). Esto significa que obtiene: - Sus mapeos personalizados (mantenidos por usted, utilizados primero) - Mapeos estándar (mantenidos externamente, accedidos automáticamente) - Sin duplicación (no necesita recrear los mapeos estándar) **Solicitud** ```javascript POST /fhir/ConceptMap/$translate Content-Type: application/json { "resourceType": "Parameters", "parameter": [ { "name": "sourceCode", "valueCode": "D" }, { "name": "sourceSystem", "valueUri": "http://hl7.org/fhir/us/vr-common-library/CodeSystem/codesystem-ije-vr" }, { "name": "targetSystem", "valueUri": "http://snomed.info/sct" } ] } ``` **Respuesta** ```javascript { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "match", "part": [ { "name": "equivalence", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "http://snomed.info/sct", "code": "434651000124107" } }, { "name": "source", "valueString": "http://hl7.org/fhir/us/vrdr/ConceptMap/CertifierTypesCM" } ] }, { "name": "match", "part": [ { "name": "equivalence", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "http://snomed.info/sct", "code": "449951000124101" } }, { "name": "source", "valueString": "http://hl7.org/fhir/us/vrdr/ConceptMap/MethodOfDispositionCM" } ] } ] } ``` ## Traducción con ConceptMap en Aidbox Aidbox introdujo `ConceptMap` en la [versión 2508](https://www.health-samurai.io/docs/aidbox/overview/release-notes#august-2025-2508), con soporte para la operación `$translate`; consulte el [registro de capacidades](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/capabilities). Si desea probarlo de forma local, comience ejecutando Aidbox siguiendo la [guía para ejecutar Aidbox de forma local](https://www.health-samurai.io/docs/aidbox/getting-started/run-aidbox-locally). **Preparar el recurso de mapeo local** Abra la [consola REST](http://localhost:8080/ui/console#/rest) de Aidbox y envíe: ```javascript PUT /fhir/ConceptMap/cm1 Content-Type: application/json { "resourceType": "ConceptMap", "id": "cm1", "url": "http://hl7.org/fhir/ConceptMap/sc-clinicalimpression-status-TEST", "version": "0.1.0", "status": "active", "group": [ { "source": "http://hl7.org/fhir/event-status|5.0.0", "target": "http://hl7.org/fhir/resource-status", "element": [ { "code": "entered-in-error", "target": [ { "code": "error", "equivalence": "equivalent" } ] }, { "code": "preparation", "target": [ { "code": "planned", "equivalence": "equivalent" } ] }, { "code": "in-progress", "target": [ { "code": "active", "equivalence": "equivalent" } ] }, { "code": "on-hold", "target": [ { "code": "suspended", "equivalence": "equivalent" } ] }, { "code": "stopped", "target": [ { "code": "failed", "equivalence": "equivalent" } ] }, { "code": "completed", "target": [ { "code": "complete", "equivalence": "equivalent" } ] }, { "code": "not-done", "target": [ { "code": "abandoned", "equivalence": "equivalent" } ] }, { "code": "unknown", "target": [ { "code": "unknown", "equivalence": "equivalent" } ] } ] } ] } ``` **Ejecutar la operación $translate de ConceptMap** ```javascript POST /fhir/ConceptMap/$translate Content-Type: application/json { "resourceType": "Parameters", "parameter": [ { "name": "url", "valueUri": "http://hl7.org/fhir/ConceptMap/sc-clinicalimpression-status-TEST" }, { "name": "sourceCode", "valueCode": "completed" }, { "name": "sourceSystem", "valueUri": "http://hl7.org/fhir/event-status" }, { "name": "sourceVersion", "valueString": "5.0.0" } ] } ``` **Respuesta** ```javascript { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "match", "part": [ { "name": "relationship", "valueCode": "equivalent" }, { "name": "concept", "valueCoding": { "system": "http://hl7.org/fhir/resource-status", "code": "complete", "display": "complete" } }, { "name": "source", "valueUri": "http://hl7.org/fhir/ConceptMap/sc-clinicalimpression-status-TEST" } ] } ] } ``` Inicie su instancia de Aidbox y automatice la traducción terminológica al estilo FHIR. Deje de escribir código personalizado de búsqueda y traducción. Véase también: - [Introducción al motor de Terminology híbrido](https://www.health-samurai.io/articles/introducing-hybrid-terminology-engine) - [Aidbox TX Engine - ConceptMap](https://www.health-samurai.io/docs/aidbox/terminology-module/fhir-terminology/conceptmap) - [Aidbox TX Engine - Modo híbrido](https://www.health-samurai.io/docs/aidbox/terminology-module/aidbox-terminology-module/hybrid) Véase también: [Categorías residuales en FHIR Terminology](/blog/residual-categories-in-fhir-terminology).