Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # `$questionnaire-package`Operación FHIR para HealthLake La `$questionnaire-package` operación recupera un paquete completo que contiene un cuestionario del FHIR y todas sus dependencias necesarias para procesar y procesar el cuestionario. Esta operación implementa la [Guía de implementación de las plantillas y reglas de documentación (DTR) de Da Vinci](https://hl7.org/fhir/us/davinci-dtr/OperationDefinition-questionnaire-package.html), que permite la representación dinámica de los formularios para los requisitos de documentación en los flujos de trabajo de atención médica. ## Funcionamiento + **Solicitud**: Usted envía los parámetros que identifican los cuestionarios necesarios, junto con la cobertura y el contexto del pedido + **Recuperar**: HealthLake recopila el cuestionario y todas las dependencias (ValueSetsbibliotecas de CQL, etc.) + **Paquete**: Todos los recursos se agrupan en un formato estandarizado + **Responda**: recibirá un paquete completo listo para su procesamiento y recopilación de datos **Casos de uso** + **Documentación de autorización previa**: recopile la información clínica requerida para las solicitudes de autorización previa + **Requisitos de cobertura**: reúna la documentación necesaria para cumplir con los requisitos de cobertura del pagador + **Clinical Data Exchange**: estructura los datos clínicos para enviarlos a los pagadores + **Formularios dinámicos**: renderice cuestionarios con datos de pacientes previamente rellenados y lógica condicional ## Punto de conexión de la API ``` POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package Content-Type: application/fhir+json ``` ## Parámetros de solicitud ### Parámetros de entrada El cuerpo de la solicitud debe contener un recurso de parámetros del FHIR con los siguientes parámetros: | Parámetro | Tipo | Cardinalidad | Description (Descripción) | | --- | --- | --- | --- | | coverage | Cobertura | 1.. \$1 (Obligatorio) | Recurso (s) de cobertura para determinar el miembro y cobertura de la documentación | | questionnaire | canonical | 0.. \$1 | URL canónicas de cuestionarios específicos a devolver (pueden incluir una versión) | | order | Recurso | 0.. \$1 | Solicite recursos (DeviceRequest,, ServiceRequest MedicationRequest, Encuentro, Cita) para establecer el contexto | | changedSince | dateTime | 0.1 | Si está presente, devuelva solo los recursos modificados después de esta marca de tiempo | ### Reglas de validación de parámetros **Debe proporcionarse al menos UNO de los siguientes datos** (además de los obligatorios`coverage`): + Uno o más `questionnaire` canónicos URLs + Uno o más recursos `order` **Combinaciones de solicitudes válidas:** + `coverage` \$1 `questionnaire` + `coverage` \$1 `order` + `coverage` \$1 `questionnaire` \$1 `order` ## Ejemplo de solicitud ``` POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package Content-Type: application/fhir+json Authorization: Bearer { "resourceType": "Parameters", "parameter": [ { "name": "coverage", "resource": { "resourceType": "Coverage", "id": "example-coverage", "status": "active", "beneficiary": { "reference": "Patient/example-patient" }, "payor": [{ "reference": "Organization/example-payer" }], "class": [{ "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/coverage-class", "code": "group" }] }, "value": "12345" }] } }, { "name": "questionnaire", "valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0" }, { "name": "order", "resource": { "resourceType": "ServiceRequest", "id": "example-service-request", "status": "active", "intent": "order", "code": { "coding": [{ "system": "http://www.ama-assn.org/go/cpt", "code": "94660", "display": "Continuous positive airway pressure ventilation (CPAP)" }] }, "subject": { "reference": "Patient/example-patient" } } }, { "name": "changedSince", "valueDateTime": "2024-01-01T00:00:00Z" } ] } ``` ## Formato de las respuestas ### Respuesta correcta (200 OK) La operación devuelve un recurso de parámetros FHIR que contiene uno o más **Package Bundles**. Cada Package Bundle incluye: | Tipo de entrada | Cardinalidad | Description (Descripción) | | --- | --- | --- | | Cuestionario | 1 | El cuestionario que se va a entregar | | QuestionnaireResponse | 0.1.. | Respuesta rellenada previamente o completada parcialmente (si corresponde) | | Library | 0.. \$1 | Bibliotecas CQL que contienen lógica condicional y previa a la población | | ValueSet | 0.. \$1 | Ampliado ValueSets (para opciones de respuesta con menos de 40 expansiones) | **Example Ejemplo de respuesta** ``` { "resourceType": "Parameters", "parameter": [ { "name": "PackageBundle", "resource": { "resourceType": "Bundle", "id": "questionnaire-package-example", "meta": { "profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"] }, "type": "collection", "timestamp": "2024-03-15T10:30:00Z", "entry": [ { "fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy", "resource": { "resourceType": "Questionnaire", "id": "home-oxygen-therapy", "url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy", "version": "2.0", "status": "active", "title": "Home Oxygen Therapy Documentation", "item": [ { "linkId": "1", "text": "Patient diagnosis", "type": "choice", "answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses" } ] } }, { "fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation", "resource": { "resourceType": "Library", "id": "oxygen-prepopulation", "url": "http://example.org/fhir/Library/oxygen-prepopulation", "version": "1.0", "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/library-type", "code": "logic-library" }] }, "content": [{ "contentType": "text/cql", "data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..." }] } }, { "fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses", "resource": { "resourceType": "ValueSet", "id": "oxygen-diagnoses", "url": "http://example.org/fhir/ValueSet/oxygen-diagnoses", "status": "active", "expansion": { "timestamp": "2024-03-15T10:30:00Z", "contains": [ { "system": "http://hl7.org/fhir/sid/icd-10", "code": "J44.0", "display": "COPD with acute lower respiratory infection" }, { "system": "http://hl7.org/fhir/sid/icd-10", "code": "J96.01", "display": "Acute respiratory failure with hypoxia" } ] } } }, { "fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated", "resource": { "resourceType": "QuestionnaireResponse", "id": "example-prepopulated", "questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0", "status": "in-progress", "subject": { "reference": "Patient/example-patient" }, "basedOn": [{ "reference": "ServiceRequest/example-service-request" }], "item": [ { "linkId": "1", "text": "Patient diagnosis", "answer": [{ "valueCoding": { "system": "http://hl7.org/fhir/sid/icd-10", "code": "J44.0", "display": "COPD with acute lower respiratory infection" } }] } ] } } ] } }, { "name": "Outcome", "resource": { "resourceType": "OperationOutcome", "issue": [{ "severity": "information", "code": "informational", "details": { "text": "Successfully retrieved questionnaire package" } }] } } ] } ``` ## Flujo de trabajo operativo **¿Cómo HealthLake procesa su solicitud** Cuando llames`$questionnaire-package`, HealthLake realiza los siguientes pasos: 1. **Identifique al paciente y al pagador**: extraiga el paciente y la organización de seguros a partir de su `coverage` parámetro. 1. **Encuentre el cuestionario correcto**: + **Con `questionnaire`** **el parámetro**: usa la URL canónica que proporcionaste + **Con** el `order` **parámetro**: Coincide con el código del pedido (CPT/HCPCS/LOINC) y el pagador para encontrar el cuestionario correspondiente 1. **Reunir dependencias**: recupera automáticamente todo lo necesario para procesar el cuestionario: + **Bibliotecas CQL**: lógica para preguntas condicionales y previas al rellenado + **ValueSets**- Opciones de respuesta (se amplían automáticamente si hay menos de 40 opciones) + **QuestionnaireResponse**- Cualquier respuesta existente, en curso o completada 1. **Package todo junto**: + Agrupa todos los recursos (cada recurso se incluye solo una vez) + Filtra por `changedSince` marca de tiempo si se proporciona + Añade advertencias en `Outcome` caso de que falte algún recurso **Resultado**: un paquete completo e independiente listo para renderizarse. ## Respuestas de error ### 400: solicitud maligna Se devuelve cuando la validación de la solicitud falla. ``` { "resourceType": "OperationOutcome", "issue": [{ "severity": "error", "code": "required", "details": { "text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'" } }] } ``` ### 4.2.4 Dependencia fallida Se devuelve cuando no se puede recuperar un recurso dependiente. ``` { "resourceType": "OperationOutcome", "issue": [{ "severity": "warning", "code": "not-found", "details": { "text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved" } }] } ``` ### 401 sin autorización Se devuelve cuando faltan credenciales de autenticación o no son válidas. ### 403: prohibido Se devuelve cuando el usuario autenticado no tiene permiso para acceder a los recursos solicitados. ### 406 No es aceptable Se devuelve cuando no se puede proporcionar el tipo de contenido solicitado. ### Conflicto, 409 Se devuelve cuando hay un conflicto de versiones o de simultaneidad. ### 410 Se ha ido Se devuelve cuando el recurso solicitado se ha eliminado permanentemente. ### 429 Demasiadas solicitudes Se devuelve cuando se superan los límites de velocidad. ### 500 Error de servidor interno Se devuelve cuando se produce un error inesperado en el servidor. ### 501 No implementado Se devuelve cuando la operación solicitada aún no está implementada. ## Reglas de validación ### Validación de entradas + `coverage`el parámetro es **obligatorio** (1.. \$1 cardinalidad) + `order`Debe proporcionarse al menos uno de `questionnaire` ellos + Todos los recursos de cobertura deben ser recursos válidos del FHIR + Todos los recursos del pedido deben ser recursos válidos del FHIR + Canonical URLs debe tener el formato correcto + `changedSince`debe ser un DateTime ISO 8601 válido ### QuestionnaireResponse validación + `status`debe ser apropiado (`in-progress`,`completed`,`amended`) + La estructura debe coincidir con el cuestionario al que se hace referencia + `basedOn`debe hacer referencia a los recursos del pedido válidos + `subject`debe hacer referencia a recursos válidos para pacientes ### Deduplicación de recursos + Cada recurso aparece solo una vez en el paquete + Excepción: es posible que se incluyan diferentes versiones del mismo recurso + Los recursos se identifican por su URL y versión canónicas ## Especificaciones de rendimiento | Métrica | Especificación | | --- | --- | | Límite de recuento de recursos | 500 recursos por paquete | | Límite de tamaño del paquete | 5 MB como máximo | ## Permisos necesarios Para utilizar la `$questionnaire-package` operación, asegúrese de que su función de IAM tenga: + `healthlake:QuestionnairePackage`- Para convocar a la operación + `healthlake:ReadResource`- Para recuperar el cuestionario y los recursos dependientes + `healthlake:SearchWithPost`- Para buscar recursos QuestionnaireResponse y recursos relacionados **SMART en FHIR Scopes** **Alcances mínimos requeridos:** + **SMART v1**: `user/Questionnaire.read user/Library.read user/ValueSet.read user/QuestionnaireResponse.read` + **SMART v2**: `user/Questionnaire.rs user/Library.rs user/ValueSet.rs user/QuestionnaireResponse.rs` ## Notas importantes sobre la implementación ### Estrategia de recuperación de recursos **Prioridad de identificación del cuestionario:** + **URL canónica** (si se proporciona el `questionnaire` parámetro): prioridad máxima + **Análisis de pedidos** (si se proporciona `order` el parámetro): + Haga coincidir los códigos de pedido (CPT, HCPCS, LOINC) con las pólizas médicas del pagador + Use el pagador de cobertura para filtrar los cuestionarios específicos del pagador + Tenga en cuenta los códigos de motivo para obtener un contexto adicional ### Resolución de dependencias **Bibliotecas CQL:** + Recuperado a través de la `cqf-library` extensión sobre los recursos del cuestionario + Busca de forma recursiva las bibliotecas dependientes mediante `Library.relatedArtifact` el tipo `depends-on` + Todas las dependencias de la biblioteca están incluidas en el paquete **ValueSets:** + Se expanden automáticamente si contienen menos de 40 conceptos + ValueSets Los más grandes se incluyen sin expansión + ValueSets Se incluyen los recursos referenciados tanto en el cuestionario como en la biblioteca ### QuestionnaireResponse prepoblación La operación puede devolver un QuestionnaireResponse con datos rellenados previamente cuando: + Se encuentra una respuesta ya finalizada o en curso + La lógica CQL de las bibliotecas asociadas puede extraer datos de los registros de los pacientes + La respuesta está vinculada al pedido y la cobertura pertinentes **Criterios de búsqueda para QuestionnaireResponse:** | Parámetro de búsqueda | Ruta FHIR | Description (Descripción) | | --- | --- | --- | | based-on | QuestionnaireResponse.basedOn | Enlaces a ServiceRequest o CarePlan | | patient | QuestionnaireResponse.subject | El paciente que es el sujeto | | questionnaire | QuestionnaireResponse.questionnaire | El cuestionario que se está respondiendo | ### Se modificó el filtrado de recursos Cuando se proporciona el `changedSince` parámetro: + Solo se incluyen los recursos modificados **después** de la marca de tiempo especificada + Si ningún recurso ha cambiado, regresa `200 OK` con un paquete vacío + Útil para actualizaciones incrementales y estrategias de almacenamiento en caché + La comparación de marcas de tiempo utiliza el campo de recursos `meta.lastUpdated` ### Múltiples paquetes La operación puede devolver **varios Package Bundles** cuando: + Se solicitan varios cuestionarios a través de Canonical URLs + Los pedidos múltiples requieren cuestionarios diferentes + Se aplican diferentes versiones del mismo cuestionario Cada Package Bundle es autónomo y cuenta con todas las dependencias necesarias. ## Casos de uso comunes ### Caso de uso 1: documentación de autorización previa **Escenario**: un proveedor debe recopilar la documentación necesaria para obtener una autorización previa para la oxigenoterapia domiciliaria. ``` { "resourceType": "Parameters", "parameter": [ { "name": "coverage", "resource": { /* Patient's insurance coverage */ } }, { "name": "order", "resource": { "resourceType": "ServiceRequest", "code": { "coding": [{ "system": "http://www.ama-assn.org/go/cpt", "code": "94660" }] } } } ] } ``` **Resultado**: devuelve un paquete con el cuestionario de oxigenoterapia, rellenado previamente con los datos vitales del paciente y los códigos de diagnóstico del EHR. ### Caso de uso 2: recupere una versión específica del cuestionario **Escenario**: un proveedor necesita una versión específica de un cuestionario para cumplir con los requisitos. ``` { "resourceType": "Parameters", "parameter": [ { "name": "coverage", "resource": { /* Coverage resource */ } }, { "name": "questionnaire", "valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0" } ] } ``` **Resultado**: devuelve exactamente la versión 3.1.0 del cuestionario de solicitud del DME con todas las dependencias. ### Caso de uso 3: comprobar si hay actualizaciones **Escenario**: un proveedor quiere comprobar si algún recurso del cuestionario se ha actualizado desde la última consulta. ``` { "resourceType": "Parameters", "parameter": [ { "name": "coverage", "resource": { /* Coverage resource */ } }, { "name": "questionnaire", "valueCanonical": "http://example.org/fhir/Questionnaire/medication-request" }, { "name": "changedSince", "valueDateTime": "2024-03-01T00:00:00Z" } ] } ``` **Resultado**: devuelve solo los recursos que se hayan modificado después del 1 de marzo de 2024 o un paquete vacío si no ha cambiado nada. ### Caso de uso 4: pedidos múltiples **Escenario**: un proveedor envía varias solicitudes de servicio que pueden requerir cuestionarios diferentes. ``` { "resourceType": "Parameters", "parameter": [ { "name": "coverage", "resource": { /* Coverage resource */ } }, { "name": "order", "resource": { /* ServiceRequest for imaging */ } }, { "name": "order", "resource": { /* ServiceRequest for DME */ } } ] } ``` **Resultado**: devuelve varios Package Bundles, uno para cada cuestionario aplicable. ## Integración con otros Da Vinci IGs ### Descubrimiento de requisitos de cobertura (CRD) **Integración del flujo de trabajo:** + El proveedor solicita un servicio en su registro electrónico electrónico + El CRD Hook se dispara, comprobando los requisitos de cobertura + El pagador responde indicando que necesita documentación + El proveedor llama `$questionnaire-package` para recuperar el formulario de documentación + El proveedor completa el cuestionario + La documentación se envía a través del PAS o CDex ### Soporte de autorización previa (PAS) **Integración del flujo de trabajo:** + Se utiliza `$questionnaire-package` para recuperar los requisitos de documentación + Complete el formulario QuestionnaireResponse con los datos clínicos requeridos + Envíe la autorización previa `Claim/$submit` junto con la cumplimentada QuestionnaireResponse + Compruebe el estado utilizando `Claim/$inquire` ### Intercambio de datos clínicos (CDex) **Integración del flujo de trabajo:** + El pagador solicita documentación adicional para una reclamación + El proveedor utiliza `$questionnaire-package` para recuperar el formulario de recopilación de datos estructurados + El proveedor completa el QuestionnaireResponse + La documentación se envía al pagador a través del flujo de trabajo CDex adjunto ## Guía para solucionar problemas ### Problema: No se devolvió el cuestionario **Posibles causas:** + La URL canónica no coincide con ningún cuestionario del almacén de datos + El código del pedido no se corresponde con ningún cuestionario de la política médica del pagador + El pagador de la cobertura no tiene cuestionarios asociados **Soluciones:** + Verifica que la URL canónica sea correcta y que el cuestionario exista + Comprueba que los códigos de pedido (CPT/HCPCS) estén correctamente especificados + Confirme que la organización pagadora tenga configurados los cuestionarios ### Problema: Faltan dependencias en el paquete **Posibles causas:** + Biblioteca a la que se hace referencia o ValueSet no existe en el almacén de datos + Las referencias a la biblioteca están rotas o son incorrectas + ValueSet la expansión ha fallado **Soluciones:** + Compruebe el `Outcome` parámetro para ver si hay advertencias sobre la falta de recursos + Compruebe que todos los recursos a los que se hace referencia existan en el banco de datos + Asegúrese de que ValueSet URLs son correctos y se pueden resolver ### Problema: Empty Package con ChangedSince **Posibles causas:** + Este es el comportamiento esperado: no se ha modificado ningún recurso desde la marca de tiempo especificada **Soluciones:** + Utilice la versión en caché del paquete + Elimine `changedSince` el parámetro para recuperar el paquete completo ### Problema: QuestionnaireResponse no se ha rellenado previamente **Posibles causas:** + No se QuestionnaireResponse encontró ningún elemento existente + La lógica de la biblioteca CQL no pudo extraer los datos necesarios + Faltan datos del paciente o están incompletos **Soluciones:** + Esto es de esperar: no todos los cuestionarios tienen una lógica previa a la población + Compruebe que los datos del paciente existan en el almacén de datos + Revise la lógica de la biblioteca CQL para conocer los requisitos de extracción de datos ## Prácticas recomendadas ### 1. Utilice Canonical URLs con las versiones Especifique siempre los números de versión cuando solicite cuestionarios específicos: ``` { "name": "questionnaire", "valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0" } ``` **Por qué**: Garantiza la coherencia y evita cambios inesperados cuando se actualizan los cuestionarios. ### 2. Aproveche los cambios desde entonces para mejorar el rendimiento Para los cuestionarios a los que se accede con frecuencia, utilícelos `changedSince` para minimizar la transferencia de datos: ``` { "name": "changedSince", "valueDateTime": "2024-03-10T15:30:00Z" } ``` **Por qué**: reduce la latencia y el uso de ancho de banda al recuperar solo los recursos actualizados. ### 3. Incluya información completa sobre la cobertura Proporcione detalles de cobertura completos para garantizar la correcta selección del cuestionario: ``` { "name": "coverage", "resource": { "resourceType": "Coverage", "beneficiary": { "reference": "Patient/123" }, "payor": [{ "reference": "Organization/payer-abc" }], "class": [{ /* Group/plan information */ }] } } ``` **Por qué**: Ayuda a HealthLake identificar los cuestionarios y requisitos específicos del pagador. ## Operaciones de relacionadas + `Claim/$submit`- Presente las solicitudes de autorización previa con la documentación completa + `Claim/$inquire`- Verificar el estado de las autorizaciones previas presentadas + `ValueSet/$expand`- Ampliar ValueSets para ver las opciones de respuesta