Pular para o conteúdo principal

Cadastrar/Atualizar

EndpointPOST /fhir/resources/Flag
Autenticação🔓 Chave de API
StatusImplementado
Comportamento
  • O campo identifier é obrigatório e é a chave de upsert: um identifier já existente atualiza a tag do paciente, um novo cria.
  • code, status e subject são obrigatórios. O code deve referenciar uma etiqueta existente e o subject, um paciente existente.
  • category é opcional e serve apenas como validação — precisa ser a categoria da etiqueta informada em code.
  • status precisa ser coerente com period. Para encerrar uma tag, envie status: "inactive" (ver Vigência).
  • encounter e author são aceitos por conformidade FHIR, mas não são armazenados no NiloCare.

Consultando as etiquetas disponíveis​

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

As etiquetas (flag-code) e suas categorias (flag-category) devem ser cadastradas no NiloCare, em Configurações > Etiquetas (menu do usuário, no canto superior direito). A integração apenas associa a um paciente uma etiqueta que já existe — enviar um code que não corresponda a uma etiqueta cadastrada resulta no erro Etiqueta inexistente.

Antes de cadastrar uma tag é necessário saber qual code utilizar. As etiquetas disponíveis são publicadas como um CodeSystem, consultado pela sua URL canônica https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code:

Etiquetas disponíveis (flag-code)
curl --request GET \
--url https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?url=https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code \
--header 'Content-Type: application/json' \
--header 'x-api-key: <inserir API Key aqui>'

Cada item de concept traz o code (o valor a ser enviado em Flag.code.coding.code) e o display (o nome da etiqueta no NiloCare):

{
"resourceType": "CodeSystem",
"url": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
"status": "active",
"content": "complete",
"publisher": "Nilo Saude",
"count": 2,
"concept": [
  { "code": "79", "display": "Escala de risco alto" },
  { "code": "80", "display": "Paciente prioritário" }
]
}

As categorias seguem o mesmo modelo, no CodeSystem https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category:

Categorias disponíveis (flag-category)
curl --request GET \
--url https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?url=https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category \
--header 'Content-Type: application/json' \
--header 'x-api-key: <inserir API Key aqui>'
Observação

Apenas as etiquetas e categorias vigentes no NiloCare são publicadas nesses CodeSystem.

Modelagem da API - Request​

OpçãoTipoRequeridoDescriçãoExemplo
x-api-keystringSimChave de autenticação do cliente, fornecida durante a configuração do ambiente.
Content-TypestringSimapplication/json


Exemplo de requisição CURL

curl --request POST \
  --url https://landing-zone-api.nilo.services/fhir/resources/Flag \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <inserir API Key aqui>' \
  --data '
{
  "resourceType": "Flag",
  "identifier": [
      {
          "system": "http://sistemaorigem.cliente.com/flag",
          "value": "12345"
      }
  ],
  "status": "active",
  "code": {
      "coding": [
          {
              "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
              "code": "79"
          }
      ]
  },
  "subject": {
      "identifier": {
          "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
          "use": "official",
          "value": "12345678900"
      },
      "type": "Patient"
  }
}'


Observação
  • O system http://sistemaorigem.cliente.com/flag e o valor 12345 são fictícios — utilize o identificador do sistema de origem do cliente.
  • O código 79 é fictício. Os valores válidos devem ser obtidos em Consultando as etiquetas disponíveis.
  • O CPF 12345678900 é fictício. Um valor real deve ser utilizado.

Modelagem da API - Response​

Operação bem sucedida.
Array of objects (CodeableConcept)

Categoria da etiqueta. Opcional — serve apenas como validação e precisa ser a categoria da etiqueta informada em code. Envie no máximo uma categoria, com o system .../CodeSystem/flag-category.

required
object

Etiqueta associada ao paciente. O code deve referenciar uma etiqueta já cadastrada no NiloCare, publicada no CodeSystem .../CodeSystem/flag-code.

object

Autor da etiqueta. Aceito por conformidade com o FHIR e preservado no recurso, mas não é armazenado no NiloCare — o NiloCare nunca preenche este campo.

object

Atendimento no qual a etiqueta foi criada. Aceito por conformidade com o FHIR e preservado no recurso, mas não é armazenado no NiloCare — o NiloCare nunca preenche este campo.

id
string (id) ^[A-Za-z0-9\-\.]{{1,64}}$

Qualquer combinação de letras, números, "-" e ".", com um limite de 64 caracteres. (Pode ser um número inteiro, um OID não prefixado, UUID ou qualquer outro padrão de identificador que atenda a essas restrições.) Os IDs não diferenciam maiúsculas de minúsculas.

required
Array of objects (Identifier) non-empty

Identificador(es) pelo qual este recurso é distinguido. É a chave de upsert — um identifier já existente atualiza a tag do paciente, um novo cria.

object (Meta)

Os metadados sobre um recurso. Este conteúdo do recurso é normalmente mantido pelo sistema gestor do registro.

object

Vigência da etiqueta. Precisa ser coerente com o status. Se omitido em uma tag active, o NiloCare define a vigência.

resourceType
required
any
Value: "Flag"
status
required
any
Enum: "active" "inactive" "entered-in-error"

Situação da etiqueta, derivada da vigência (period). Para encerrar uma tag, envie inactive.

required
object

Paciente ao qual a etiqueta está associada. O paciente precisa existir previamente no NiloCare. Quando type não é informado, assume-se Patient.

{}

Possíveis Erros​

identifier ausente​

O identifier é a chave de upsert. Um payload sem identifier é rejeitado para evitar duplicidade de tags.

{
  "issue": [
    {
      "code": "required",
      "details": {
        "text": "Field is required"
      },
      "expression": [
        "Flag.identifier"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

Etiqueta inexistente​

O code informado não corresponde a nenhuma etiqueta cadastrada no NiloCare.

{
  "issue": [
    {
      "code": "code-invalid",
      "details": {
        "text": "Tag not found"
      },
      "expression": [
        "Flag.code.coding.code"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

Paciente inexistente​

O subject não resolve para nenhum paciente do NiloCare. Cadastre o paciente antes de associar a tag.

{
  "issue": [
    {
      "code": "not-found",
      "details": {
        "text": "Patient does not exist"
      },
      "expression": [
        "Flag.subject"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

Categoria inexistente​

A category enviada não corresponde a nenhuma categoria cadastrada no NiloCare.

{
  "issue": [
    {
      "code": "code-invalid",
      "details": {
        "text": "Category not found"
      },
      "expression": [
        "Flag.category.coding.code"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

Categoria não corresponde à etiqueta​

A category existe, mas não é a categoria da etiqueta informada em code. Como a categoria é inferida do code, o mais simples é omitir category.

{
  "issue": [
    {
      "code": "invariant",
      "details": {
        "text": "Tag does not belong to the category"
      },
      "expression": [
        "Flag.category.coding.code"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

Múltiplas categorias​

Foi enviada mais de uma category com códigos diferentes. Envie no máximo uma categoria.

{
"issue": [
  {
    "code": "multiple-matches",
    "details": {
      "text": "Multiple matches to system https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category"
    },
    "expression": [
      "Flag.category.coding"
    ],
    "severity": "error"
  }
],
"resourceType": "OperationOutcome"
}

status incoerente com period​

Ocorre quando status: "active" é enviado com um period que não está vigente (já encerrado ou com início no futuro), ou quando status: "inactive" é enviado com um period vigente.

{
  "issue": [
    {
      "code": "invariant",
      "details": {
        "text": "Status does not match the period"
      },
      "expression": [
        "Flag.status"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

Exemplo de payload que gera o erro​

{
"resourceType": "Flag",
"identifier": [
  {
    "system": "http://sistemaorigem.cliente.com/flag",
    "value": "12345"
  }
],
"status": "active",
"code": {
  "coding": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
      "code": "79"
    }
  ]
},
"subject": {
  "identifier": {
    "system": "https://servicos.receita.fazenda.gov.br/servicos/cpf/",
    "use": "official",
    "value": "12345678900"
  },
  "type": "Patient"
},
"period": {
  "start": "2020-01-01T00:00:00+00:00",
  "end": "2020-02-01T00:00:00+00:00"
}
}
Observação

O code 79 e o CPF 12345678900 são fictícios. Para reproduzir este erro especificamente, use uma etiqueta e um paciente que existam no ambiente — caso contrário a API rejeita antes, com Tag not found ou Patient does not exist.

Criação de tag inativa sem period​

Uma tag nova não pode ser criada como inactive sem uma vigência explícita. Em tags já existentes, status: "inactive" sem period encerra a vigência no momento da requisição.

{
  "issue": [
    {
      "code": "business-rule",
      "details": {
        "text": "Period is required to create inactive flags"
      },
      "expression": [
        "Flag.period"
      ],
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}