Solicitação de serviço
A solicitação de serviço é o pedido de que alguma coisa seja feita para o paciente. Na
plataforma isso são três coisas diferentes, e todas saem como
ServiceRequest:
Reconhecer qual é qual se faz pelo system do identificador Nilo, e só por ele — veja
Como distinguir as três origens.
O intent decide tudo na escrita, e o valor que funciona não é o natural. Só
intent: proposal tem destino: ele grava uma conduta. Qualquer outro valor — inclusive
order, que é o que a leitura devolve nos pedidos de exame — não é gravável, e a chamada
falha com erro inesperado do servidor (500), sem OperationOutcome.
Ou seja: você não pode reenviar um pedido de exame lido por esta API. Não há caminho de escrita para pedido de exame nem para encaminhamento.
Como distinguir as três origens
O intent separa a conduta das outras duas. Para separar pedido de exame de encaminhamento,
olhe o system do identificador Nilo:
Só a conduta pode carregar uma chave do seu sistema, porque é a única que você grava. As outras duas trazem apenas o identificador Nilo.
Pedido de exame
É o exame solicitado numa receita.
O status vem da receita inteira, não deste exame:
Uma receita com três exames produz três pedidos, todos com o mesmo status. Ele não diz
se o exame foi realizado — esse dado não existe nesta API.
E o status do pedido de exame pode ficar para trás. Ele é fotografado quando o pedido
muda, não quando a receita é emitida: um pedido pode continuar draft numa receita já emitida.
O encaminhamento não tem esse problema — nele a mudança de situação da receita ressincroniza o
recurso.
Se você precisa acompanhar a emissão, releia por _lastUpdated em vez de confiar no status
que veio.
encounter e basedOn vêm sem o campo reference — só com identifier e type. Para
buscar por eles, use encounter:identifier e based-on:identifier; a forma sem modificador
não encontra nada.
O documento apontado por supportingInfo[0] carrega o mesmo identificador do pedido de
exame — então dá para buscá-lo direto por identifier, sem seguir a referência. A URL do
arquivo está em content[0].attachment.url.
Esse recurso 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.
Encaminhamento
É o encaminhamento do paciente para outra especialidade, registrado num atendimento.
O status do encaminhamento usa um mapa diferente do pedido de exame, sobre a mesma
situação de receita:
Um encaminhamento emitido é active; um pedido de exame emitido é completed. Não trate os
dois vocabulários como um só.
Não leia note[] nem reasonCode[] por posição. Nos dois, a ordem é fixa mas os itens são
opcionais e só entram se estiverem preenchidos:
note[]— conduta primeiro, história clínica depois. Num encaminhamento sem conduta, a história clínica énote[0];reasonCode[]— motivo em texto primeiro, CID depois. Sem motivo, o CID éreasonCode[0].
Não há campo que distinga um do outro dentro de note[]. No reasonCode[] dá para separar: o
CID é o item que traz coding.
performerType vem da tradução da especialidade da plataforma para um código CBO, e essa
tradução pode não existir: uma especialidade sem correspondência CBO faz o campo não vir,
sem erro.
Conduta
É a conduta de um atendimento cujo desfecho foi sugestão terapêutica. É o único dos três que você pode gravar.
A resposta é o recurso gravado, sem envelope:
Uma conduta sem encounter cria um atendimento. A plataforma precisa de um atendimento
onde pendurar a conduta e, não recebendo um, cria um atendimento já finalizado no prontuário do
paciente — visível para a equipe como qualquer outro.
Se você tem o atendimento, mande-o — é o caminho recomendado.
Uma conduta sem note falha — e falha depois de o atendimento ter sido criado. A recusa
vem sem classificação de campo, e o atendimento vazio fica no prontuário. Confira que note
está preenchido antes de enviar.
O mesmo POST cria e atualiza: reenviando um identifier que já corresponde a uma conduta, o
texto dela é reescrito.
O atendimento de uma conduta não muda depois da criação. Numa atualização, o encounter do
payload é ignorado e a conduta continua no atendimento onde já estava. Para movê-la, não há
caminho por esta API.
Na leitura, a conduta vem com um note por linha; na escrita, os itens que você manda são
juntados numa nota só do lado da plataforma. Enviar duas notas e reler devolve duas notas — mas
uma nota que contenha uma quebra de linha volta partida em duas.
O encounter que você mandou é preservado no recurso e volta nas leituras seguintes. Uma
conduta registrada dentro da plataforma, essa sim, vem sem encounter.
O mesmo vale para qualquer campo que você envie e que a plataforma não produza — code,
category, priority, reasonCode. Eles ficam guardados no recurso e voltam nas leituras
seguintes, sem nunca terem significado nada para a plataforma. A referência não os declara, mas
a API não os recusa. Omita-os.
Pendurar a conduta num atendimento existente pode mudar o recurso que a lê. O tipo de recurso em que a conduta aparece é decidido pelo desfecho do atendimento, não pelo endpoint que você usou: num atendimento de resultado de exame ela vira Procedimento, e num de hipótese diagnóstica vira Condição.
A resposta do seu POST sempre volta como ServiceRequest, mas a próxima sincronização pode
reescrevê-la como outro recurso — e aí ela some da busca de ServiceRequest. Só quando a API
cria o atendimento é que o desfecho fica garantido como sugestão terapêutica.
A mesma conduta em outros recursos
A conduta que você grava aqui também aparece em action[] da
Conduta do atendimento, com o texto inteiro em vez de quebrado por
linha — mas não na hora: aquele recurso só é regravado quando o atendimento em si
sincroniza.
E é a mesma família de registro que a Condição grava com
verificationStatus: provisional. Quando a API cria o atendimento, o que muda entre os dois
caminhos é o desfecho que ela dá a ele; quando você informa um encounter, o desfecho é o do
atendimento que já existe, e a diferença é só o tipo de recurso que guarda a sua chave.
Não grave a mesma conduta pelos dois caminhos. POST /fhir/resources/Condition com
verificationStatus: provisional e POST /fhir/resources/ServiceRequest com
intent: proposal gravam registros diferentes, cada um com o seu identificador. Escolha um.
Buscar
A resposta é sempre um Bundle do tipo searchset, e a busca mistura as três origens.
Filtre por intent para separar a conduta, e pelo system do identificador para separar
pedido de exame de encaminhamento.
Busca sem resultados não é erro: volta 200 com um Bundle cujo entry é uma lista vazia.
Parâmetros de busca suportados
No pedido de exame, encounter e based-on só encontram com o modificador :identifier —
as duas referências saem sem o campo reference, e é nele que a forma sem modificador procura.
O subject, esse, vem completo nas três origens: patient e patient:identifier funcionam
igualmente.
Os demais parâmetros canônicos do ServiceRequest existem e não encontram nada, porque a
plataforma não preenche o campo correspondente: authored (exceto no encaminhamento),
body-site, instantiates-canonical, occurrence, performer, priority, replaces,
requisition e specimen.
code e category são preenchidos no pedido de exame, mas com coding — então funcionam com
o par system|code, não com o nome do exame.
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 solicitação está em
resource.
Erros
Recusa é 400, e o corpo é um OperationOutcome — exceto quando o intent não é
proposal, caso em que a chamada falha com 500 e sem corpo tratável.
Um POST com intent diferente de proposal não devolve nenhum dos erros acima: a
chamada falha com erro inesperado do servidor (500), sem OperationOutcome. Não escreva
tratamento em cima desse comportamento — ele não é contrato, e nada é gravado.
Dentro de uma carga em lote o erro é limpo:
a entrada é recusada com Resource ServiceRequest not supported.
O que a integração não cobre
- escrever pedido de exame ou encaminhamento — só a conduta é gravável;
- se o exame foi realizado, e o resultado dele;
- a receita que agrupa os pedidos, como recurso próprio;
- a distinção entre conduta e história clínica dentro de
note[]do encaminhamento; - o autor e a data da conduta.
Para as condutas de um atendimento reunidas num recurso só, veja Conduta; para as condutas registradas como condição, Condição; para o procedimento em si, Procedimento.