Operação FHIR para $questionnaire-package HealthLake

A $questionnaire-package operação recupera um pacote abrangente contendo um questionário FHIR e todas as dependências necessárias para renderizar e processar o questionário. Essa operação implementa o Guia de Implementação de Modelos e Regras de Documentação Da Vinci (DTR), permitindo a renderização dinâmica de formulários para requisitos de documentação em fluxos de trabalho de saúde.

Como funciona

Casos de uso

Ponto final da API

POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json

Parâmetros de solicitação

Parâmetros de entrada

O corpo da solicitação deve conter um recurso de parâmetros FHIR com os seguintes parâmetros:

Regras de validação de parâmetros

Pelo menos UM dos seguintes itens deve ser fornecido (além do obrigatóriocoverage):

Combinações de solicitações válidas:

Exemplo de solicitação

POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json  
Authorization: Bearer <your-token>  
  
{  
  "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 resposta

Resposta de sucesso (200 OK)

A operação retorna um recurso FHIR Parameters contendo um ou mais Package Bundles. Cada pacote Package inclui:

{  
  "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"  
          }  
        }]  
      }  
    }  
  ]  
}

Fluxo de trabalho operacional

Como HealthLake processa sua solicitação

Quando você liga$questionnaire-package, HealthLake executa as seguintes etapas:

Resultado: um pacote completo e independente pronto para renderização.

Respostas de erro

400 solicitação inválida

Retornado quando a validação da solicitação falha.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "required",  
    "details": {  
      "text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"  
    }  
  }]  
}

424 Dependência falhada

Retornado quando um recurso dependente não pode ser recuperado.

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "warning",  
    "code": "not-found",  
    "details": {  
      "text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"  
    }  
  }]  
}

401 Não autorizado

Retornado quando as credenciais de autenticação estão ausentes ou são inválidas.

403 proibido

Retornado quando o usuário autenticado não tem permissão para acessar os recursos solicitados.

406 Não aceitável

Retornado quando o tipo de conteúdo solicitado não pode ser fornecido.

409 Conflito

Retornado quando há um conflito de versão ou simultaneidade.

410 Desaparecido

Retornado quando o recurso solicitado foi excluído permanentemente.

429, muitas solicitações

Retornado quando os limites de taxa são excedidos.

500 Internal Server Error

Retornado quando ocorre um erro inesperado no servidor.

501 Não implementado

Retornado quando a operação solicitada ainda não foi implementada.

Regras de validação

Validação de entrada

QuestionnaireResponse validação

Desduplicação de recursos

Especificações de performance

Permissões obrigatórias

Para usar a $questionnaire-package operação, certifique-se de que sua função do IAM tenha:

SMART em escopos FHIR

Escopos mínimos exigidos:

Notas de implementação importantes

Estratégia de recuperação de recursos

Prioridade de identificação do questionário:

Resolução de dependências

Bibliotecas CQL:

ValueSets:

QuestionnaireResponse pré-população

A operação pode retornar um QuestionnaireResponse com dados pré-preenchidos quando:

Critérios de pesquisa para QuestionnaireResponse:

Filtragem de recursos alterada

Quando o changedSince parâmetro é fornecido:

Vários pacotes

A operação pode retornar vários Package Bundles quando:

Cada Package Bundle é independente com todas as dependências necessárias.

Casos de uso comuns

Caso de uso 1: documentação de autorização prévia

Cenário: Um provedor precisa coletar a documentação para uma autorização prévia de oxigenoterapia domiciliar.

{  
  "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: Retorna um pacote com o questionário de oxigenoterapia, pré-preenchido com os sinais vitais do paciente e os códigos de diagnóstico do EHR.

Caso de uso 2: Recuperar a versão específica do questionário

Cenário: um provedor precisa de uma versão específica de um questionário para fins de conformidade.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"  
    }  
  ]  
}

Resultado: retorna exatamente a versão 3.1.0 do questionário de solicitação do DME com todas as dependências.

Caso de uso 3: verifique se há atualizações

Cenário: um provedor deseja verificar se algum recurso do questionário foi atualizado desde a última recuperação.

{  
  "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: retorna somente recursos que foram modificados após 1º de março de 2024 ou um pacote vazio se nada tiver sido alterado.

Caso de uso 4: vários pedidos

Cenário: um provedor envia várias solicitações de serviço que podem exigir questionários diferentes.

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for imaging */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for DME */ }  
    }  
  ]  
}

Resultado: retorna vários Package Bundles, um para cada questionário aplicável.

Integração com outros Da Vinci IGs

Descoberta de requisitos de cobertura (CRD)

Integração do fluxo de trabalho:

Suporte de autorização prévia (PAS)

Integração do fluxo de trabalho:

Troca de dados clínicos (CDex)

Integração do fluxo de trabalho:

Guia de solução de problemas

Problema: Nenhum questionário foi devolvido

Causas possíveis:

Soluções:

Problema: dependências ausentes no Package

Causas possíveis:

Soluções:

Problema: Empty Package com ChangedSince

Causas possíveis:

Soluções:

Problema: QuestionnaireResponse Não pré-preenchido

Causas possíveis:

Soluções:

Práticas recomendadas

1. Use Canonical com versões URLs

Sempre especifique os números das versões ao solicitar questionários específicos:

{  
  "name": "questionnaire",  
  "valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"  
}

Por quê: Garante a consistência e evita alterações inesperadas quando os questionários são atualizados.

2. Aproveite o ChangedSince para desempenho

Para questionários acessados com frequência, use changedSince para minimizar a transferência de dados:

{  
  "name": "changedSince",  
  "valueDateTime": "2024-03-10T15:30:00Z"  
}

Por quê: Reduz a latência e o uso da largura de banda recuperando somente recursos atualizados.

3. Inclua informações completas de cobertura

Forneça detalhes abrangentes da cobertura para garantir a seleção correta do questionário:

{  
  "name": "coverage",  
  "resource": {  
    "resourceType": "Coverage",  
    "beneficiary": { "reference": "Patient/123" },  
    "payor": [{ "reference": "Organization/payer-abc" }],  
    "class": [{ /* Group/plan information */ }]  
  }  
}

Por quê: Ajuda a HealthLake identificar questionários e requisitos específicos do pagador.

Operações do relacionadas