Hospitalização
Hospitalização
Uma hospitalização é a internação do paciente numa instituição — quando ela começou, quando terminou, onde, com qual profissional e por qual diagnóstico. Não é um atendimento do prontuário: é um evento que aparece na linha do tempo do paciente, ao lado do pronto atendimento, e serve para a equipe saber o que aconteceu com o paciente fora do cuidado que ela presta.
No FHIR ela é um Encounter com class.code
IMP, e é esse código que faz a Nilo criar uma hospitalização em vez de um atendimento.
No NiloCare o registro aparece em Eventos, com Evento: Hospitalização.
As regras desta página valem igualmente para o
pronto atendimento — os dois são eventos e só se
distinguem pelo class.code. Elas são bem diferentes das dos
atendimentos VR e AMB: aqui o identifier é obrigatório, o
status é calculado pela plataforma, e nenhum agendamento é criado.
Campos
Campos que a Nilo não usa
participant[].type, appointment, length e as extensões de origem, canal e desfecho não
são lidos num evento — são campos dos atendimentos. O
Encounter canônico traz ainda type, serviceType, priority, episodeOfCare, basedOn,
reasonCode, reasonReference, account, hospitalization, serviceProvider, partOf,
classHistory e statusHistory, nenhum deles lido nem gravado. Enviá-los não é recusado — o
valor fica no recurso FHIR e volta nas leituras —, mas nada no NiloCare passa a exibi-los.
O campo Referido por da tela de eventos não tem representação FHIR. Toda hospitalização escrita por esta API entra como Outros, e uma atualização redefine o valor que a equipe tiver marcado na tela.
Cadastrar ou atualizar
Não há endpoint separado para criar e atualizar. O mesmo POST faz os dois, e quem decide é
o identifier.
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 da hospitalização ao lado do seu, no system:
O identifier é obrigatório e a escrita é recusada sem ele.
Use um namespace de identificador só para eventos. Reaproveitar num evento um system +
value já usado noutro tipo de registro faz a atualização falhar com
Could not find … identifier for Encounter, porque a API acha o recurso mas não o evento.
A atualização substitui, não complementa. Um campo omitido não preserva o valor atual:
omitir location apaga o local, omitir participant apaga o profissional, omitir period.end
volta a internação para em andamento. Para mudar um campo só, reenvie o evento inteiro com o
valor novo.
A exceção é diagnosis, que só adiciona — veja Diagnósticos.
Entrada, saída e estado
period.start é a data de entrada e é obrigatório. period.end é a data de saída, opcional,
e quando enviado tem de ser maior que period.start.
O status funciona de forma diferente dos atendimentos: o FHIR R4 exige o campo, mas o valor
que você envia é descartado. A plataforma calcula o estado a partir de period.end:
Uma internação em andamento, portanto, é simplesmente uma sem data de saída:
Para dar alta, reenvie o mesmo identifier com o period.end preenchido.
O status que você enviou continua no recurso FHIR e volta na leitura imediatamente seguinte
— inclusive um cancelled ou um planned, que não têm significado aqui. O valor calculado
pela plataforma só aparece na próxima vez que o evento mudar por lá, e aí substitui o seu.
Reler o recurso logo depois do POST não confirma o estado real: use a tabela acima.
Profissional
O profissional vai em participant[].individual, e a referência precisa ter
type: "Practitioner":
O participant[].type — o CodeableConcept do papel, com ATND — não é lido num evento.
Mandá-lo não é erro, só não tem efeito.
Um profissional que não casa com nenhum cadastro é descartado em silêncio: o evento é
gravado sem profissional e a chamada responde 200. Diferente dos
atendimentos, aqui não há erro. Confira o identificador do
profissional antes de uma carga de eventos — a resposta não avisa.
Um item de participant sem individual, ou com individual.type diferente de
Practitioner, também não é lido — e o primeiro caso faz a escrita falhar com um erro
genérico. Não mande participant vazio.
Local
O local é texto livre, em location[0].location.display. Apenas o primeiro item da lista
é lido — e, ao contrário do procedimento, aqui ele é opcional:
Por compatibilidade, um location[0].location.identifier apontando para um
local de atendimento já cadastrado também é aceito, e o
nome daquele local é gravado como texto. Não há vínculo: alterar o local depois não muda o
que ficou no evento. Prefira display.
location é opcional, mas um location[0].location vazio — sem display e sem
identifier — faz a escrita falhar com um erro genérico. Ou mande o campo preenchido, ou não
mande location.
Diagnósticos
diagnosis vincula à internação condições que já existem. Cada item aponta para uma
Condição por um identificador dela — este campo não a cria:
Para criar a condição e a hospitalização na mesma chamada, mande os dois num Bundle do tipo
transaction e referencie a condição pelo fullUrl da entrada dela.
Uma condição pertence a um evento. Referenciar uma condição já vinculada a outro evento é recusado — e a recusa chega depois de a hospitalização ter sido criada na plataforma.
O resultado é uma escrita parcial ruim: a hospitalização existe na Nilo, mas o recurso FHIR
não foi criado, então o seu identifier não encontra nada no store. Um reenvio do mesmo
payload não atualiza o evento — cria uma segunda hospitalização. Trate este 400 como
duplicação a resolver, não como retry seguro: confira o vínculo da condição e o evento já
criado antes de reenviar.
diagnosis só adiciona. Remover um item do payload não desfaz o vínculo da condição com o
evento, e reenviar uma condição já vinculada àquela mesma hospitalização não é erro — é uma
operação sem efeito.
Paciente
subject é obrigatório, e o paciente tem de existir no cadastro:
Um evento 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ó as hospitalizações de um paciente, filtre por class:
A resposta é sempre um Bundle do tipo searchset. Busca sem resultados volta 200 com um
Bundle cujo entry é uma lista vazia, não 404.
Parâmetros de busca suportados
O parâmetro canônico location não encontra nada, apesar de o evento ter local: a Nilo
grava o local como texto, e esse parâmetro casa por referência. Filtrar por local não é
possível.
E participant-type também não: o papel do participante não é gravado nos 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 evento está em
resource. Ler status ou identifier na raiz da resposta não encontra nada.
Valores aceitos
class.code tem de ser IMP, no system
http://terminology.hl7.org/CodeSystem/v3-ActCode, com display inpatient encounter. É o
código do vocabulário v3-ActEncounterCode
para internação.
Os outros códigos aceitos pela API são EMER
(pronto atendimento) e VR/AMB
(atendimentos). Qualquer outro é recusado:
status aceita os nove códigos do FHIR R4 no envio, e nenhum tem efeito. Nas leituras só
in-progress e finished aparecem.
Efeitos colaterais
Vincular uma condição por diagnosis altera a condição: ela passa a pertencer a esta
hospitalização, e esta API não desfaz o vínculo. Isso é visível na página da
Condição.
Uma condição já vinculada a outro evento cria a hospitalização sem gravar o recurso FHIR. Veja Diagnósticos.
Nenhum agendamento é criado. Esse efeito é exclusivo dos
atendimentos VR e AMB.
Este endpoint não remove eventos: 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 outro código que este endpoint devolve é 429, quando o limite de escrita
do tipo de recurso é atingido.
Nos eventos as validações chegam sem expression e com o code genérico exception, e o
details.text traz um prefixo técnico (ValueError: …). Trate esses erros pela menção no
texto, não pelo code nem pelo expression.
E a mesma condição sai com mensagens diferentes conforme o tipo: o paciente não encontrado é
Could not find Patient in subject aqui e
Patient with identifier … does not exist or is not active nos
atendimentos.
O que a integração não cobre
Não há como, por esta API: filtrar eventos por local, registrar mais de um profissional num evento, desvincular uma condição de um evento, ou definir o Referido por. Também não é possível informar origem, canal ou desfecho — essas extensões valem só para os atendimentos.