Mensagem programada
Uma mensagem programada é um envio agendado para um paciente: o lembrete de consulta, a mensagem de acompanhamento que a diretriz manda disparar em 30 dias.
No FHIR o recurso é a
CommunicationRequest — e ele carrega
duas coisas diferentes, distinguidas pelo system do identificador:
As duas formas não trazem os mesmos campos. A mensagem programada é rica: tem priority,
category, occurrencePeriod, payload e note. A matrícula em campanha traz apenas
status, basedOn, subject, recipient e authoredOn.
Confira o system do identificador antes de ler qualquer outro campo.
Campos
status
priority não é uma prioridade: é um sinal de atraso. Ele vale asap quando o envio já
passou da data e ainda não aconteceu, e routine em todo o resto. Ninguém escolhe esse valor.
E ele fica para trás. O valor gravado é o do último instante em que a mensagem foi
sincronizada — e a passagem de “programada” para “atrasada” não altera nada no registro, então
não dispara sincronização. Uma mensagem que venceu depois do último sync continua routine.
Para saber se uma mensagem está atrasada, compare occurrencePeriod.start com a data de hoje do
seu lado. Não confie no priority.
subject e recipient[0] trazem o mesmo paciente. O FHIR distingue de quem é o assunto e
para quem vai a mensagem; aqui os dois campos são a mesma pessoa, sempre.
occurrencePeriod não é um intervalo
occurrencePeriod.start é a data programada de envio, e occurrencePeriod.end é o instante
em que a mensagem foi concluída ou cancelada. Numa mensagem ainda programada, o end não
vem.
Não são as duas pontas de uma janela de envio: são “quando devia” e “quando acabou”.
Dois campos que vazam formato interno
category[0].coding[0].code traz um identificador interno da plataforma, não um código de
vocabulário. Não é contrato: o valor pode mudar sem aviso, e não deve ser interpretado nem
usado como filtro estável — o parâmetro de busca category, na prática, só serve para quem já
conhece o valor que veio numa resposta.
note[0].text é a única informação de motivo que existe neste recurso. Ele vem no formato
status-detail:<motivo>, e o motivo é um de oito valores fechados: espera de encerramento da
conversa, nova tentativa em curso, limite de tentativas excedido, expirada, criada no passado,
paciente inativo, conversa desabilitada, e atraso máximo excedido.
O formato não é contrato — pode mudar sem aviso —, mas conhecer a lista ajuda a entender por que uma mensagem não saiu. Use para exibição e diagnóstico, não para lógica.
Campos que a Nilo não usa
A CommunicationRequest canônica traz muito mais: basedOn de outros tipos, groupIdentifier,
statusReason, medium, about, encounter, requester, sender, reasonCode,
reasonReference e doNotPerform. Nenhum deles é lido.
Repare em medium: não há campo que diga por onde a mensagem vai — se por conversa, se
por outro canal. E em sender: não há como saber quem a programou.
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.
Parâmetros de busca suportados
Os demais parâmetros canônicos existem e não encontram nada, porque a plataforma não
preenche o campo correspondente: medium, encounter, requester, sender, group-identifier
e based-on — este último porque a referência ao plano de cuidado vem sem reference; use
based-on:identifier.
Qual identificador as referências carregam depende da sua implantação. Na configuração que
usa identificadores externos, o subject sai com o identificador do seu sistema; sem ela, vem o
identificador Nilo do paciente. Confira numa resposta de leitura antes de montar a busca em
volume.
A paginação é por _count e _page_token; havendo página seguinte, o Bundle traz a URL
pronta em link.
Ler por ID
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 a mensagem está em
resource.
Onde a mensagem programada aparece
As mensagens geradas por uma diretriz também aparecem em activity[] do
plano de cuidado do paciente, junto com as tarefas e os
questionários. A vantagem desta página é poder buscá-las diretamente, sem passar pelo plano.
O caminho de volta é o basedOn, que aponta para o plano de cuidado — sem reference, então
use based-on:identifier para buscar por ele. Numa matrícula em campanha, o mesmo basedOn
aponta para a campanha, não para um plano: confira o system do identificador antes de
interpretá-lo.
Uma mensagem reprogramada aponta em replaces[0] para a anterior. É a única forma de
reconstruir a cadeia de reprogramações.
Matricular um paciente numa campanha
O POST deste recurso faz uma coisa só: coloca um paciente numa campanha de mensagens
já configurada no seu ambiente. Ele não programa uma mensagem avulsa.
A resposta é o recurso gravado, sem envelope:
São quatro exigências, e todas recusam a chamada quando não são atendidas:
A campanha não é criada por aqui. Ela é configurada no seu ambiente, e o que esta API faz é
matricular pacientes nela. Se a campanha não existir, a chamada é recusada com
Campaign not found — fale com o Suporte para saber quais campanhas existem e quais são os
identificadores delas.
Um paciente não pode ser matriculado duas vezes na mesma campanha. Se ele já estiver nela
com a matrícula em andamento, a chamada é recusada com Patient already on campaign.
E não há como retirá-lo por esta API: sair da campanha é ação da plataforma.
priority, occurrencePeriod, payload, category e note não são lidos neste POST, e
não voltam na resposta. A matrícula é um recurso mais pobre que a mensagem programada.
Erros da matrícula
Recusa é 400, e o corpo é um OperationOutcome com code: structure e o campo em
issue[].expression.
429
Este recurso pode ter limite de escrita, conforme a configuração do ambiente. Havendo
limite e estourando-o, a chamada responde 429 com code: throttled, e a mensagem informa
quantos segundos esperar.
O que a integração não cobre
- programar uma mensagem avulsa, cancelá-la ou reprogramá-la — só a matrícula em campanha é gravável;
- retirar um paciente de uma campanha;
- listar as campanhas existentes: elas não são publicadas como recurso;
- por onde a mensagem vai ser enviada;
- quem a programou;
- o elo com a mensagem efetivamente enviada — o
Communicationcorrespondente não é referenciado.