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

# Catálogo de códigos

> Consultar os catálogos de códigos do seu ambiente — etiquetas e categorias de etiqueta — no padrão FHIR CodeSystem.

Um **catálogo de códigos** é a lista de valores que a plataforma aceita num campo codificado.
Hoje há **dois**, e os dois servem à [etiqueta do paciente](/guia/recursos/flag):

| Catálogo               | Nome            | O que lista                                           |
| ---------------------- | --------------- | ----------------------------------------------------- |
| Etiquetas              | `flag-code`     | Os marcadores que a equipe pode aplicar a um paciente |
| Categorias de etiqueta | `flag-category` | Os agrupamentos dessas etiquetas                      |

No FHIR o recurso é o
[`CodeSystem`](https://hl7.org/fhir/R4/codesystem.html), e ele existe aqui por um motivo
prático: **os códigos não são um vocabulário fixo**. Cada ambiente tem os seus, cadastrados na
implantação, e a única forma de saber quais existem é lendo estes catálogos.

> **Warning**
>
> **Este recurso é somente leitura.** Não existe `POST /fhir/resources/CodeSystem` — os catálogos
> são montados pela equipe no Nilo Care, nas configurações do ambiente.

## Campos

Todos os campos são de resposta — nenhum deles é enviado por você.

| Campo           | Sempre presente | O que significa                                                                           |
| --------------- | --------------- | ----------------------------------------------------------------------------------------- |
| `resourceType`  | sim             | Constante `CodeSystem`                                                                    |
| `url`           | sim             | Diz **qual** catálogo é este. É o mesmo valor que vai no `system` do `coding` da etiqueta |
| `status`        | sim             | Constante `active`                                                                        |
| `content`       | sim             | Constante `complete` — a lista vem inteira, não em pedaços                                |
| `publisher`     | sim             | Constante `Nilo Saude`                                                                    |
| `compositional` | sim             | Constante `false`                                                                         |
| `count`         | sim             | Quantos códigos o catálogo tem                                                            |
| `concept[]`     | sim             | Um item por código: o `code` e o `display`                                                |
| `id` · `meta`   | sim             | Identificador Nilo FHIR do recurso e metadados da gravação                                |

> **Note**
>
> `concept[].code` é o valor que vai em `Flag.code.coding[].code` (ou em
> `Flag.category.coding[].code`), e `concept[].display` é o nome que a equipe vê. São os dois
> únicos dados de cada código: não há descrição, hierarquia, sinônimo nem propriedade.

> **Warning**
>
> **Só os códigos vigentes aparecem.** Uma etiqueta encerrada no Nilo Care some do catálogo — e
> some sem deixar rastro, porque não há campo de situação por código.
>
> Consequência: uma etiqueta aplicada a um paciente pode referenciar um código que **não está
> mais** no catálogo. Ao ler uma [etiqueta](/guia/recursos/flag), não conte com encontrar o
> código dela aqui — o `display` da própria etiqueta já traz o nome.

## Ler um catálogo

O caminho é `GET /fhir/resources/CodeSystem/{nome}`, com `flag-code` ou `flag-category`.

> **Warning**
>
> **Este é o único caminho do projeto em que o segmento final não é o `id` do recurso.** Em todos
> os outros recursos, `/{id}` é o identificador Nilo FHIR; aqui é o **nome** do catálogo.
>
> Passar o `id` do recurso neste caminho **não funciona** — e é justamente o que o `fullUrl` do
> envelope traz. Ignore o `fullUrl` deste recurso: para reler o catálogo, monte o caminho com o
> nome.

### Request

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

**`Catálogo encontrado`**

```curl Catálogo encontrado
curl https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code \
     -H "x-api-key: <apiKey>"
```

**`Catálogo encontrado`**

```python Catálogo encontrado
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code"

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

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

print(response.json())
```

**`Catálogo encontrado`**

```javascript Catálogo encontrado
const url = 'https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code';
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);
}
```

**`Catálogo encontrado`**

```go Catálogo encontrado
package main

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

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code"

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

}
```

**`Catálogo encontrado`**

```ruby Catálogo encontrado
require 'uri'
require 'net/http'

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

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

**`Catálogo encontrado`**

```java Catálogo encontrado
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/CodeSystem/flag-code")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Catálogo encontrado`**

```php Catálogo encontrado
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

**`Catálogo encontrado`**

```csharp Catálogo encontrado
using RestSharp;

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

**`Catálogo encontrado`**

```swift Catálogo encontrado
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code")! 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**
>
> 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 o catálogo está em `resource`. Ler `concept` na
> raiz da resposta não encontra nada.

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/7d0a41f8-25c6-4b93-81ea-06c5d2794b13",
  "resource": {
    "resourceType": "CodeSystem",
    "url": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-category",
    "status": "active",
    "content": "complete",
    "publisher": "Nilo Saude",
    "compositional": false,
    "count": 2,
    "concept": [
      {
        "code": "12",
        "display": "Condições de saúde"
      },
      {
        "code": "13",
        "display": "Operacional"
      }
    ],
    "id": "7d0a41f8-25c6-4b93-81ea-06c5d2794b13",
    "meta": {
      "lastUpdated": "2026-05-04T10:15:34.902000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM5OQ"
    }
  },
  "search": {
    "mode": "match"
  }
}
```

## Buscar

### Request

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

**`Catálogo de etiquetas`**

```curl Catálogo de etiquetas
curl -G https://landing-zone-api.nilo.services/fhir/resources/CodeSystem \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     --data-urlencode url=https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code
```

**`Catálogo de etiquetas`**

```python Catálogo de etiquetas
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","url":"https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code"}

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

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

print(response.json())
```

**`Catálogo de etiquetas`**

```javascript Catálogo de etiquetas
const url = 'https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&url=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FCodeSystem%2Fflag-code';
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);
}
```

**`Catálogo de etiquetas`**

```go Catálogo de etiquetas
package main

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

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&url=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FCodeSystem%2Fflag-code"

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

}
```

**`Catálogo de etiquetas`**

```ruby Catálogo de etiquetas
require 'uri'
require 'net/http'

url = URI("https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&url=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FCodeSystem%2Fflag-code")

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

**`Catálogo de etiquetas`**

```java Catálogo de etiquetas
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/CodeSystem?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&url=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FCodeSystem%2Fflag-code")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Catálogo de etiquetas`**

```php Catálogo de etiquetas
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&url=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FCodeSystem%2Fflag-code', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Catálogo de etiquetas`**

```csharp Catálogo de etiquetas
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&url=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FCodeSystem%2Fflag-code");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

**`Catálogo de etiquetas`**

```swift Catálogo de etiquetas
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&url=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FCodeSystem%2Fflag-code")! 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`. Como só há dois catálogos, a busca sem
filtro devolve os dois:

### Response (200)

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/b5e1207c-63a9-4d81-90f2-e478a3c15d60",
      "resource": {
        "resourceType": "CodeSystem",
        "url": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/flag-code",
        "status": "active",
        "content": "complete",
        "publisher": "Nilo Saude",
        "compositional": false,
        "count": 3,
        "concept": [
          {
            "code": "318",
            "display": "Gestante"
          },
          {
            "code": "319",
            "display": "Alto risco"
          },
          {
            "code": "412",
            "display": "Prioridade no atendimento"
          }
        ],
        "id": "b5e1207c-63a9-4d81-90f2-e478a3c15d60",
        "meta": {
          "lastUpdated": "2026-05-04T10:15:34.771000Z",
          "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
        }
      },
      "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                 |
| -------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
| `url`          | [uri](https://hl7.org/fhir/R4/search.html#uri)       | A URL **exata** do catálogo. É o filtro que separa um do outro     | `CodeSystem.url`          |
| `system`       | [uri](https://hl7.org/fhir/R4/search.html#uri)       | O mesmo campo que `url`                                            | `CodeSystem.url`          |
| `code`         | [token](https://hl7.org/fhir/R4/search.html#token)   | Devolve o catálogo que **contém** o código informado               | `CodeSystem.concept.code` |
| `status`       | [token](https://hl7.org/fhir/R4/search.html#token)   | Aceito, e inútil: todo catálogo é `active`                         | `CodeSystem.status`       |
| `content-mode` | [token](https://hl7.org/fhir/R4/search.html#token)   | Aceito, e inútil: todo catálogo é `complete`                       | `CodeSystem.content`      |
| `publisher`    | [string](https://hl7.org/fhir/R4/search.html#string) | Aceito, e inútil: todo catálogo é `Nilo Saude`                     | `CodeSystem.publisher`    |
| `_lastUpdated` | [date](https://hl7.org/fhir/R4/search.html#date)     | Data da última gravação no store, com os prefixos `eq`, `ge`, `le` | —                         |

> **Note**
>
> Os demais parâmetros canônicos do `CodeSystem` existem e **não encontram nada**, porque a
> plataforma não preenche o campo correspondente: `name`, `title`, `version`, `identifier`,
> `context`, `jurisdiction`, `description`, `language` e `supplements`.

## Como o catálogo é atualizado

> **Warning**
>
> **Qualquer alteração numa etiqueta republica o catálogo inteiro.** O recurso é sempre a lista
> completa: acrescentar, renomear ou encerrar uma etiqueta reescreve o `CodeSystem` inteiro, com
> um `meta.versionId` novo.
>
> Isso vale inclusive para a **remoção**: encerrar uma etiqueta não apaga o catálogo — ele é
> republicado sem ela. Não trate uma mudança de versão do catálogo como sinal de que algo
> específico mudou; compare as listas.

> **Note**
>
> Encerrar uma **categoria** encerra, junto, todas as etiquetas dela — então uma única ação faz os
> **dois** catálogos mudarem de versão ao mesmo tempo.

> **Note**
>
> Como o catálogo é pequeno e muda pouco, o padrão de uso recomendado é lê-lo uma vez, guardar o
> mapa código → nome do seu lado, e reler quando uma etiqueta trouxer um código que você não
> conhece.

## Cadastrar ou atualizar

**Não existe.** Este recurso não tem caminho de escrita nesta API — nem para criar um catálogo,
nem para acrescentar um código a um existente.

> **Warning**
>
> Um `POST /fhir/resources/CodeSystem` **não é uma operação suportada** e não devolve um erro de
> validação tratável: a chamada falha com erro inesperado do servidor (`500`). Não escreva
> tratamento em cima desse comportamento — ele não é contrato, e nada é gravado.

Para cadastrar uma etiqueta nova no catálogo, peça à equipe que a crie em
*Configurações › Etiquetas*, no Nilo Care — lembrando que a **categoria precisa existir antes**
da etiqueta.

## O que a integração não cobre

* **outros catálogos**: só etiquetas e categorias de etiqueta são publicados assim. Os códigos
  de procedimento, de especialidade e de diagnóstico usam vocabulários externos, e não têm
  catálogo próprio nesta API;
* a **situação** de cada código — encerrados simplesmente somem;
* a **hierarquia** entre códigos, e qualquer propriedade além de `code` e `display`;
* a ligação entre uma **categoria** e as etiquetas que pertencem a ela: os dois catálogos são
  listas planas, e o vínculo só aparece na leitura de uma
  [etiqueta](/guia/recursos/flag), que traz as duas.