Medicamento
Um medicamento do paciente é um registro do que ele está tomando. Na plataforma ele nasce de dois jeitos, e é essa origem que decide o recurso FHIR que você vai ler:
Nos dois casos o nome do medicamento não está no recurso: ele vem por referência para um
terceiro recurso, o Medication, que é o catálogo.
Este é um recurso só, visto de três ângulos. Um mesmo registro de medicamento sai como
MedicationStatement ou como MedicationRequest — nunca os dois —, e o que decide é a
presença de uma receita. O identificador é o mesmo nos dois casos, no system
…/NamingSystem/hippocrates-api--medication-request.
Se a sua integração quer todos os medicamentos de um paciente, precisa consultar as duas buscas. Nenhuma delas sozinha devolve o conjunto completo.
Os três recursos são somente leitura. Não existe POST para nenhum deles — medicamentos
são registrados pela equipe no Nilo Care, e o catálogo é da plataforma.
O catálogo: Medication
O Medication é mínimo: identificador, nome e uma constante.
code vem só com text, nunca com coding. Não há código de catálogo — nem EAN, nem
princípio ativo, nem laboratório. O que a API dá é o nome comercial, como ele está cadastrado.
Por causa disso, a busca por nome usa o modificador :text — veja
Buscar no catálogo.
status é constante active em todo medicamento do catálogo. Não use este campo para saber
se um medicamento foi descontinuado: essa informação não existe aqui.
Medicamento em uso: MedicationStatement
É o que a equipe anota na aba Medicamentos da ficha do paciente, sem receita — na seção Medicamentos em uso enquanto está tomando, e no Histórico depois.
status é binário, e não reproduz as seções da tela. Ele é derivado de um único sinal — se
o paciente está tomando o medicamento hoje —, enquanto a plataforma trabalha com quatro
situações: em uso, previsto, interrompido e encerrado.
Consequências: um medicamento com início futuro vem completed mesmo aparecendo em
Medicamentos em uso na tela; e um interrompido pode vir active mesmo estando no
Histórico. Não use status para reproduzir a tela.
E o status fica para trás. Ele é regravado quando o registro do medicamento muda —
não quando a posologia é encerrada ou interrompida. Um medicamento já encerrado no Nilo Care
pode continuar vindo como active por tempo indeterminado.
Não trate status como sinal de encerramento. Se a sua integração precisa saber se o paciente
parou de tomar, este dado não é confiável nesta API.
effectivePeriod vem de uma posologia só, e não é a vigente. Um medicamento cuja posologia
foi alterada tem várias; o período exposto é o da posologia menos recentemente alterada —
que pode ter terminado há meses enquanto o paciente segue tomando.
Cruzar status: active com um effectivePeriod já vencido é comum e não é inconsistência de
dado: são duas coisas que não se conversam.
dosage[] traz todas as posologias registradas, da última alterada para a primeira — e a
tela mostra só a vigente. Uma posologia gravada sem texto vem como "?", literalmente.
Posologia e nota não atualizam o recurso. dosage[], note[] e effectivePeriod são
gravados quando o registro do medicamento muda. Alterar a posologia, interrompê-la ou
acrescentar uma nota não regrava o recurso FHIR.
Na prática, o conteúdo desses três campos pode estar defasado — inclusive vazio num
medicamento que já tem posologia no Nilo Care, se o registro nunca mais foi tocado depois de
criado. Vale igualmente para dosageInstruction[] e note[] do medicamento prescrito.
Buscar medicamentos em uso
Para o atendimento, use context:identifier, não context. A referência ao atendimento vem
sem o campo reference — só com identifier e type —, e o parâmetro sem modificador procura
justamente em reference. É a mesma situação da
avaliação clínica e da conduta.
subject, informationSource e medicationReference, esses, vêm completos: as duas formas
funcionam.
Os demais parâmetros canônicos do MedicationStatement existem e não encontram nada,
porque a plataforma não preenche o campo correspondente: category, code, effective e
part-of.
Para filtrar por medicamento, o caminho estável é medication:identifier com o identificador
Nilo do Medication — busque o medicamento no catálogo por code:text, pegue o identifier e
filtre por ele. O id do recurso também funciona, mas muda entre ambientes.
Medicamento prescrito: MedicationRequest
É cada item de uma receita emitida na plataforma.
status é da receita, não do medicamento
Uma receita com cinco medicamentos produz cinco MedicationRequest, todos com o mesmo
status. Ele não diz nada sobre este medicamento em particular — não diz se o paciente o
tomou, se a prescrição foi suspensa, nem se ela ainda está válida.
E não há campo que aponte para a receita que agrupa os itens: cada MedicationRequest é
independente na leitura, e o que os liga é o encounter mais o requester.
recorder traz sempre o mesmo profissional que requester. O FHIR distingue quem prescreveu
de quem registrou; aqui os dois campos são a mesma pessoa.
O PDF da receita
Quando a receita tem PDF, supportingInformation[0] aponta para um DocumentReference que
guarda a URL do arquivo. É preciso ler esse recurso para chegar à URL.
Esse DocumentReference carrega o mesmo identificador do medicamento prescrito, no system
…/NamingSystem/hippocrates-api--medication-request — então dá para buscá-lo direto por
identifier, sem precisar seguir a referência. A URL do arquivo está em
content[0].attachment.url.
O DocumentReference não tem página neste guia, e a URL que ele guarda é um caminho de
armazenamento, não necessariamente um link de download direto — o mesmo comportamento descrito
em Arquivo do paciente.
Buscar prescrições
Para o atendimento, use encounter:identifier, pela mesma razão do context do medicamento
em uso: a referência vem sem o campo reference.
Os demais parâmetros canônicos do MedicationRequest existem e não encontram nada, porque
a plataforma não preenche o campo correspondente: authoredon, category, code, date,
intended-dispenser, intended-performer, intended-performertype e priority.
requester, esse, vem completo — com reference além do identifier —, e as duas formas de
busca funcionam.
Buscar no catálogo
Use code:text, não code. O parâmetro code é de token e procura dentro de coding —
que a Nilo não preenche. Buscar code=ACEBROFILINA não devolve nada; code:text=ACEBROFILINA
devolve.
O catálogo não é filtrado por cliente. Ele é da plataforma inteira: sem code:text ou
identifier, a busca percorre todos os medicamentos cadastrados, e são muitos. Pagine com
_count e filtre sempre.
Os demais parâmetros canônicos do Medication existem e não encontram nada: form,
ingredient, ingredient-code, lot-number, expiration-date e manufacturer. Nenhum
deles é preenchido.
Ler por ID
Os três recursos têm leitura direta por id, e os três devolvem o mesmo envelope.
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 registro está em
resource.
Cadastrar ou atualizar
Não existe, em nenhum dos três recursos.
Um POST em qualquer um deles 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 … not supported.
Efeitos colaterais
Excluir um atendimento remove, junto, os medicamentos registrados nele. Os recursos
correspondentes desaparecem do store sem aviso, e um id que você já leu com sucesso passa a
responder 404. Se você guarda o conteúdo, guarde o conteúdo — não o id.
O que a integração não cobre
Além da escrita, vários dados que a plataforma guarda não têm campo em nenhum dos três recursos:
- se o medicamento é de uso contínuo — um campo obrigatório na tela;
- se a substituição por genérico é permitida;
- quando o uso foi interrompido, por quem e por quê;
- as interações medicamentosas que a plataforma calcula;
- o princípio ativo, o laboratório e o código de barras do medicamento;
- a receita que agrupa os itens prescritos, como recurso próprio.
Para os arquivos do paciente, veja Arquivo do paciente; para o atendimento em que o medicamento foi registrado, Atendimentos.