Extensões
Extensões são o mecanismo do FHIR para carregar informação que o recurso padrão não prevê. Elas não alteram a estrutura do recurso: convivem com os campos padrão, e um sistema que não conhece uma extensão continua processando o resto do recurso normalmente.
Na Nilo é por aí que trafega o que é específico da plataforma — o status do paciente, o grupo a que
ele pertence, as decisões de onboarding. Algumas são obrigatórias no envio, então esta página não é
opcional para quem vai escrever um Patient.
A URL é a chave
Cada extensão é identificada por uma URL, e a comparação é de igualdade exata da string inteira.
Não há normalização: nem barra final, nem http por https, nem casamento por sufixo. A URL que
você manda é a URL que a Nilo procura, caractere por caractere.
As extensões da Nilo ficam sob:
Repare no /resources. E {host} é o host do ambiente que você está chamando — os dois estão em
Introdução.
Uma URL de extensão errada não gera erro de URL: a extensão simplesmente não é encontrada. Nas
extensões opcionais o valor enviado é ignorado em silêncio — num paciente que já existe a API
preserva o valor atual, e num paciente novo aplica o padrão da unidade de cuidado. Nas duas
obrigatórias (patient-sendWelcomingMessage e patient-createOnboardingScheduling) o resultado é
um 400 dizendo que a extensão é obrigatória, mesmo estando ela ali no payload.
Os dois erros mais comuns são omitir o /resources e usar o host de produção contra homologação.
O tipo do valor também é a chave
O nome do campo de valor — valueBoolean, valueString, valueIdentifier,
valueCodeableConcept, valueUrl — faz parte do contrato de cada extensão. A leitura busca
exatamente aquele campo: um valueString onde se espera valueBoolean é lido como ausente,
com o mesmo desfecho silencioso de uma URL errada. Por isso o catálogo abaixo traz o tipo de cada
uma.
Onde aplicar
Uma extensão só é lida no nível em que foi projetada. As de Patient, Coverage,
Practitioner e Encounter ficam no extension da raiz do recurso; algumas são compostas e carregam as
suas próprias extensões aninhadas, e aí o filho só é encontrado dentro do pai — nunca na raiz.
É o caso do practitioner-user-active, que fora de practitioner-user não tem efeito nenhum, e
do patient-paths, que a API devolve nas leituras:
Também não convém reescrever a estrutura de uma extensão — trocar o nome do campo de valor, achatar uma composta ou acrescentar elementos à definição produz o mesmo resultado de não a ter enviado.
Catálogo
As extensões da Nilo estão listadas pelo sufixo; o prefixo é
{host}/fhir/resources/StructureDefinition/, com o {host} do ambiente que você chama. As duas do
hl7.org estão por extenso, porque não ficam sob esse prefixo.
O que cada uma significa no fluxo do recurso — quais são exigidas, com o que precisam concordar, o que acontece na atualização parcial — está na página do recurso: Paciente, Cobertura, Profissional, Atendimentos e Agendamento.
Nas três extensões do Encounter o coding.system também é load-bearing: precisa ser
{host}/fhir/resources/CodeSystem/encounter-admitSource (e equivalentes). Um coding no system
errado é lido como ausente, com o mesmo desfecho silencioso de uma URL errada. Elas valem apenas
nos atendimentos de class VR e AMB — nos eventos (EMER e IMP) são gravadas e
ignoradas.
patient-religion é assimétrica. A escrita aceita a URL sob o prefixo da Nilo, mas a leitura
devolve http://hl7.org/fhir/StructureDefinition/patient-religion. Ou seja: reenviar um recurso
exatamente como ele veio numa resposta não preserva a religião — reenvie a URL da Nilo.
O grupo tem o mesmo tipo de assimetria: você envia em Group e a resposta traz patient-cohort,
com o id Nilo do grupo. As duas descrevem o mesmo vínculo.
As três extensões de acesso do Practitioner são as únicas desta lista que agem fora do
recurso: enviá-las cria ou remove um usuário com acesso ao NiloCare. Não as inclua num
payload de rotina só porque a plataforma as devolveria — a leitura não as devolve, e mandar
practitioner-user-active: false num reenvio remove o acesso de quem já tinha.
Exemplo
O cadastro completo de paciente manda seis extensões de uma vez: as duas obrigatórias, isLead, e
as três do hl7.org:
E a resposta traz as que a Nilo gera, incluindo a composta patient-paths:
Extensões que a Nilo não conhece
Fora as obrigatórias, mande uma extensão só quando ela for relevante para aquele recurso: omitir uma extensão opcional preserva o valor que já está gravado.
Uma extensão cuja URL a Nilo não reconhece não é recusada nem descartada — ela é gravada no recurso e volta nas leituras seguintes, sem nenhum efeito sobre os dados da Nilo. Isso é útil para carregar metadado seu, e é uma armadilha quando a intenção era usar uma extensão da plataforma e a URL saiu errada: o payload volta parecendo correto.