Questionário
Um questionário é o formulário que a equipe monta no Nilo Care e aplica ao paciente: a lista de perguntas, o tipo de cada uma e as opções de resposta. É o molde; o que o paciente respondeu é o questionário respondido.
No FHIR o recurso é o
Questionnaire, e ele existe aqui sobretudo
para uma coisa: resolver a canônica que cada resposta carrega em questionnaire, e assim
descobrir o enunciado de cada pergunta.
Este recurso é somente leitura. Não existe POST /fhir/resources/Questionnaire — os
questionários são montados pela equipe no Nilo Care, e não há como criá-los ou alterá-los por
esta API.
Campos
A coluna No Nilo Care traz o rótulo com que o dado aparece para a equipe; são rótulos, não caminhos de navegação. Todos os campos são de resposta — nenhum deles é enviado por você.
name e title trazem o mesmo texto. O FHIR distingue nome técnico de título de
exibição; a plataforma tem só um nome, e ele é copiado para os dois campos.
date e lastReviewDate vêm da mesma data — a da última alteração do questionário —, mas
não no mesmo formato: o FHIR tipa lastReviewDate como data pura, então a hora se perde
ali e fica só em date. approvalDate também é data pura. Não há revisão registrada à parte.
subjectType vem com o valor Questionnaire, e isso não faz sentido. No FHIR o campo diz
a que tipo de recurso o questionário se aplica — o valor correto seria Patient. Ignore este
campo: ele não carrega informação e não deve ser usado para nada.
status
Na tela, os quatro estados aparecem como Rascunho, Publicado, Não publicado e Desatualizado — ou, numa implantação que ainda usa a lista antiga, Rascunho, Ativo, Inativo e Desatualizado.
retired junta duas coisas diferentes — o questionário que a equipe tirou do ar (Não
publicado) e o que foi substituído por uma versão mais nova (Desatualizado). Não há campo
que distinga um do outro, nem que aponte para a versão que substituiu.
As perguntas
Cada pergunta do questionário vira um item de item[], com três campos — o linkId, o
enunciado em text e o tipo em type — mais as opções, nas perguntas de escolha.
linkId é a chave para casar pergunta e resposta. É o mesmo valor que aparece em
item[].linkId do questionário respondido. Lendo os
dois recursos, é por ele que você liga o enunciado à resposta do paciente.
Tipos de pergunta
choice não distingue escolha única de escolha múltipla. Os dois tipos saem iguais, e não
há campo que diga quantas opções o paciente podia marcar. Se isso importa para a sua
integração, o dado não está nesta API.
Seis outros tipos de pergunta caem todos em text. Escala, data, numérica, e-mail,
telefone e os blocos de texto informativo — que nem aceitam resposta — saem todos com
type: text, indistinguíveis de uma pergunta de texto longo.
A pergunta de escala é o caso mais confuso: ela tem opções, e elas vêm em answerOption.
Ou seja, um type: text com answerOption é sinal de que o tipo original se perdeu; um
sem opções pode ser texto longo ou qualquer um dos demais.
As opções de resposta
Nas perguntas de escolha, cada opção vira um item de answerOption, com o rótulo em
valueString.
Opções de campo aberto não entram na lista. Uma pergunta com a opção Outro (especifique)
aparece aqui sem ela: o answerOption traz só as opções fechadas, e o total de opções que
você lê é menor do que o que o paciente viu.
É o outro lado de um comportamento do questionário
respondido: quando o paciente escolhe uma opção aberta
e digita algo, a resposta traz o texto digitado, e não um rótulo que exista aqui. Não trate a
resposta como um valor que tem de estar em answerOption.
answerOption traz só o rótulo. A pontuação de cada opção, que a plataforma usa para
calcular o resultado do questionário, não é exposta — nem aqui nem no questionário respondido.
O que item[] não representa
A lista de perguntas é plana: as seções do formulário não existem no recurso, e perguntas de seções diferentes vêm num nível só. Não há como reconstruir onde uma seção termina e a outra começa.
A ordem, essa sim, é a da tela: as perguntas vêm na ordem das seções e, dentro de cada seção, na ordem em que foram montadas. É por isso que dá para ordenar as respostas de um paciente por aqui — veja Questionário respondido.
Num questionário que veio de uma sincronização externa e já foi ressincronizado, item[]
pode trazer perguntas de versões anteriores junto com as atuais — enunciados repetidos, com
linkId diferentes. Case sempre pelo linkId que veio na resposta do paciente, e não conte os
itens para saber o tamanho do formulário.
Também não têm campo aqui: se a pergunta é obrigatória, a descrição dela, a pontuação das opções e a escala de resultado do questionário.
Buscar
A resposta é sempre um Bundle do tipo searchset:
Busca sem resultados não é erro: volta 200 com um Bundle cujo entry é uma lista vazia.
Trate a ausência de resultados pela lista vazia, não esperando um 404.
Parâmetros de busca suportados
name também é um parâmetro canônico do Questionnaire, e aqui ele encontra o mesmo que
title — os dois campos trazem o mesmo texto.
Os demais parâmetros canônicos existem e não encontram nada, porque a plataforma não
preenche o campo correspondente: version, url, publisher, context, jurisdiction,
code, definition e effective. Repare em url: este recurso não tem url canônica —
a canônica que a resposta do paciente carrega é montada a partir do id.
subject-type é a exceção: ele encontra, e encontra errado. Como o campo é sempre a
constante Questionnaire, subject-type=Questionnaire devolve tudo e subject-type=Patient
não devolve nada. Não é filtro útil.
A paginação é por _count e _page_token; havendo página seguinte, o Bundle traz a URL
pronta em link.
Há um segundo caminho para chegar a um questionário: a Tarefa. O item
questionnaire de output[] traz o identificador do questionário, não a canônica — então
o caminho é buscar por identifier=…|{valor}, e não ler por id.
Ler por ID
É este o caminho que a canônica do
questionário respondido aponta. Use a URL que veio no
campo questionnaire da resposta, tal como ela veio.
Diferente da busca, esta leitura não devolve um Bundle — mas também não devolve o recurso
nu. A resposta é um envelope com fullUrl, search e resource, e o questionário está em
resource. Ler item na raiz da resposta não encontra nada.
A canônica não é versionada. O que você lê por aqui é o questionário como ele está hoje — perguntas podem ter sido reescritas, acrescentadas ou removidas depois de o paciente responder.
Casando linkId entre o questionário e uma resposta antiga, pode não haver correspondência:
uma pergunta removida some daqui e continua na resposta. Trate a ausência como “pergunta que
não existe mais”, não como erro.
Cadastrar ou atualizar
Não existe. Este recurso não tem caminho de escrita nesta API — nem para criar, nem para atualizar, nem para apagar.
Um POST /fhir/resources/Questionnaire não é uma operação suportada e não devolve um erro
de validação tratável: a chamada falha com erro inesperado do servidor (500). Não escreva
tratamento em cima desse comportamento — ele não é contrato, e nada é gravado de qualquer
forma.
Dentro de uma carga em lote o erro é limpo, e
igualmente definitivo: a entrada é recusada com Resource Questionnaire not supported.
O que a integração não cobre
Além da escrita, vários dados que a plataforma guarda não têm campo aqui:
- as seções do formulário (a ordem das perguntas, essa, é preservada);
- se a pergunta é obrigatória, e a descrição dela;
- a pontuação de cada opção e a escala de resultado do questionário;
- as opções de campo aberto;
- a distinção entre escolha única e escolha múltipla, e os seis tipos de pergunta que
caem em
text; - a versão do questionário — não há histórico de versões deste recurso, e a canônica aponta sempre para o estado atual.
Para o que o paciente respondeu, veja Questionário respondido; para o questionário atribuído a um paciente como tarefa, Tarefa.