Identificadores
Um identificador é o que liga um registro do seu sistema ao mesmo registro dentro da Nilo. É ele
que decide se um POST cria ou atualiza — isso está em Escritas.
Esta página cobre o resto: o que a API lê de um identificador, quais identificadores ela devolve, como apontar de um recurso para outro e como buscar por identificador.
O que a API lê de um identificador
O use não é decorativo, mas também não é lido em todo lugar. No Patient ele decide três coisas:
um CPF com use: official pode sobrescrever um CPF já gravado e um CPF com qualquer outro use
só entra se ainda não houver nenhum; um name com use: official é o nome civil e com
use: usual é o nome social; um telefone com use: old ou use: temp é descartado em vez de
derrubar a requisição. Os detalhes estão em Paciente. Fora desses
casos, o use é apenas armazenado.
Os identificadores que a Nilo devolve
Toda resposta traz mais identificadores do que você enviou: o seu, mais os que a Nilo emite. Os dela seguem sempre a mesma forma:
Onde {api} é o microsserviço Nilo que é dono do registro e {recurso} é o modelo, em
kebab-case. Por exemplo, o id interno do paciente:
O value desse identificador é a chave primária do registro na Nilo, então ele serve para buscar
e para referenciar sem nenhuma tradução no meio. A lista dos que voltam num paciente está em
Paciente.
O {host} faz parte do identificador — não é enfeite. Um identificador Nilo de produção enviado
para homologação não é reconhecido, e o recurso é recusado na validação. Use sempre o host do
ambiente que você está chamando; os dois estão em Introdução.
Quais system a Nilo aceita no envio
Para Patient e Practitioner, os system aceitos são configurados por unidade de cuidado, e
a lista é ordenada: quando o payload traz vários identificadores, a Nilo tenta encontrar o registro
na ordem em que os namespaces foram configurados. Um payload que só traz system fora dessa lista
é recusado, em vez de criar um registro duplicado — veja
Paciente.
Nos demais recursos não há lista: qualquer system presente no recurso é aceito como chave de
upsert.
Consequência prática: no Patient você não escolhe livremente o seu system — ele precisa estar
habilitado para a sua unidade antes da primeira carga. Se não souber quais estão habilitados, fale
com o time antes de montar a integração.
Referenciar outro recurso por identificador
Um recurso aponta para outro pelo identificador, não pelo id da Nilo. Em vez de
reference: "Patient/...", mande identifier:
A resolução tem dois caminhos. Se o system for um NamingSystem da Nilo, o value já é a chave do
registro e a referência resolve direto. Se for um system seu, a Nilo busca o recurso apontado no
store por aquele identificador e lê o identificador Nilo de dentro dele.
O recurso referenciado precisa já existir. Uma referência que não resolve recusa a escrita
inteira — ela nunca cria o alvo por conta própria. Identificador sem system ou sem value
também é recusado, com 400 apontando identifier.system ou identifier.value.
Buscar por identificador
O parâmetro identifier recebe as duas metades separadas por barra vertical, e vale para qualquer
recurso que tenha busca:
O system entra cru, com as suas próprias barras — não precisa escapar nada. O que precisa é
colocar a URL entre aspas, porque a barra vertical é um pipe para o shell.
A resposta é um Bundle do tipo searchset, como em qualquer busca: nenhum resultado é 200 com
Bundle vazio, não 404.
Boas práticas
- Mantenha o
systemestável. Trocar osystemde um registro já integrado faz a Nilo tratá-lo como um registro novo, e o histórico fica partido em dois. Não há como juntá-los depois pela API. - Garanta a unicidade do
valuedentro de cadasystem. Dois registros seus com o mesmo par fazem o upsert acertar o registro errado — silenciosamente, porque para a API é o mesmo recurso. - Prefira namespaces oficiais quando existirem. O CPF, por exemplo, tem tratamento próprio sob
https://servicos.receita.fazenda.gov.br/servicos/cpf/, e usá-lo permite que a Nilo correlacione o paciente com dados vindos de outra origem. - Documente os seus namespaces. Registre a URI de cada
systemque você usa e o formato dovalue— é essa lista que precisa ser habilitada na sua unidade de cuidado, e é ela que alguém vai consultar quando um upsert cair no lugar errado.