Etiqueta
Uma etiqueta é um marcador que a equipe pendura num paciente para sinalizar alguma coisa sobre ele — Gestante, Alto risco, Prioridade no atendimento. Ela tem vigência: começa num dia e pode terminar noutro.
No FHIR o recurso é a Flag, e esta integração o usa nas
duas pontas: aplicar uma etiqueta a um paciente e consultar as que ele tem.
A etiqueta em si não é criada por aqui. O que você aplica é uma etiqueta que já existe no catálogo do seu ambiente, e o catálogo é montado pela equipe em Configurações › Etiquetas — onde a categoria precisa ser criada antes da etiqueta. Para descobrir quais etiquetas existem, e os códigos delas, leia o catálogo de códigos.
Campos
code.text, code.coding[].display, category e os display dela vêm do catálogo na
leitura. Enviá-los não tem efeito: quem identifica a etiqueta é o par system + code.
E category vem sempre na leitura, mesmo que você não a tenha enviado — ela é derivada da
etiqueta.
status e period têm de concordar
Esta é a regra que mais recusa chamadas neste recurso. A API confere se o status que você
mandou bate com o period:
status não é um campo livre: é uma afirmação sobre o period, e ela é verificada. Mandar
active numa etiqueta com vigência futura não a agenda — recusa a chamada.
E o status gravado não muda sozinho. Ele é calculado no momento da gravação, não da
leitura: uma etiqueta gravada como inactive com vigência futura continua sendo devolvida como
inactive depois de a data chegar, até que alguma coisa altere a etiqueta na plataforma.
Não conte com a virada automática. Se você agenda etiquetas, reenvie o recurso com
status: active quando a vigência começar — ou compare o period com a data de hoje do seu
lado.
status é derivado do período, não um estado à parte: não existe uma etiqueta “desativada mas
dentro da vigência”.
Encerrar uma etiqueta
Reenviar o mesmo identifier com status: inactive e sem period encerra a etiqueta no
instante da chamada.
Não há remoção por integração: este endpoint nunca responde 204. Encerrar é a forma de tirar
uma etiqueta do paciente, e o registro continua existindo com a vigência fechada.
Campos que a Nilo não usa
A Flag canônica traz mais do que esta integração lê: encounter, author e text. Nenhum
deles é lido — em particular, não há como registrar quem aplicou a etiqueta nem a que
atendimento ela se refere.
A referência lista só os campos suportados, não os permitidos: a API em si não recusa quem manda os outros — eles ficam guardados no recurso e voltam nas leituras seguintes, sem nunca terem significado nada para a plataforma. Se o seu validador for estrito contra a referência, uma resposta assim vai parecer inválida; o remédio é não enviá-los.
Aplicar uma etiqueta
A resposta é o recurso gravado, sem envelope:
Guarde o id: é por ele que se faz a leitura direta. Ao lado do seu identifier, a resposta
traz o identificador Nilo da etiqueta aplicada, no system
…/NamingSystem/hippocrates-api--patient-tag.
Mandando mais de um identifier, eles são testados na ordem em que aparecem no payload, e o
primeiro que casar com uma etiqueta existente vence.
O código da etiqueta
O código vai num coding cujo system é {host}/fhir/resources/CodeSystem/flag-code, com o
host do seu ambiente:
Um coding em qualquer outro system é ignorado, e não sobrando nenhum no system certo a
chamada é recusada com Invalid system …. Confira a URL — o system é o mesmo valor que o
url do catálogo.
O código precisa existir no catálogo do seu ambiente. Um código válido em homologação pode não existir em produção: os catálogos são independentes.
A categoria
category é opcional — e, quando você a manda, ela não classifica nada: é conferida contra
a categoria à qual a etiqueta já pertence.
Mandar uma categoria que não é a da etiqueta recusa a chamada
(Tag does not belong to the category). Se você não tem certeza, omita — a leitura vai
trazer a categoria certa de qualquer forma.
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
status, code e category são preenchidos no recurso e não são filtráveis. O Flag do
FHIR R4 não define parâmetro de busca para nenhum dos três — não há como pedir “as etiquetas
ativas” nem “os pacientes com a etiqueta 318”.
Para isso, busque por paciente ou por date e filtre do seu lado.
author e encounter são parâmetros canônicos que funcionam — mas só encontram as
etiquetas em que você enviou o campo, já que a plataforma nunca o preenche.
A paginação é por _count e _page_token; havendo página seguinte, o Bundle traz a URL
pronta em link.
A busca devolve também as etiquetas aplicadas pela equipe dentro do Nilo Care. Essas trazem
apenas o identificador Nilo — não haverá um identifier seu. É por essa diferença que você
separa umas das outras.
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 etiqueta está em
resource.
Efeitos colaterais
Aplicar uma etiqueta não notifica ninguém e não cria nada. Ela aparece como um chip no cartão de cabeçalho do paciente, com o ícone e a cor da categoria — que é onde a categoria, que não classifica nada na escrita, acaba tendo efeito visível.
Etiqueta encerrada no catálogo continua aplicada. Se a equipe encerrar uma etiqueta nas
configurações, ela some do catálogo mas as aplicações
existentes continuam sendo devolvidas na busca — com o display que tinham.
Encerrar uma categoria encerra, junto, todas as etiquetas dela — e também não afeta as aplicações já feitas.
Erros
Recusa é 400 — com uma exceção, o 409 da etiqueta repetida. O corpo é um
OperationOutcome: issue[].expression aponta o campo culpado e issue[].details.text explica
o motivo.
E, fora do 400:
Um paciente não pode ter a mesma etiqueta aplicada duas vezes em vigência simultânea. A
segunda aplicação é recusada com 409, mesmo com um identifier diferente — a plataforma
compara o par paciente + etiqueta, não a sua chave. Encerre a primeira antes de aplicar de novo.
Os payloads completos estão na aba Referência, em POST /fhir/resources/Flag.