Condição
Condição
Uma condição é qualquer problema de saúde que a equipe registra sobre o paciente: o diagnóstico fechado num atendimento, uma doença crônica que o acompanha há anos, ou a conduta que o profissional orientou ao encerrar a consulta.
No FHIR todos esses casos são o mesmo recurso, a
Condition — e é aqui que este recurso pede
atenção. Dois campos do payload decidem qual dos três registros a Nilo cria, e eles não
parecem campos de decisão: passam por descrição.
A ordem é essa: provisional é conferido primeiro e ganha de tudo. Um payload com
verificationStatus provisional e category event grava uma conduta, não um evento.
A consequência mais séria dessa regra aparece num ida-e-volta. Um diagnóstico marcado como
Hipótese na plataforma é lido com verificationStatus provisional. Reenviar esse
mesmo recurso de volta não atualiza o diagnóstico nem grava a conduta: a escrita falha com
400 e uma mensagem genérica de recurso não localizado, porque o identifier enviado já
pertence a uma condição de outro destino. Se o seu integrador lê condições e as reescreve,
filtre os provisional antes de reenviar.
Os três destinos compartilham um endpoint, um schema e uma busca. O que muda é quais campos são lidos, quais são obrigatórios e o que acontece de efeito colateral — e é isso que o resto desta página detalha.
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.
O que muda de destino para destino
Campos que a Nilo não usa
A Condition canônica tem campos que esta integração não lê nem grava: asserter,
severity, bodySite, stage, evidence, onsetPeriod, onsetAge, onsetString,
abatementPeriod, abatementAge, abatementString, abatementBoolean e encounter como
lista. 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.
E dois dados que o NiloCare mostra não têm campo nesta API: a cor e o ícone com que a
condição é destacada na ficha, e o autor de cada nota de diagnóstico — a nota volta com
authorReference, mas ele é da plataforma, não do seu payload.
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 uma condição com aquele par system + value, ela é
atualizada; se não existir, é criada.
A resposta devolve o recurso como ficou gravado, sem envelope:
O reconhecimento é por destino: a busca pelo seu identifier é restrita às condições
daquele mesmo destino. Um identifier já usado num diagnóstico não atualiza um evento clínico
com o mesmo valor — e reenviá-lo apontando para outro destino falha, como no aviso acima.
Guarde o id: é por ele que se faz a leitura direta. A resposta traz também o identificador
Nilo da condição ao lado do seu, e o system dele diz qual dos três destinos gravou:
Diagnósticos de atendimento carregam também um identificador no system
…/NamingSystem/care-api--patient-diagnosis, sem o -v3. É o mesmo diagnóstico: o system
antigo é preservado para não partir o histórico dos registros anteriores.
Nas duas variantes de diagnóstico 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
a condição, e cada POST cria uma condição nova. Mande sempre a sua chave.
Na conduta é diferente: a validação recusa o payload sem identifier, com o code
required.
A atualização substitui, não complementa. Assim como no Coverage, no Practitioner e no
Encounter, e diferente do Patient, um campo omitido não preserva o valor atual na
plataforma: num evento clínico, omitir abatementDateTime reabre a condição, e omitir
onsetDateTime apaga o início. Para mudar um campo só, reenvie a condição inteira com o valor
novo.
Uma exceção nos três destinos: encounter é preservado. Omiti-lo não desvincula a
condição do atendimento — o vínculo atual continua valendo. Não há como desfazer um vínculo por
esta API.
E o recurso FHIR que você lê depois não reflete o apagamento. Na regravação, o valor que já
estava guardado sobrevive onde a plataforma não gera um novo: omitir onsetDateTime zera o
início na plataforma, mas a leitura seguinte continua devolvendo o onsetDateTime anterior. Se
você precisa confirmar que um campo foi apagado, não confie na releitura do recurso.
O diagnóstico
code é como você diz qual é o diagnóstico, e o coding[0].system tem de ser um dos três
catálogos que a plataforma mantém:
Só o primeiro coding de code é lido. Mandar o CID-10 em coding[1] e outra
terminologia em coding[0] faz a escrita ser recusada pelo coding[0], e o CID-10 nunca é
considerado. Ponha o código que vale na primeira posição.
O código precisa existir no catálogo — não há criação de diagnóstico por esta API. Um system
fora dos três e um código inexistente têm mensagens diferentes: Unknown diagnosis system: …
com o code not-supported, e Unknown … with code: … com o code not-found. Os dois
payloads completos estão na aba Referência, em POST /fhir/resources/Condition.
Na leitura, code.text e code.coding[0].display vêm preenchidos com a descrição oficial do
item do catálogo, não com o que você enviou. No envio esses dois campos não são necessários.
code não é lido na conduta, e mandá-lo lá não é erro — a conduta simplesmente o ignora.
O profissional
recorder é o profissional que registrou a condição, e é obrigatório nas duas variantes de
diagnóstico. O profissional precisa já estar cadastrado; veja
Profissional.
Faltando o campo, a recusa vem com o code required e o expression Condition.recorder.
Havendo o campo com um identificador que não resolve, vem Professional does not exist com o
code not-found.
Na conduta, recorder não é lido: a conduta gravada não tem autor, mesmo que você mande um.
O paciente
subject é obrigatório nos três destinos, e o paciente tem de existir — uma condição não
cria paciente. Cadastre o Paciente primeiro.
A mesma recusa cobre os dois casos: subject ausente e subject com um identificador que não
resolve saem os dois como not-found com Patient does not exist, não como required.
O atendimento
encounter liga a condição a um atendimento, e o que ele aceita depende do destino.
Nas duas variantes de diagnóstico e na conduta, é um atendimento do prontuário — veja Atendimentos. O campo é opcional: sem ele, o diagnóstico é registrado sem vínculo.
No evento clínico, encounter só aceita uma hospitalização ou um pronto atendimento.
Apontar para um atendimento do prontuário é recusado com … is not an event.
A referência é sempre por identifier, não pelo id do store. É o identificador do seu
sistema que você usou ao criar o atendimento — a API resolve a partir dele.
Datas
O evento clínico é o único destino que lê datas do payload: onsetDateTime é o início da
condição e abatementDateTime é o fim. Nos outros dois, os dois campos são aceitos e não
gravam nada.
No evento clínico, o que você manda em onsetDateTime volta em recordedDate, não em
onsetDateTime. Enviar e reler não devolve o mesmo payload: o onsetDateTime que aparece na
leitura é o que ficou guardado do seu próprio envio, não o valor que a plataforma registrou.
Para saber o início da condição de verdade, leia recordedDate.
Nos outros dois destinos recordedDate é outra coisa: no diagnóstico de atendimento é a data
em que o diagnóstico foi registrado, sem hora; na conduta é o instante em que a conduta foi
criada. Nenhum dos dois aceita o campo na escrita.
Situação da condição
clinicalStatus e verificationStatus aparecem no NiloCare como dois seletores no mesmo menu
de status da condição — Alterar status clínico e Alterar verificação — e é assim que a
equipe muda o status de um diagnóstico. Pela API eles funcionam de outra forma.
Agudo e Crônico são estados de verificação que a plataforma reconhece e que esta
integração não representa: um diagnóstico nesses dois estados volta sem
verificationStatus e sem clinicalStatus, indistinguível de um diagnóstico sem status. Não
conclua “sem status” a partir da ausência dos dois campos.
O eixo Ativo / Inativo que a aba de condições oferece também não sai nesta API: num
diagnóstico de atendimento, o único valor que clinicalStatus assume é o resolved da tabela
acima. Uma condição marcada como Inativa na tela continua sem clinicalStatus.
Essa tabela descreve a leitura. Na escrita, não há como definir o status de um
diagnóstico por esta API: clinicalStatus é ignorado, e verificationStatus só serve para
rotear — mandar confirmed ou unconfirmed não grava nada, e mandar provisional troca o
destino: com um identifier novo grava uma conduta, e com o identifier de um diagnóstico que
já existe falha com 400. Um diagnóstico criado por aqui nasce sem status, e quem o define é a
equipe na tela.
Como o valor que você enviou continua no recurso FHIR, ele volta na leitura imediatamente
seguinte ao POST — mesmo sem ter sido gravado na plataforma. O valor real aparece na próxima
vez que o diagnóstico mudar por lá, e aí substitui o seu. Reler o recurso logo depois do
POST não confirma o que a Nilo registrou.
Vale para a maioria dos campos que a Nilo não lê. note num diagnóstico de atendimento é a
exceção: ele não é apenas ignorado, é descartado — a resposta traz as notas da plataforma,
que num diagnóstico recém-criado é uma lista vazia, e não as suas.
E um reenvio em que nada do que a plataforma usa mudou pode não regravar o recurso FHIR: nesse caso a resposta traz o recurso como ele estava antes.
No evento clínico os dois campos são derivados e não há o que enviar: verificationStatus é
sempre confirmed, e clinicalStatus é resolved quando há abatementDateTime e active
quando não há.
Evento clínico
O evento clínico é a condição que não pertence a um atendimento: a doença crônica, o
histórico que o paciente já traz. Ele é escolhido por um coding no system
{host}/fhir/resources/CodeSystem/condition-category com o código event:
O system desse coding é conferido. Um coding com o código event em outro system — no
system do FHIR, por exemplo — não roteia: a condição vira um diagnóstico de atendimento.
O mesmo acontece com um category que traga vários coding no system da Nilo com códigos
diferentes: a ambiguidade não é recusada, é descartada, e o destino vira o padrão.
Um evento clínico só aparece no NiloCare quando está associado a uma hospitalização ou a um
pronto atendimento. A associação é feita de duas formas: pelo encounter da própria
condição, ou pelo diagnosis[].condition do evento — veja
Hospitalização e
Pronto atendimento. Um evento clínico sem
nenhuma das duas fica gravado e não é exibido.
Para criar a condição e o evento numa chamada só, use um Bundle do tipo transaction: o
diagnosis[].condition do evento referencia o fullUrl da condição criada na mesma
requisição. Fora do Bundle, a condição precisa já existir e a referência é pelo identifier
dela. Uma condição pertence a um evento — vincular a mesma condição a um segundo é
recusado.
Vincular várias condições ao mesmo evento é aceito, mas o evento na linha do tempo mostra uma delas — a alterada mais recentemente. As outras ficam gravadas e vinculadas, e são alcançáveis pela busca; elas só não aparecem todas no evento.
Conduta do atendimento
A conduta é o que o profissional orientou ao encerrar o atendimento. Ela é escolhida por
verificationStatus provisional, e nela o conteúdo é o note: cada item da lista é uma
linha da conduta.
Há um segundo caminho para gravar conduta, pela
Solicitação de serviço com intent: proposal.
Escolha um dos dois: gravar a mesma conduta pelos dois cria registros diferentes.
Nesse destino, code e recorder não são lidos, identifier é obrigatório e note também:
uma conduta sem note falha com um erro genérico, não com required.
E falha depois de o atendimento de suporte ter sido criado. Uma conduta sem encounter e
sem note devolve 400 e deixa um atendimento vazio no prontuário do paciente. Confira que
note está preenchido antes de enviar.
Na leitura, a conduta vem com um note por linha; na escrita, as linhas que você manda são
juntadas numa só anotação 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.
Uma conduta sem encounter cria um atendimento. A API precisa de um atendimento onde
pendurar a conduta, e não achando um, cria um atendimento já finalizado para servir de
suporte. Uma carga de condutas sem encounter, portanto, popula o prontuário do paciente com
um atendimento por conduta.
Numa atualização de conduta, o atendimento já vinculado é mantido — o encounter do
payload não o troca, e nenhum atendimento novo é criado. A troca de atendimento de uma
conduta existente não é possível por esta API.
Na criação, o paciente do atendimento referenciado tem de ser o mesmo de subject; não
sendo, a escrita é recusada com Encounter's patient does not match the resource's patient. Na
atualização essa conferência não acontece, porque o encounter do payload não é nem resolvido.
Um encounter que não resolve, na conduta, também não sai como not-found: sai com o code
genérico exception.
Buscar
A busca é a mesma para os três destinos, porque são o mesmo recurso FHIR. Para trazer só um
deles, filtre por category ou por verification-status:
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 recorder e encounter.
Vários parâmetros canônicos da Condition existem e não encontram nada aqui, porque a
Nilo não preenche o campo correspondente: asserter, severity, body-site, evidence,
evidence-detail, stage, abatement-string, onset-info e onset-age.
onset-date é um caso à parte: ele só encontra as condições em que você enviou
onsetDateTime, porque a plataforma não produz esse campo — nem nos eventos clínicos, onde o
início da condição sai em recordedDate. abatement-date tem meia ressalva do mesmo tipo:
fora dos eventos clínicos, ele encontra apenas as condições em que você enviou
abatementDateTime.
E recorder não encontra condutas, que são gravadas sem profissional.
A paginação é por _count e _page_token; havendo página seguinte, o Bundle traz a URL
pronta em link.
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 a condição está em
resource. Ler code ou identifier na raiz da resposta não encontra nada.
Nem tudo o que você lê foi escrito por esta API. Diagnósticos, condições e condutas
registradas pela equipe no NiloCare aparecem aqui do mesmo jeito — e são eles que trazem
verificationStatus e clinicalStatus com o status real, e as notas de diagnóstico com
authorReference.
Valores aceitos
Catálogos de diagnóstico
Três terminologias, e o code é o código do item nela: CID-10
(http://hl7.org/fhir/sid/icd-10), CIAP-2 (http://hl7.org/fhir/sid/icpc-2) e NANDA
(http://terminology.hl7.org/CodeSystem/nanda). Qualquer outro system no coding[0] é
recusado.
Os três são catálogos da plataforma, e o código tem de existir neles. Para descobrir o código
de um diagnóstico, leia uma condição já registrada pela plataforma e aproveite o code que
vier — ou peça a lista ao Suporte.
Classificação
category usa dois system. O do FHIR,
condition-category, aparece nas
leituras com o código encounter-diagnosis e é constante. O da Nilo,
{host}/fhir/resources/CodeSystem/condition-category, é o que roteia e o que identifica o
destino na leitura:
patient-diagnosis é devolvido nas leituras, mas não é preciso enviá-lo: o diagnóstico de
atendimento é o destino padrão, e um payload sem category nenhum chega lá.
Situação e verificação
clinicalStatus usa
condition-clinical e
verificationStatus usa
condition-ver-status. Dos
valores do padrão, a plataforma devolve active e resolved no primeiro e unconfirmed,
provisional e confirmed no segundo. Na escrita, o único valor com efeito é o provisional
que roteia para a conduta.
Efeitos colaterais
Uma conduta sem encounter cria um atendimento já finalizado no prontuário do paciente,
para servir de suporte à conduta.
verificationStatus provisional muda o tipo de registro, não só o status. É o efeito
colateral mais fácil de disparar sem querer: basta reenviar um diagnóstico provável que foi
lido desta API.
Vincular uma condição a uma hospitalização ou pronto atendimento pelo diagnosis do evento
altera a condição: ela passa a pertencer àquele evento. Uma condição pertence a um evento só,
e a segunda tentativa é recusada — veja o aviso em
Hospitalização.
Este endpoint não remove condições: 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 é 409,
quando a condição conflita com um registro já existente na plataforma.
Os payloads completos estão na aba Referência, em POST /fhir/resources/Condition.
A última linha da tabela agrupa quatro situações que não saem como required nem como
not-found, e sim com o code genérico exception e sem expression. São elas que um
integrador tende a tratar errado: não espere um erro de campo obrigatório para code ausente
nem para note ausente, e não espere not-found para um encounter de conduta que não
resolve. Confira o payload antes de enviar.
O que a integração não cobre
O status de um diagnóstico não é definível por esta API — nem na criação, nem depois. Também não há como registrar a gravidade, o local do corpo, o estadiamento ou a evidência de uma condição, nem adicionar uma nota a um diagnóstico já criado, nem desfazer o vínculo de uma condição com o atendimento dela.
O diagnóstico de atendimento tem início e fim na plataforma, e esta API não os escreve nem
os lê: onsetDateTime e abatementDateTime só chegam ao registro no evento clínico. Um
diagnóstico com período definido pela equipe volta sem nenhuma data além do recordedDate.
A avaliação clínica e o exame físico do atendimento estão em Avaliação clínica, e a leitura consolidada das condutas de um atendimento está em Conduta. Os medicamentos e os pedidos de exame de um atendimento têm recursos próprios.