Mensagem enviada
Uma mensagem enviada é o que a equipe e o paciente trocaram na conversa: o texto, o anexo, quando saiu e quando chegou.
No FHIR o recurso é a
Communication.
Este recurso é somente leitura. Não existe POST /fhir/resources/Communication — não há
como enviar mensagem a um paciente por esta API.
Campos
Todos os campos são de resposta — nenhum deles é enviado por você.
status é entrega, não leitura
completed junta três coisas diferentes. Enviada, entregue e lida colapsam no mesmo valor:
não há como saber, por este campo, se o paciente leu a mensagem.
O que dá alguma pista é o received, que só aparece quando a entrega foi confirmada — mas
leitura não tem campo nenhum.
Quem enviou e quem recebeu
Mensagem do paciente vem sem destinatário. Só as mensagens enviadas pela equipe trazem
recipient[]. Numa mensagem recebida, o campo simplesmente não vem — a plataforma não registra
para quem, dentro da equipe, ela foi.
E uma mensagem da equipe também pode vir sem recipient: quando a conversa não resolve
nenhum paciente, a lista sai vazia e some da resposta. Ausência de recipient não distingue,
sozinha, quem enviou — para isso, olhe o type do sender.
Numa mensagem do paciente, o sender é o primeiro paciente da conversa, não
necessariamente quem escreveu. Numa conversa com mais de um paciente — o que acontece em
conversas familiares —, isso pode apontar para a pessoa errada.
Não use o sender de uma mensagem recebida para atribuir autoria.
Uma conversa resolve no máximo 50 pacientes. Acima disso, os destinatários excedentes são
omitidos em silêncio do recipient[]. Numa conversa grande, a lista que você recebe é
incompleta e não há sinal disso na resposta.
O conteúdo
payload[] traz até dois itens: um com contentString, para o texto, e outro com
contentAttachment, para o anexo.
Uma mensagem só com anexo vem com um item só; uma mensagem sem texto e sem anexo vem sem
payload. E o anexo é uma referência ao arquivo, não o conteúdo dele.
Campos que a Nilo não usa
A Communication canônica traz muito mais: basedOn, partOf, inResponseTo, category,
priority, subject, topic, about, encounter, reasonCode, reasonReference e note.
Nenhum deles é lido.
Repare em inResponseTo e em partOf: não há como reconstruir a thread da
conversa por esta API. As mensagens vêm soltas, e a única forma de agrupá-las é pelo par de
participantes e pela ordem de sent.
E repare em subject: numa mensagem da equipe, o paciente está em recipient; numa do
paciente, em sender. Não há um campo único que diga “de quem é esta conversa”.
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
Para listar as mensagens de um paciente, você precisa das duas buscas. As que ele recebeu
estão em recipient; as que ele enviou, em sender. Não há um parâmetro que cubra os dois.
Os demais parâmetros canônicos da Communication existem e não encontram nada, porque a
plataforma não preenche o campo correspondente: based-on, category, encounter,
instantiates-canonical, instantiates-uri, part-of, patient e subject.
Repare em patient: o parâmetro canônico procura em Communication.subject, que a Nilo
não preenche — use recipient e sender.
Qual identificador as referências de sender e recipient carregam depende da sua
implantação. Na configuração que usa identificadores externos, cada referência sai com o
identificador do seu sistema; sem ela, vem o identificador Nilo. 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.
Cadastrar ou atualizar
Não existe. Este recurso não tem caminho de escrita nesta API.
Um POST /fhir/resources/Communication 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.
O que a integração não cobre
- enviar mensagem a um paciente;
- a thread da conversa — não há
inResponseTonempartOf; - se o paciente leu a mensagem;
- o destinatário de uma mensagem recebida;
- os pacientes além do quinquagésimo numa conversa grande;
- o conteúdo do anexo — só a referência a ele.
Para as mensagens que a plataforma vai enviar, veja Mensagem programada.