Atendimentos
O atendimento é a interação entre o paciente e a equipe com a finalidade de prestar cuidado ou avaliar o estado de saúde. É o registro em torno do qual gira o resto do prontuário — a avaliação clínica, os diagnósticos, as condutas e os documentos emitidos todos apontam para ele.
No FHIR ele é um Encounter, e o campo class
decide o que a Nilo cria. Esta página cobre os dois valores que geram um atendimento no
prontuário:
Os outros dois valores aceitos, EMER e IMP, criam um evento na linha do tempo do
paciente em vez de um atendimento, e seguem regras próprias — estão em
Pronto atendimento e
Hospitalização. Qualquer outro código do vocabulário
do FHIR é recusado.
Escrever um atendimento com profissional e sem appointment cria um agendamento na agenda
daquele profissional. É o efeito colateral mais forte deste recurso. Antes da primeira carga
em volume, leia Agendamento e Efeitos colaterais.
Campos
A coluna No NiloCare traz o rótulo com que o dado aparece para a equipe; são rótulos, não caminhos de navegação: a tela pode ser reorganizada, o rótulo é o que permite conferir se o dado chegou onde você esperava.
As URLs completas das extensões estão em Extensões — nesta página elas aparecem só pelo nome final.
Campos que a Nilo não usa
O Encounter canônico tem campos que esta integração não lê nem grava: type,
serviceType, priority, episodeOfCare, basedOn, reasonCode, reasonReference,
account, hospitalization, serviceProvider, partOf, classHistory, statusHistory e
participant[].period. Ficam fora da referência de propósito. Como esta referência descreve
só o que é suportado, eles não aparecem no schema do recurso. O servidor os aceita, guarda no
recurso FHIR e devolve nas leituras seguintes, mas nada no NiloCare passa a exibi-los.
Dois em particular:
locationnão é lido num atendimento do prontuário. O local só existe nos eventos.diagnosisnão é lido aqui. Os diagnósticos de um atendimento são escritos pelo recurso Condição.
E dois campos do NiloCare não têm representação FHIR alguma: Criado em é o instante em
que a plataforma registrou o atendimento — não é period.start e não é escrito por esta API —
e o exame físico não tem campo neste recurso.
Cadastrar ou atualizar
Não há endpoint separado para criar e atualizar. O mesmo POST faz os dois, e quem decide é
o identifier: se já existir um atendimento com aquele par system + value, ele é
atualizado; se não existir, é criado.
A resposta devolve o recurso como ficou gravado:
Guarde o id: é por ele que se faz a leitura direta. A resposta traz também o identificador
Nilo do atendimento ao lado do seu, no system:
Atendimentos sincronizados há mais tempo podem carregar também um identificador no
system …/NamingSystem/care-api--appointment, sem o -v3. É o mesmo atendimento: o
system antigo é preservado para não partir o histórico. Nos registros novos só o -v3
aparece.
E as consultas antigas do histórico do paciente, que esta API não escreve, chegam com um
terceiro system: …/NamingSystem/hippocrates-api--appointment. Veja o aviso em
Ler por ID.
O identifier não é exigido pela validação, e é por isso que ele é obrigatório na prática:
sem identificador nenhum a API não tem como reconhecer o atendimento, e cada POST cria um
atendimento novo. Mande sempre a sua chave.
A atualização substitui, não complementa. Assim como no Coverage e no Practitioner, e
diferente do Patient, um campo omitido não preserva o valor atual: omitir period.end
volta o atendimento para em andamento, omitir participant apaga o responsável, e omitir as
extensões apaga origem, canal e desfecho. Para mudar um campo só, reenvie o atendimento
inteiro com o valor novo.
Exceção: o vínculo com o agendamento é preservado — veja Agendamento.
Situação do atendimento
status é obrigatório pelo FHIR R4, e os nove valores do padrão são convertidos para os três
estados que a plataforma tem:
O status que você enviou continua no recurso FHIR e volta na leitura imediatamente seguinte
— inclusive um cancelled, que a plataforma não tem. O valor da plataforma só aparece na
próxima vez que o atendimento mudar por lá, e aí substitui o seu. Ou seja: reler o recurso
logo depois do POST não confirma o que a Nilo registrou. Use a tabela acima para saber o
estado real.
Vale para todo campo que a Nilo não lê, não só para o status: um reenvio em que nada do
que a plataforma usa mudou pode não regravar o recurso FHIR, e aí a resposta traz o recurso
como ele estava antes. Se você depende de um campo que só existe no seu payload, não conte com
ele ter sido atualizado por um reenvio.
Período
period.start é obrigatório:
period.end é opcional, e quando enviado tem de ser maior que period.start — dois
valores iguais são recusados:
Profissional responsável
O FHIR permite vários participantes num atendimento; a Nilo registra um: o primeiro item
de participant cujo type traz o código ATND.
Um item de participant sem type faz a escrita falhar com um erro genérico, em vez de
ser ignorado. Se você não tem o papel do participante, não mande o participant.
O profissional precisa existir — no store FHIR e no cadastro da plataforma. Uma das duas ausências recusa a escrita, com mensagens diferentes:
O participant é opcional. Sem ele, o atendimento é criado sem responsável — e sem
agendamento:
Agendamento
Um atendimento do prontuário pode estar ligado a um agendamento na agenda do profissional, e
o campo appointment é como você diz qual:
Um único item — mais de um é recusado:
Essa validação só acontece quando há um profissional no participant. Sem profissional, dois
appointment passam sem erro e nenhum deles é usado.
Sem appointment e com profissional, um agendamento novo é criado. A API primeiro procura
um agendamento daquele profissional para aquele paciente começando exatamente em
period.start; não achando, cria um, com conflito de agenda permitido e um resumo gerado
automaticamente. O agendamento entra como Agendado se period.start está no futuro e como
Realizado se está no passado.
Uma carga histórica de atendimentos com profissional, portanto, popula a agenda de cada profissional com um agendamento por atendimento.
appointment só é considerado quando existe um participant com profissional. Enviar
appointment sem profissional não gera erro: a referência é simplesmente ignorada, e o
atendimento fica sem agendamento. E numa atualização, o agendamento já vinculado ao
atendimento é mantido — o appointment do payload não o troca.
O exemplo acima referencia o agendamento pelo system Nilo
(…/NamingSystem/care-api--scheduling-v2), que é o que você tem quando o agendamento nasceu
na plataforma. Qualquer identificador do agendamento serve, inclusive um do seu sistema.
Quando o agendamento é criado, a duração dele vem de period.end. Faltando period.end, ela
vem de length.value, em minutos:
Sem period.end e sem length, o agendamento é criado com 1 minuto de duração.
period.end tem prioridade: enviando os dois, length é ignorado.
length é lido sempre em minutos, e a unidade que você declarar é ignorada. {"value": 2, "unit": "h"} produz um agendamento de 2 minutos, não de 2 horas. Converta para minutos antes
de enviar.
Origem, canal e desfecho
Três extensões descrevem o contexto do atendimento. Todas carregam um valueCodeableConcept
cujo coding.code é o código do catálogo da sua implantação:
O coding.system precisa ser o do catálogo correspondente — {host}/fhir/resources/CodeSystem/encounter-admitSource
e equivalentes. Um coding em outro system é ignorado, e a extensão não tem efeito. Aqui,
diferente do class, o system é conferido.
Havendo mais de uma extensão com a mesma URL no payload, vale a primeira. E na leitura a
Nilo devolve o display e o text preenchidos com o nome do item do catálogo, que é o que
aparece na tela — no envio esses dois campos não são necessários.
Os códigos de origem, canal e desfecho são configurados por implantação, e não há catálogo
publicado nesses system: GET /fhir/resources/CodeSystem/encounter-admitSource responde
404. Peça a lista ao Suporte, ou leia um atendimento já registrado pela plataforma e
aproveite os códigos que vierem nas extensões.
Paciente
subject é obrigatório, e o paciente tem de existir — no store FHIR e no cadastro da
plataforma. As duas ausências têm mensagens diferentes:
Um atendimento não cria paciente. Cadastre o Paciente primeiro.
Buscar
A busca é a mesma para atendimentos e eventos, porque os quatro tipos são o mesmo recurso
FHIR. Para trazer só os atendimentos do prontuário, filtre por class:
A resposta é sempre um Bundle do tipo searchset, mesmo quando há um único resultado:
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
Qual identificador do paciente o subject carrega depende da sua implantação. Na
configuração que usa identificadores externos nas referências, é o identificador do seu
sistema — e o filtro acima funciona como está. Sem ela, o subject traz o identificador Nilo
do paciente (…/NamingSystem/hippocrates-api--patient), e é esse system que você tem de
usar no filtro. Confira numa resposta de leitura qual dos dois está lá antes de montar a
busca em volume. O mesmo vale para practitioner.
Vários parâmetros canônicos do Encounter existem e não encontram nada aqui, porque a
Nilo não preenche o campo correspondente: type, service-provider, episode-of-care,
based-on, part-of, reason-code, reason-reference, account e special-arrangement.
appointment e length só encontram os atendimentos em que você enviou aqueles campos —
a plataforma não os produz por conta própria. E location e diagnosis só encontram eventos.
Ler por ID
A leitura por ID responde 404 quando o id não existe.
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 atendimento está em
resource. Ler status ou identifier na raiz da resposta não encontra nada.
Nem tudo o que você lê foi escrito por esta API. Atendimentos registrados pela equipe no
NiloCare aparecem aqui do mesmo jeito — e consultas mais antigas do histórico do paciente vêm
com class AMB, status finished e um participant que traz apenas o papel, com o
código CBO da especialidade em type, sem individual. É a especialidade que atendeu, não a
pessoa.
Valores aceitos
Classes
class.code usa o vocabulário
v3-ActEncounterCode. Os dois códigos
desta página:
O system esperado é http://terminology.hl7.org/CodeSystem/v3-ActCode. Os códigos que criam
evento em vez de atendimento — EMER e IMP — estão nas páginas dos eventos. Qualquer outro
código do vocabulário (HH, SS, OBSENC, PRENC, FLD, ACUTE, NONAC) é recusado:
Situações
status aceita os nove códigos do FHIR R4 no envio. Nas leituras, só três aparecem:
planned, in-progress e finished. A conversão está em
Situação do atendimento.
Papel do participante
participant[].type usa o vocabulário
v3-ParticipationType. O único
código com significado aqui é ATND (attender), e é o que a Nilo devolve nas leituras.
Catálogos de origem, canal e desfecho
Não são vocabulários desta API: são catálogos que a sua implantação mantém, e o code é o id
do item no catálogo. Não há catálogo publicado nesses system — veja o aviso em
Origem, canal e desfecho.
Efeitos colaterais
Um atendimento com profissional e sem appointment cria um agendamento na agenda daquele
profissional, com conflito de agenda permitido.
Reenviar um atendimento cujo identificador aponta para um registro que não existe mais na
Nilo faz a API remover o recurso FHIR órfão e criar um atendimento novo em seguida. É a
forma de não deixar dois recursos com o mesmo identificador, mas o id Nilo FHIR muda: o id
que você tinha guardado deixa de resolver.
Este endpoint não remove atendimentos: a escrita nunca responde 204. A remoção acontece do
lado da plataforma e é propagada para o store FHIR pela sincronização.
Erros
Recusa é 400, e o corpo é um OperationOutcome: issue[].expression aponta o campo culpado
e issue[].details.text explica o motivo. O outro código que este endpoint devolve é 429,
quando o limite de escrita do tipo de recurso é atingido — nesse caso, aguarde e repita.
Há uma exceção de forma. O class.code não suportado é recusado antes de o atendimento chegar
à camada FHIR, e volta com só um campo errors com a mensagem, sem issue, sem code e sem
expression:
O que a integração não cobre
A avaliação clínica, o exame físico e os pontos de atenção de um atendimento não são campos
do Encounter: estão em Avaliação clínica. As condutas e
orientações estão em Conduta, os diagnósticos do atendimento em
Condição e os medicamentos em
Medicamento. Os documentos emitidos no atendimento
— prescrição, solicitação de exame e encaminhamento — também têm recursos próprios. O plano de
cuidado do paciente não é alcançável a partir do atendimento.
Também não há como, por esta API: registrar mais de um profissional num atendimento, ou informar o local de um atendimento do prontuário — local só existe nos eventos.