Tags

Contexto NiloCare

---

Esse endpoint permite aos clientes Nilo Saúde ler e adicionar novas tags (etiquetas) aos pacientes.

---

---

Mapeamento de Campos

Recurso FHIR: Flag

#	Campo		Expressão de caminho no objeto FHIR
1	Identificador		identifier
2	Status		status
3	Código (etiqueta)		code.coding.where(system='https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code').first()
4	Paciente		subject.reference
5	Categoria		category.coding.where(system='https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category').first()
6	Início de vigência		period.start
7	Fim de vigência		period.end

dica

Na escrita, os campos obrigatórios são: identifier, code, status e subject¹. A category é opcional — quando enviada, é apenas validada contra a etiqueta informada em code (ver Categoria). Os campos encounter e author são aceitos por conformidade com o FHIR, mas não são armazenados no NiloCare.

Especificações de comportamento FHIR - NiloCare

---

Identificação e upsert

O campo identifier é obrigatório e é usado como chave de deduplicação: se já existir uma tag de paciente com um dos identifier informados, a requisição é tratada como atualização; caso contrário, uma nova tag é criada. Enviar um payload sem identifier resulta em erro.

Qualquer system de identificador é aceito — use o do sistema de origem do cliente (ex.: http://sistemaorigem.cliente.com/flag). Quando mais de um identifier é enviado, eles são testados na ordem em que aparecem no payload.

Na resposta, o sistema adiciona automaticamente um identifier do próprio NiloCare (system https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-tag, cujo value é o identificador interno da tag do paciente). Esse identifier pode ser usado para consultar ou atualizar o recurso posteriormente. O identifier do cliente é preservado nas sincronizações seguintes.

Código da etiqueta (code)

Obrigatório. O coding precisa usar o system https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code e o code deve ser o identificador de uma etiqueta existente no NiloCare. Os valores válidos são publicados como um CodeSystem — veja Consultando as etiquetas disponíveis.

Etiquetas não são criadas por integração

As etiquetas e suas categorias devem ser cadastradas no NiloCare, em Configurações > Etiquetas (menu do usuário, no canto superior direito). Toda etiqueta pertence a uma categoria, então a categoria precisa ser criada primeiro.

A integração apenas associa a um paciente uma etiqueta que já existe; ela não cria novas etiquetas nem novas categorias.

{
"code": {
  "coding": [
    {
      "code": "79",
      "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code"
    }
  ]
}
}

Paciente (subject)

Obrigatório. Deve referenciar um paciente já existente no NiloCare, por identifier — o CPF é a forma mais comum, mas qualquer identificador válido do paciente é aceito. Quando subject.type é omitido, o sistema assume Patient.

{
  "subject": {
    "identifier": {
      "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
      "use": "official",
      "value": "12345678900"
    },
    "type": "Patient"
  }
}

Categoria

A categoria não é obrigatória, porque ela é inferida a partir do code. Quando enviada, é usada apenas como validação: a categoria precisa existir e ser exatamente a categoria à qual a etiqueta pertence — caso contrário a requisição é rejeitada. Não é permitido enviar mais de uma categoria com códigos diferentes.

{
"category": [
  {
    "coding": [
      {
        "code": "1",
        "display": "Escala de risco!",
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category"
      }
    ],
    "text": "Escala de risco!"
  }
]
}

Os valores válidos são publicados no CodeSystem https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category — veja Consultando as etiquetas disponíveis.

Vigência (status e period)

O status é active ou inactive e precisa ser coerente com a vigência informada em period. Considera-se a tag vigente quando period.start já ocorreu (ou está ausente) e period.end ainda não ocorreu (ou está ausente).

status	period	Comportamento
active	ausente	A vigência é definida pelo NiloCare (início imediato, sem fim)
active	vigente	A vigência informada é usada
active	não vigente	❌ Erro Status does not match the period
inactive	ausente, tag nova	❌ Erro Period is required to create inactive flags
inactive	ausente, tag existente	A tag é encerrada agora (period.end = momento da requisição)
inactive	não vigente	A vigência informada é usada
inactive	vigente	❌ Erro Status does not match the period

O NiloCare produz apenas active e inactive. O terceiro valor do enum do FHIR, entered-in-error, é aceito na escrita por conformidade, mas é tratado exatamente como inactive — inclusive na validação de coerência com period — e nunca é devolvido em tags sincronizadas a partir do NiloCare.

{
  "period": {
    "start": "2025-02-03T17:24:36.817645+00:00",
    "end": "2025-02-03T17:25:22.756947+00:00"
  }
}

Observação

Não há operação de exclusão: para remover uma tag de um paciente, envie status: "inactive" (encerrando a vigência).

Os cenários de erro correspondentes estão documentados em Cadastrar/Atualizar.

Sincronização a partir do NiloCare

Tags criadas, atualizadas ou removidas diretamente no NiloCare são sincronizadas automaticamente para o FHIR store, e ficam disponíveis na Consulta. Nesse caso o recurso terá apenas o identifier do NiloCare.

Footnotes

1. Confira o payload na aba "Cadastrar/Atualizar". ↩