Catálogo de códigos
Um catálogo de códigos é a lista de valores que a plataforma aceita num campo codificado. Hoje há dois, e os dois servem à etiqueta do paciente:
No FHIR o recurso é o
CodeSystem, e ele existe aqui por um motivo
prático: os códigos não são um vocabulário fixo. Cada ambiente tem os seus, cadastrados na
implantação, e a única forma de saber quais existem é lendo estes catálogos.
Este recurso é somente leitura. Não existe POST /fhir/resources/CodeSystem — os catálogos
são montados pela equipe no Nilo Care, nas configurações do ambiente.
Campos
Todos os campos são de resposta — nenhum deles é enviado por você.
concept[].code é o valor que vai em Flag.code.coding[].code (ou em
Flag.category.coding[].code), e concept[].display é o nome que a equipe vê. São os dois
únicos dados de cada código: não há descrição, hierarquia, sinônimo nem propriedade.
Só os códigos vigentes aparecem. Uma etiqueta encerrada no Nilo Care some do catálogo — e some sem deixar rastro, porque não há campo de situação por código.
Consequência: uma etiqueta aplicada a um paciente pode referenciar um código que não está
mais no catálogo. Ao ler uma etiqueta, não conte com encontrar o
código dela aqui — o display da própria etiqueta já traz o nome.
Ler um catálogo
O caminho é GET /fhir/resources/CodeSystem/{nome}, com flag-code ou flag-category.
Este é o único caminho do projeto em que o segmento final não é o id do recurso. Em todos
os outros recursos, /{id} é o identificador Nilo FHIR; aqui é o nome do catálogo.
Passar o id do recurso neste caminho não funciona — e é justamente o que o fullUrl do
envelope traz. Ignore o fullUrl deste recurso: para reler o catálogo, monte o caminho com o
nome.
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 catálogo está em resource. Ler concept na
raiz da resposta não encontra nada.
Buscar
A resposta é sempre um Bundle do tipo searchset. Como só há dois catálogos, a busca sem
filtro devolve os dois:
Busca sem resultados não é erro: volta 200 com um Bundle cujo entry é uma lista vazia.
Parâmetros de busca suportados
Os demais parâmetros canônicos do CodeSystem existem e não encontram nada, porque a
plataforma não preenche o campo correspondente: name, title, version, identifier,
context, jurisdiction, description, language e supplements.
Como o catálogo é atualizado
Qualquer alteração numa etiqueta republica o catálogo inteiro. O recurso é sempre a lista
completa: acrescentar, renomear ou encerrar uma etiqueta reescreve o CodeSystem inteiro, com
um meta.versionId novo.
Isso vale inclusive para a remoção: encerrar uma etiqueta não apaga o catálogo — ele é republicado sem ela. Não trate uma mudança de versão do catálogo como sinal de que algo específico mudou; compare as listas.
Encerrar uma categoria encerra, junto, todas as etiquetas dela — então uma única ação faz os dois catálogos mudarem de versão ao mesmo tempo.
Como o catálogo é pequeno e muda pouco, o padrão de uso recomendado é lê-lo uma vez, guardar o mapa código → nome do seu lado, e reler quando uma etiqueta trouxer um código que você não conhece.
Cadastrar ou atualizar
Não existe. Este recurso não tem caminho de escrita nesta API — nem para criar um catálogo, nem para acrescentar um código a um existente.
Um POST /fhir/resources/CodeSystem não é uma operação suportada e não devolve um erro de
validação tratável: a chamada falha com erro inesperado do servidor (500). Não escreva
tratamento em cima desse comportamento — ele não é contrato, e nada é gravado.
Para cadastrar uma etiqueta nova no catálogo, peça à equipe que a crie em Configurações › Etiquetas, no Nilo Care — lembrando que a categoria precisa existir antes da etiqueta.
O que a integração não cobre
- outros catálogos: só etiquetas e categorias de etiqueta são publicados assim. Os códigos de procedimento, de especialidade e de diagnóstico usam vocabulários externos, e não têm catálogo próprio nesta API;
- a situação de cada código — encerrados simplesmente somem;
- a hierarquia entre códigos, e qualquer propriedade além de
codeedisplay; - a ligação entre uma categoria e as etiquetas que pertencem a ela: os dois catálogos são listas planas, e o vínculo só aparece na leitura de uma etiqueta, que traz as duas.