> 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.

# Etiqueta

> Aplicar e consultar etiquetas nos pacientes, no padrão FHIR Flag.

Uma **etiqueta** é um marcador que a equipe pendura num paciente para sinalizar alguma coisa
sobre ele — *Gestante*, *Alto risco*, *Prioridade no atendimento*. Ela tem vigência: começa
num dia e pode terminar noutro.

No FHIR o recurso é a [`Flag`](https://hl7.org/fhir/R4/flag.html), e esta integração o usa nas
duas pontas: aplicar uma etiqueta a um paciente e consultar as que ele tem.

> **Warning**
>
> **A etiqueta em si não é criada por aqui.** O que você aplica é uma etiqueta que já existe no
> catálogo do seu ambiente, e o catálogo é montado pela equipe em *Configurações › Etiquetas* —
> onde a **categoria precisa ser criada antes** da etiqueta. Para descobrir quais etiquetas
> existem, e os códigos delas, leia o
> [catálogo de códigos](/guia/recursos/codesystem).

## Campos

| Campo                         | Obrigatório | O que significa                                                                                                      | No Nilo Care  |
| ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ------------- |
| `resourceType`                | **sim**     | Constante `Flag`                                                                                                     | —             |
| `identifier`                  | **sim**     | Suas chaves da etiqueta aplicada. É por elas que a API decide entre criar e atualizar                                | —             |
| `status`                      | **sim**     | `active` ou `inactive`, **e tem de concordar com o `period`**. `entered-in-error` é aceito e tratado como `inactive` | —             |
| `code.coding[]`               | **sim**     | A etiqueta, por um código do catálogo                                                                                | **Etiqueta**  |
| `subject.identifier`          | **sim**     | O paciente                                                                                                           | —             |
| `category[].coding[]`         | não         | A categoria da etiqueta. Enviada, é **conferida**                                                                    | **Categoria** |
| `period.start` · `period.end` | não         | A vigência da etiqueta                                                                                               | —             |
| `id` · `meta`                 | não         | Só resposta: identificador Nilo FHIR e metadados da gravação                                                         | —             |

> **Note**
>
> `code.text`, `code.coding[].display`, `category` e os `display` dela vêm **do catálogo** na
> leitura. Enviá-los não tem efeito: quem identifica a etiqueta é o par `system` + `code`.
>
> E `category` vem **sempre** na leitura, mesmo que você não a tenha enviado — ela é derivada da
> etiqueta.

### `status` e `period` têm de concordar

Esta é a regra que mais recusa chamadas neste recurso. A API confere se o `status` que você
mandou bate com o `period`:

| O que você manda                                          | Resultado                                                    |
| --------------------------------------------------------- | ------------------------------------------------------------ |
| `active`, sem `period`                                    | A plataforma decide a vigência — começa agora                |
| `active`, com `period` já começado e não terminado        | Aceito                                                       |
| `active`, com `period` futuro ou já terminado             | **Recusado** (`Status does not match the period`)            |
| `inactive`, com `period` futuro ou já terminado           | Aceito                                                       |
| `inactive`, com `period` vigente                          | **Recusado**                                                 |
| `inactive`, sem `period`, numa etiqueta **que já existe** | A etiqueta é **encerrada agora**                             |
| `inactive`, sem `period`, numa etiqueta **nova**          | **Recusado** (`Period is required to create inactive flags`) |

> **Warning**
>
> **`status` não é um campo livre: é uma afirmação sobre o `period`, e ela é verificada.** Mandar
> `active` numa etiqueta com vigência futura não a agenda — recusa a chamada.

> **Warning**
>
> **E o `status` gravado não muda sozinho.** Ele é calculado no momento da **gravação**, não da
> leitura: uma etiqueta gravada como `inactive` com vigência futura continua sendo devolvida como
> `inactive` depois de a data chegar, até que alguma coisa altere a etiqueta na plataforma.
>
> Não conte com a virada automática. Se você agenda etiquetas, reenvie o recurso com
> `status: active` quando a vigência começar — ou compare o `period` com a data de hoje do seu
> lado.

> **Note**
>
> `status` é derivado do período, não um estado à parte: não existe uma etiqueta "desativada mas
> dentro da vigência".

### Encerrar uma etiqueta

Reenviar o mesmo `identifier` com `status: inactive` e **sem** `period` encerra a etiqueta no
instante da chamada.

### Request

POST [https://landing-zone-api.nilo.services/fhir/resources/Flag](https://landing-zone-api.nilo.services/fhir/resources/Flag)

**`Encerrar uma etiqueta`**

```curl Encerrar uma etiqueta
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Flag \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    }
  ],
  "status": "inactive",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  }
}'
```

**`Encerrar uma etiqueta`**

```python Encerrar uma etiqueta
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/Flag"

payload = {
    "resourceType": "Flag",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
            "value": "ET-7001",
            "use": "usual"
        }
    ],
    "status": "inactive",
    "code": { "coding": [
            {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
                "code": "318"
            }
        ] },
    "subject": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Encerrar uma etiqueta`**

```javascript Encerrar uma etiqueta
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Flag';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Flag","identifier":[{"system":"https://www.acmesaude.com.br/integracao/etiqueta/","value":"ET-7001","use":"usual"}],"status":"inactive","code":{"coding":[{"system":"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code","code":"318"}]},"subject":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Encerrar uma etiqueta`**

```go Encerrar uma etiqueta
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Flag"

	payload := strings.NewReader("{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"inactive\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Encerrar uma etiqueta`**

```ruby Encerrar uma etiqueta
require 'uri'
require 'net/http'

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Flag")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"inactive\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

**`Encerrar uma etiqueta`**

```java Encerrar uma etiqueta
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://landing-zone-api.nilo.services/fhir/resources/Flag")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"inactive\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}")
  .asString();
```

**`Encerrar uma etiqueta`**

```php Encerrar uma etiqueta
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Flag', [
  'body' => '{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    }
  ],
  "status": "inactive",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`Encerrar uma etiqueta`**

```csharp Encerrar uma etiqueta
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Flag");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"inactive\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Encerrar uma etiqueta`**

```swift Encerrar uma etiqueta
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Flag",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    ]
  ],
  "status": "inactive",
  "code": ["coding": [
      [
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      ]
    ]],
  "subject": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Flag")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> **Note**
>
> Não há remoção por integração: este endpoint nunca responde `204`. Encerrar é a forma de tirar
> uma etiqueta do paciente, e o registro continua existindo com a vigência fechada.

### Campos que a Nilo não usa

A `Flag` canônica traz mais do que esta integração lê: `encounter`, `author` e `text`. Nenhum
deles é lido — em particular, **não há como registrar quem aplicou a etiqueta** nem a que
atendimento ela se refere.

> **Note**
>
> A referência lista só os campos **suportados**, não os permitidos: a API em si não recusa quem
> manda os outros — eles ficam guardados no recurso e voltam nas leituras seguintes, sem nunca
> terem significado nada para a plataforma. Se o seu validador for estrito contra a referência,
> uma resposta assim vai parecer inválida; o remédio é não enviá-los.

## Aplicar uma etiqueta

### Request

POST [https://landing-zone-api.nilo.services/fhir/resources/Flag](https://landing-zone-api.nilo.services/fhir/resources/Flag)

**`Aplicar uma etiqueta`**

```curl Aplicar uma etiqueta
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Flag \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    }
  ],
  "status": "active",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  }
}'
```

**`Aplicar uma etiqueta`**

```python Aplicar uma etiqueta
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/Flag"

payload = {
    "resourceType": "Flag",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
            "value": "ET-7001",
            "use": "usual"
        }
    ],
    "status": "active",
    "code": { "coding": [
            {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
                "code": "318"
            }
        ] },
    "subject": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Aplicar uma etiqueta`**

```javascript Aplicar uma etiqueta
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Flag';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Flag","identifier":[{"system":"https://www.acmesaude.com.br/integracao/etiqueta/","value":"ET-7001","use":"usual"}],"status":"active","code":{"coding":[{"system":"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code","code":"318"}]},"subject":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Aplicar uma etiqueta`**

```go Aplicar uma etiqueta
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Flag"

	payload := strings.NewReader("{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Aplicar uma etiqueta`**

```ruby Aplicar uma etiqueta
require 'uri'
require 'net/http'

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Flag")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

**`Aplicar uma etiqueta`**

```java Aplicar uma etiqueta
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://landing-zone-api.nilo.services/fhir/resources/Flag")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}")
  .asString();
```

**`Aplicar uma etiqueta`**

```php Aplicar uma etiqueta
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Flag', [
  'body' => '{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    }
  ],
  "status": "active",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`Aplicar uma etiqueta`**

```csharp Aplicar uma etiqueta
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Flag");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7001\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Aplicar uma etiqueta`**

```swift Aplicar uma etiqueta
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Flag",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    ]
  ],
  "status": "active",
  "code": ["coding": [
      [
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      ]
    ]],
  "subject": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Flag")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

A resposta é o recurso gravado, sem envelope:

### Response (200)

```json
{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-tag",
      "value": "55210",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    }
  ],
  "status": "active",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318",
        "display": "Gestante"
      }
    ],
    "text": "Gestante"
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4",
    "type": "Patient"
  },
  "id": "4c7a0d31-98e6-42b5-b17f-3e05a92c8674",
  "meta": {
    "lastUpdated": "2026-05-04T10:15:33.902000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "category": [
    {
      "coding": [
        {
          "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
          "code": "12",
          "display": "Condições de saúde"
        }
      ],
      "text": "Condições de saúde"
    }
  ],
  "period": {
    "start": "2026-05-04T10:15:33+00:00"
  }
}
```

Guarde o `id`: é por ele que se faz a leitura direta. Ao lado do seu `identifier`, a resposta
traz o identificador Nilo da etiqueta aplicada, no `system`
`…/NamingSystem/hippocrates-api--patient-tag`.

> **Note**
>
> Mandando mais de um `identifier`, eles são testados **na ordem em que aparecem no payload**, e o
> primeiro que casar com uma etiqueta existente vence.

### Request

POST [https://landing-zone-api.nilo.services/fhir/resources/Flag](https://landing-zone-api.nilo.services/fhir/resources/Flag)

**`Aplicar com vigência definida`**

```curl Aplicar com vigência definida
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Flag \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7002",
      "use": "usual"
    }
  ],
  "status": "active",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "category": [
    {
      "coding": [
        {
          "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
          "code": "12"
        }
      ]
    }
  ],
  "period": {
    "start": "2026-05-04T00:00:00+00:00"
  }
}'
```

**`Aplicar com vigência definida`**

```python Aplicar com vigência definida
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/Flag"

payload = {
    "resourceType": "Flag",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
            "value": "ET-7002",
            "use": "usual"
        }
    ],
    "status": "active",
    "code": { "coding": [
            {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
                "code": "318"
            }
        ] },
    "subject": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    },
    "category": [{ "coding": [
                {
                    "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
                    "code": "12"
                }
            ] }],
    "period": { "start": "2026-05-04T00:00:00+00:00" }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Aplicar com vigência definida`**

```javascript Aplicar com vigência definida
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Flag';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Flag","identifier":[{"system":"https://www.acmesaude.com.br/integracao/etiqueta/","value":"ET-7002","use":"usual"}],"status":"active","code":{"coding":[{"system":"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code","code":"318"}]},"subject":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"},"category":[{"coding":[{"system":"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category","code":"12"}]}],"period":{"start":"2026-05-04T00:00:00+00:00"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Aplicar com vigência definida`**

```go Aplicar com vigência definida
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Flag"

	payload := strings.NewReader("{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7002\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"category\": [\n    {\n      \"coding\": [\n        {\n          \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category\",\n          \"code\": \"12\"\n        }\n      ]\n    }\n  ],\n  \"period\": {\n    \"start\": \"2026-05-04T00:00:00+00:00\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Aplicar com vigência definida`**

```ruby Aplicar com vigência definida
require 'uri'
require 'net/http'

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Flag")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7002\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"category\": [\n    {\n      \"coding\": [\n        {\n          \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category\",\n          \"code\": \"12\"\n        }\n      ]\n    }\n  ],\n  \"period\": {\n    \"start\": \"2026-05-04T00:00:00+00:00\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

**`Aplicar com vigência definida`**

```java Aplicar com vigência definida
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://landing-zone-api.nilo.services/fhir/resources/Flag")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7002\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"category\": [\n    {\n      \"coding\": [\n        {\n          \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category\",\n          \"code\": \"12\"\n        }\n      ]\n    }\n  ],\n  \"period\": {\n    \"start\": \"2026-05-04T00:00:00+00:00\"\n  }\n}")
  .asString();
```

**`Aplicar com vigência definida`**

```php Aplicar com vigência definida
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Flag', [
  'body' => '{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7002",
      "use": "usual"
    }
  ],
  "status": "active",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      }
    ]
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "category": [
    {
      "coding": [
        {
          "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
          "code": "12"
        }
      ]
    }
  ],
  "period": {
    "start": "2026-05-04T00:00:00+00:00"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`Aplicar com vigência definida`**

```csharp Aplicar com vigência definida
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Flag");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Flag\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/etiqueta/\",\n      \"value\": \"ET-7002\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"status\": \"active\",\n  \"code\": {\n    \"coding\": [\n      {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code\",\n        \"code\": \"318\"\n      }\n    ]\n  },\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"category\": [\n    {\n      \"coding\": [\n        {\n          \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category\",\n          \"code\": \"12\"\n        }\n      ]\n    }\n  ],\n  \"period\": {\n    \"start\": \"2026-05-04T00:00:00+00:00\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Aplicar com vigência definida`**

```swift Aplicar com vigência definida
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Flag",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7002",
      "use": "usual"
    ]
  ],
  "status": "active",
  "code": ["coding": [
      [
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318"
      ]
    ]],
  "subject": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ],
  "category": [["coding": [
        [
          "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
          "code": "12"
        ]
      ]]],
  "period": ["start": "2026-05-04T00:00:00+00:00"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Flag")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### O código da etiqueta

O código vai num `coding` cujo `system` é `{host}/fhir/resources/CodeSystem/flag-code`, com o
host do seu ambiente:

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

> **Warning**
>
> Um `coding` em qualquer outro `system` é **ignorado**, e não sobrando nenhum no `system` certo a
> chamada é recusada com `Invalid system …`. Confira a URL — o `system` é o mesmo valor que o
> `url` do [catálogo](/guia/recursos/codesystem).

> **Warning**
>
> O código precisa existir no catálogo do **seu** ambiente. Um código válido em homologação pode
> não existir em produção: os catálogos são independentes.

### A categoria

`category` é opcional — e, quando você a manda, ela **não classifica nada**: é conferida contra
a categoria à qual a etiqueta já pertence.

> **Warning**
>
> Mandar uma categoria que não é a da etiqueta **recusa a chamada**
> (`Tag does not belong to the category`). Se você não tem certeza, **omita** — a leitura vai
> trazer a categoria certa de qualquer forma.

## Buscar

### Request

GET [https://landing-zone-api.nilo.services/fhir/resources/Flag](https://landing-zone-api.nilo.services/fhir/resources/Flag)

**`Busca com resultados`**

```curl Busca com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/Flag \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     -d date=ge2026-01-01 \
     --data-urlencode identifier=https://www.acmesaude.com.br/integracao/etiqueta/|ET-7001 \
     --data-urlencode patient=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4 \
     --data-urlencode patient:identifier=https://www.acmesaude.com.br/integracao/paciente/|507823709 \
     --data-urlencode subject=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4
```

**`Busca com resultados`**

```python Busca com resultados
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/Flag"

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","date":"ge2026-01-01","identifier":"https://www.acmesaude.com.br/integracao/etiqueta/|ET-7001","patient":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4","patient:identifier":"https://www.acmesaude.com.br/integracao/paciente/|507823709","subject":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"}

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

**`Busca com resultados`**

```javascript Busca com resultados
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Flag?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=ge2026-01-01&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fetiqueta%2F%7CET-7001&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Busca com resultados`**

```go Busca com resultados
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Flag?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=ge2026-01-01&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fetiqueta%2F%7CET-7001&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Busca com resultados`**

```ruby Busca com resultados
require 'uri'
require 'net/http'

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Flag?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=ge2026-01-01&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fetiqueta%2F%7CET-7001&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

**`Busca com resultados`**

```java Busca com resultados
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://landing-zone-api.nilo.services/fhir/resources/Flag?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=ge2026-01-01&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fetiqueta%2F%7CET-7001&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Busca com resultados`**

```php Busca com resultados
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://landing-zone-api.nilo.services/fhir/resources/Flag?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=ge2026-01-01&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fetiqueta%2F%7CET-7001&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`Busca com resultados`**

```csharp Busca com resultados
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Flag?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=ge2026-01-01&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fetiqueta%2F%7CET-7001&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

**`Busca com resultados`**

```swift Busca com resultados
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Flag?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=ge2026-01-01&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fetiqueta%2F%7CET-7001&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

A resposta é sempre um `Bundle` do tipo `searchset`:

### Response (200)

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Flag/4c7a0d31-98e6-42b5-b17f-3e05a92c8674",
      "resource": {
        "resourceType": "Flag",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-tag",
            "value": "55210",
            "use": "usual"
          },
          {
            "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
            "value": "ET-7001",
            "use": "usual"
          }
        ],
        "status": "active",
        "code": {
          "coding": [
            {
              "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
              "code": "318",
              "display": "Gestante"
            }
          ],
          "text": "Gestante"
        },
        "subject": {
          "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
          },
          "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4",
          "type": "Patient"
        },
        "id": "4c7a0d31-98e6-42b5-b17f-3e05a92c8674",
        "meta": {
          "lastUpdated": "2026-05-04T10:15:33.902000Z",
          "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
        },
        "category": [
          {
            "coding": [
              {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
                "code": "12",
                "display": "Condições de saúde"
              }
            ],
            "text": "Condições de saúde"
          }
        ],
        "period": {
          "start": "2026-05-04T00:00:00+00:00"
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

Busca sem resultados não é erro: volta `200` com um `Bundle` cujo `entry` é uma lista vazia.

### Response (200)

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [],
  "link": []
}
```

### Parâmetros de busca suportados

| Nome                                        | Tipo                                                       | Descrição                                                          | Expressão                 |
| ------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
| `identifier`                                | [token](https://hl7.org/fhir/R4/search.html#token)         | Identificador da etiqueta aplicada, em `system\|value`             | `Flag.identifier`         |
| `patient` · `subject`                       | [reference](https://hl7.org/fhir/R4/search.html#reference) | Paciente, pelo `id` Nilo FHIR dele                                 | `Flag.subject`            |
| `patient:identifier` · `subject:identifier` | [reference](https://hl7.org/fhir/R4/search.html#reference) | Paciente, pelo identificador dele                                  | `Flag.subject.identifier` |
| `date`                                      | [date](https://hl7.org/fhir/R4/search.html#date)           | Vigência da etiqueta, com os prefixos `eq`, `ge`, `le`             | `Flag.period`             |
| `_lastUpdated`                              | [date](https://hl7.org/fhir/R4/search.html#date)           | Data da última gravação no store, com os prefixos `eq`, `ge`, `le` | —                         |

> **Warning**
>
> **`status`, `code` e `category` são preenchidos no recurso e não são filtráveis.** O `Flag` do
> FHIR R4 não define parâmetro de busca para nenhum dos três — não há como pedir "as etiquetas
> ativas" nem "os pacientes com a etiqueta 318".
>
> Para isso, busque por paciente ou por `date` e filtre do seu lado.

> **Note**
>
> `author` e `encounter` são parâmetros canônicos que **funcionam** — mas só encontram as
> etiquetas em que **você** enviou o campo, já que a plataforma nunca o preenche.

A paginação é por `_count` e `_page_token`; havendo página seguinte, o `Bundle` traz a URL
pronta em `link`.

> **Note**
>
> A busca devolve também as etiquetas aplicadas pela **equipe dentro do Nilo Care**. Essas trazem
> apenas o identificador Nilo — não haverá um `identifier` seu. É por essa diferença que você
> separa umas das outras.

## Ler por ID

### Request

GET [https://landing-zone-api.nilo.services/fhir/resources/Flag/\{id}](https://landing-zone-api.nilo.services/fhir/resources/Flag/\{id})

**`Etiqueta encontrada`**

```curl Etiqueta encontrada
curl https://landing-zone-api.nilo.services/fhir/resources/Flag/id \
     -H "x-api-key: <apiKey>"
```

**`Etiqueta encontrada`**

```python Etiqueta encontrada
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/Flag/id"

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

**`Etiqueta encontrada`**

```javascript Etiqueta encontrada
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Flag/id';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Etiqueta encontrada`**

```go Etiqueta encontrada
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Flag/id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Etiqueta encontrada`**

```ruby Etiqueta encontrada
require 'uri'
require 'net/http'

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Flag/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

**`Etiqueta encontrada`**

```java Etiqueta encontrada
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://landing-zone-api.nilo.services/fhir/resources/Flag/id")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Etiqueta encontrada`**

```php Etiqueta encontrada
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://landing-zone-api.nilo.services/fhir/resources/Flag/id', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`Etiqueta encontrada`**

```csharp Etiqueta encontrada
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Flag/id");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

**`Etiqueta encontrada`**

```swift Etiqueta encontrada
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Flag/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> **Warning**
>
> Diferente da busca, esta leitura não devolve um `Bundle` — mas também **não devolve o recurso
> nu**. A resposta é um envelope com `fullUrl`, `search` e `resource`, e a etiqueta está em
> `resource`.

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Flag/4c7a0d31-98e6-42b5-b17f-3e05a92c8674",
  "resource": {
    "resourceType": "Flag",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-tag",
        "value": "55210",
        "use": "usual"
      }
    ],
    "status": "active",
    "code": {
      "coding": [
        {
          "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
          "code": "318",
          "display": "Gestante"
        }
      ],
      "text": "Gestante"
    },
    "subject": {
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/paciente/",
        "value": "507823709",
        "use": "usual"
      },
      "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4",
      "type": "Patient"
    },
    "id": "4c7a0d31-98e6-42b5-b17f-3e05a92c8674",
    "meta": {
      "lastUpdated": "2026-05-04T10:15:33.902000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "category": [
      {
        "coding": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
            "code": "12",
            "display": "Condições de saúde"
          }
        ],
        "text": "Condições de saúde"
      }
    ],
    "period": {
      "start": "2026-05-04T00:00:00+00:00"
    }
  },
  "search": {
    "mode": "match"
  }
}
```

## Efeitos colaterais

> **Note**
>
> Aplicar uma etiqueta **não notifica ninguém e não cria nada**. Ela aparece como um chip no
> cartão de cabeçalho do paciente, com o **ícone e a cor da categoria** — que é onde a categoria,
> que não classifica nada na escrita, acaba tendo efeito visível.

> **Warning**
>
> **Etiqueta encerrada no catálogo continua aplicada.** Se a equipe encerrar uma etiqueta nas
> configurações, ela some do [catálogo](/guia/recursos/codesystem) mas as aplicações
> existentes continuam sendo devolvidas na busca — com o `display` que tinham.
>
> Encerrar uma **categoria** encerra, junto, todas as etiquetas dela — e também não afeta as
> aplicações já feitas.

## Erros

Recusa é `400` — com uma exceção, o `409` da etiqueta repetida. O corpo é um
`OperationOutcome`: `issue[].expression` aponta o campo culpado e `issue[].details.text` explica
o motivo.

| `code`             | `expression`                | Mensagem                                                                                                     | Quando                                                                                                       |
| ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `required`         | `Flag.identifier`           | `Field is required`                                                                                          | O payload não tem `identifier`                                                                               |
| `business-rule`    | `Flag.identifier`           | `Unable to use any of the provided identifiers to match an existing resource, which can lead to duplicates.` | Há `identifier`, mas nenhum utilizável                                                                       |
| `not-found`        | `Flag.subject`              | `Patient does not exist`                                                                                     | O `subject` não resolve para um paciente do seu ambiente — **ou está ausente**, que sai com a mesma mensagem |
| `code-invalid`     | `Flag.code.coding.code`     | `Tag not found`                                                                                              | O código não existe no catálogo do ambiente                                                                  |
| `code-invalid`     | `Flag.category.coding.code` | `Category not found`                                                                                         | A categoria enviada não existe                                                                               |
| `invariant`        | `Flag.category.coding.code` | `Tag does not belong to the category`                                                                        | A categoria enviada não é a da etiqueta                                                                      |
| `multiple-matches` | `Flag.category.coding`      | `Multiple matches to system …`                                                                               | Mais de uma categoria, com códigos diferentes                                                                |
| `code-invalid`     | `Flag.code…coding.system`   | `Invalid system …`                                                                                           | Nenhum `coding` no `system` do catálogo                                                                      |
| `invariant`        | `Flag.status`               | `Status does not match the period`                                                                           | O `status` não bate com o `period`                                                                           |
| `business-rule`    | `Flag.period`               | `Period is required to create inactive flags`                                                                | Etiqueta nova, `inactive` e sem `period`                                                                     |
| `structure`        | —                           | `Resource has identifier from a Nilo environment that is not the current environment.`                       | O payload traz um identificador Nilo gerado em outro ambiente                                                |

E, fora do `400`:

| Status | `code`     | Mensagem                                             | Quando                                            |
| ------ | ---------- | ---------------------------------------------------- | ------------------------------------------------- |
| `409`  | `conflict` | `Resource conflicts with other existing resource(s)` | O paciente já tem essa mesma etiqueta em vigência |

> **Warning**
>
> **Um paciente não pode ter a mesma etiqueta aplicada duas vezes em vigência simultânea.** A
> segunda aplicação é recusada com `409`, **mesmo com um `identifier` diferente** — a plataforma
> compara o par paciente + etiqueta, não a sua chave. Encerre a primeira antes de aplicar de novo.

### Response (200)

```json
{
  "resourceType": "Flag",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-tag",
      "value": "55210",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/etiqueta/",
      "value": "ET-7001",
      "use": "usual"
    }
  ],
  "status": "active",
  "code": {
    "coding": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "code": "318",
        "display": "Gestante"
      }
    ],
    "text": "Gestante"
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4",
    "type": "Patient"
  },
  "id": "4c7a0d31-98e6-42b5-b17f-3e05a92c8674",
  "meta": {
    "lastUpdated": "2026-05-04T10:15:33.902000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "category": [
    {
      "coding": [
        {
          "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
          "code": "12",
          "display": "Condições de saúde"
        }
      ],
      "text": "Condições de saúde"
    }
  ],
  "period": {
    "start": "2026-05-04T10:15:33+00:00"
  }
}
```

Os payloads completos estão na aba **Referência**, em `POST /fhir/resources/Flag`.