> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://api-docs.nilo.services/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.nilo.services/_mcp/server. # Identificadores > O que a API lê de um identificador, quais ela devolve e como referenciar e buscar recursos por identificador. 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](/guia/comecando/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 | Campo | O que é | Como a API usa | | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `system` | A URI do namespace — quem emitiu o identificador | Obrigatório. É a primeira metade da chave, e é o que a Nilo compara para decidir se aquele identificador é utilizável | | `value` | A chave do registro dentro daquele namespace | Obrigatório. É a segunda metade da chave | | `use` | A finalidade do identificador (`official`, `usual`, `temp`, `secondary`, `old`) | Lido em pontos específicos, não de forma geral — veja a nota abaixo | | `period` | A vigência do identificador | Aceito e devolvido, **sem efeito**. Nenhum recurso desta API lê a vigência de um identificador | > **Note** > > 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](/guia/recursos/patient). 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: ``` {host}/fhir/resources/NamingSystem/{api}--{recurso} ``` Onde `{api}` é o microsserviço Nilo que é dono do registro e `{recurso}` é o modelo, em kebab-case. Por exemplo, o id interno do paciente: ``` https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient ``` 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](/guia/recursos/patient). > **Warning** > > 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](/guia/comecando/introducao). ## 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](/guia/recursos/patient). Nos demais recursos não há lista: qualquer `system` presente no recurso é aceito como chave de upsert. > **Note** > > 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`: ```json { "resourceType": "Condition", "identifier": [ { "system": "https://www.acmesaude.com.br/integracao/condicao/", "value": "CON-0001" } ], "subject": { "type": "Patient", "identifier": { "system": "https://www.acmesaude.com.br/integracao/paciente/", "value": "507823709" } } } ``` 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. > **Warning** > > 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: ```bash curl --request GET \ --url 'https://landing-zone-api.nilo.services/fhir/resources/Condition?identifier=https://www.acmesaude.com.br/integracao/condicao/|CON-0001' \ --header 'x-api-key: SUA_API_KEY' ``` 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 `system` estável.** Trocar o `system` de 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 `value` dentro de cada `system`.** 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 `system` que você usa e o formato do `value` — é 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.