CDS Hooks explicado: hooks, cartões, prefetch

Resposta curta: CDS Hooks é uma norma HL7 que permite a um sistema de registo eletrónico de saúde (EHR) chamar um serviço externo de apoio à decisão clínica em momentos definidos (hooks) no fluxo de trabalho de um profissional de saúde: abrir o historial de um paciente (patient-view), escolher uma prescrição (order-select), assinar prescrições (order-sign), iniciar ou terminar uma consulta. O EHR envia o contexto e, opcionalmente, dados FHIR pré-carregados; o serviço responde em segundos com cartas: curtas informações, avisos ou sugestões, e links que podem iniciar uma aplicação SMART on FHIR. O profissional de saúde permanece no EHR; a inteligência vive fora dele.

Os três passos

O CDS Hooks funciona em três passos. Primeiro, descoberta: o EHR obtém o GET /cds-services e descobre a que hook cada serviço responde e quais dados FHIR pretende pré-carregar. Segundo, a chamada do hook: num evento de fluxo de trabalho, como a assinatura de uma ordem, o EHR envia o contexto e os recursos pré-carregados para o serviço. Terceiro, a resposta: o serviço devolve cartões que o EHR exibe.

1. Descoberta. O EHR obtém GET https://cds.example.org/cds-services e recebe a lista de serviços, cada um com o hook a que responde e as consultas FHIR que gostaria de pré-carregar:

{
  "services": [{
    "id": "renal-dosing",
    "hook": "order-sign",
    "title": "Renal dosing check",
    "description": "Flags drug orders whose dose needs review against the latest eGFR.",
    "prefetch": {
      "patient": "Patient/{{context.patientId}}",
      "egfr": "Observation?patient={{context.patientId}}&code=http://loinc.org|98979-8&_sort=-date&_count=1"
    }
  }]
}

2. A chamada do hook. Quando o profissional de saúde assina prescrições, o EHR envia um POST para /cds-services/renal-dosing:

{
  "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
  "hook": "order-sign",
  "fhirServer": "https://ehr.example.org/fhir",
  "fhirAuthorization": {"access_token": "…", "token_type": "Bearer", "expires_in": 300, "scope": "patient/*.read", "subject": "renal-dosing"},
  "context": {
    "userId": "Practitioner/42",
    "patientId": "123",
    "draftOrders": {"resourceType": "Bundle", "entry": [{"resource": {"resourceType": "MedicationRequest", "id": "draft-1", "status": "draft"}}]}
  },
  "prefetch": {
    "patient": {"resourceType": "Patient", "id": "123"},
    "egfr": {"resourceType": "Bundle", "type": "searchset", "entry": [{"resource": {"resourceType": "Observation", "id": "obs-9", "status": "final", "code": {"coding": [{"system": "http://loinc.org", "code": "98979-8"}]}, "valueQuantity": {"value": 38, "unit": "mL/min/1.73m2"}}}]}
  }
}

Se algo de que o serviço necessita não foi pré-carregado, pode consultar o servidor FHIR do EHR com o token de curta duração em fhirAuthorization.

3. A resposta. Cartas e, na versão 2.0, também ações do sistema:

{
  "cards": [{
    "uuid": "9a1d2f3e-…",
    "summary": "eGFR 38: dose review suggested",
    "indicator": "warning",
    "detail": "The most recent eGFR (38 mL/min/1.73m², 2026-03-10) is below the threshold in the local renal dosing guidance for this drug.",
    "source": {"label": "Hospital renal dosing guidance", "url": "https://intranet.example.org/renal"},
    "suggestions": [{"label": "Open renal dosing table", "uuid": "…", "actions": []}],
    "links": [{"label": "Dosing calculator", "url": "https://apps.example.org/renal/launch", "type": "smart"}]
  }]
}

summary está limitado a 140 caracteres; indicator é info, warning ou critical; source é obrigatório para que o profissional de saúde saiba quem está a falar. suggestions podem propor alterações concretas (criar, atualizar ou eliminar um rascunho de recurso) que o profissional de saúde aceita com um clique; links do tipo smart abrem uma aplicação SMART em contexto. O EHR renderiza as cartas no seu próprio estilo; o serviço nunca desenha a sua própria interface dentro do EHR.

Adições da versão 2.0

A versão 2.0 do CDS Hooks, publicada em 2022, adicionou um ponto final de feedback através do qual o EHR reporta se um cartão foi aceite, ignorado com motivos ou recusado; systemActions, alterações que o EHR aplica sem pedir, para tarefas de manutenção de baixo risco; o campo fhirAuthorization.subject; e regras mais claras de selectionBehavior (at-most-one ou any) para sugestões.

Publicada em 2022: um ponto final de feedback (POST /cds-services/{id}/feedback) através do qual o EHR reporta se uma carta foi aceite, ignorada (com razões) ou rejeitada; systemActions, alterações que o EHR aplica sem perguntar, destinadas a tarefas de manutenção de baixo risco, como adicionar uma razão codificada; fhirAuthorization.subject; e regras mais claras sobre selectionBehavior (at-most-one ou any) para sugestões.

O que é e o que não é um serviço

Um serviço CDS Hooks é um software que lê o contexto do fluxo de trabalho e devolve informações em forma de cartões; não é automaticamente um dispositivo médico. Se as regras de dispositivos médicos se aplicam na UE e nos EUA depende do conteúdo: lembrar um médico que um valor laboratorial existe é informação, enquanto uma recomendação de dose específica para o paciente é um suporte de decisão regulamentado.

Um serviço CDS é software que lê o contexto e devolve informação. Se é um dispositivo médico depende do que as cartas dizem: um lembrete de que um valor laboratorial existe é informação; uma recomendação de dose para um paciente específico é apoio à decisão que se enquadra nas regras de dispositivos médicos na UE e nos EUA. Ver Uma aplicação de saúde é um dispositivo médico?. A norma é neutra; o conteúdo não é.

Hooks definidos hoje: patient-view, order-select, order-sign, order-dispatch, encounter-start, encounter-discharge, appointment-book, com um catálogo público onde novos hooks são propostos.

Relação com SMART on FHIR

O CDS Hooks e o SMART on FHIR são complementares. O SMART on FHIR lança uma aplicação que assume parte do ecrã e consulta o servidor FHIR com a autorização do utilizador; o CDS Hooks corre em segundo plano e devolve cartões na própria interface do EHR. Um cartão pode conter um link de lançamento SMART quando é necessária mais do que um cartão.

SMART on FHIR inicia uma aplicação que assume parte do ecrã e comunica com o servidor FHIR com a autorização do utilizador. CDS Hooks funciona em segundo plano e devolve cartas; uma carta pode conter um link de lançamento SMART quando é necessária mais do que uma carta. A maioria dos produtos de apoio à decisão utiliza ambos: hooks para o alerta, uma aplicação SMART para os detalhes.

Onde a Anpheros se encaixa

A Anpheros não oferece um serviço CDS Hooks nem produz recomendações clínicas. O seu registo FHIR, com o consentimento do paciente, pode ser os dados que o serviço de apoio à decisão do hospital lê (medicamentos, alergias, resultados recentes), através da mesma API FHIR que um serviço de hook utilizaria. Ver Plataforma de consentimento do paciente.

Páginas relacionadas

Fontes

Perguntas frequentes

O CDS Hooks faz parte do FHIR?

É uma especificação HL7 separada que utiliza FHIR para os seus dados: o pré-carregamento e o contexto transportam recursos FHIR, e a autorização reutiliza tokens SMART on FHIR. É publicada pela HL7 juntamente com o FHIR, não dentro da especificação FHIR.

Quão rápido deve responder um serviço CDS?

A especificação não fixa um número, mas os EHRs aplicam timeouts de alguns segundos e descartam respostas tardias, porque o profissional de saúde está à espera. O pré-carregamento existe precisamente para que o serviço não gaste esse tempo a consultar.

Um serviço CDS pode alterar a prescrição?

Apenas propondo uma sugestão que o profissional de saúde aceite, ou, na versão 2.0, através de systemActions que o EHR concordou em aplicar automaticamente para esse serviço. O serviço nunca escreve no servidor FHIR do EHR por conta própria durante um hook.

Uma aplicação de paciente utiliza CDS Hooks?

Não. CDS Hooks foi concebido para fluxos de trabalho de EHR direcionados a profissionais de saúde. As aplicações de paciente utilizam diretamente a API FHIR e SMART on FHIR para login.

Anpheros Platform

Experimente grátis no sandbox

Sua primeira chamada FHIR em 5 minutos. Uma API HL7 FHIR R4 com o consentimento do paciente integrado: experimente na sandbox e depois conecte a sua própria app ou sistema clínico.

Criar um sandbox grátis Ler os guias para programadores →

Grátis · 30 pacientes sintéticos · sem cartão

Este guia é meramente informativo e não substitui aconselhamento médico. Para decisões sobre a sua saúde, fale com o seu médico. Em uma emergência, ligue para o número de emergência local (112 na Europa).

Escrito por

A equipa Anpheros

A Anpheros desenvolve um registo médico que o doente controla e pode partilhar com qualquer clínica, numa plataforma HL7 FHIR R4, sediada na UE. Estes guias ajudam-no a compreender e organizar a sua saúde; não substituem o seu médico.

Sobre a Anpheros →