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

# Unidade de cuidado

> Cadastrar e consultar as unidades de cuidado do seu ambiente, no padrão FHIR Organization.

Uma **unidade de cuidado** é como a sua operação se divide dentro do Nilo Care: uma clínica,
uma regional, uma frente de atendimento. Pacientes, profissionais e equipes de cuidado são
todos alocados a uma unidade, e é ela que delimita quem enxerga quem — um profissional
vinculado à *Unidade Centro* trabalha com os pacientes da *Unidade Centro*.

Na tela a unidade aparece como o campo **Unidade de cuidado**: no cadastro do paciente, na
ficha dele e no cadastro das equipes de cuidado, sempre como uma escolha em lista.

No FHIR o recurso é o [`Organization`](https://hl7.org/fhir/R4/organization.html). Esta
página é curta de propósito: **a unidade tem um único dado gravável, o nome**. O valor dela
está em ser referenciada — por
[Paciente](/guia/recursos/patient), [Profissional](/guia/recursos/practitioner) e
[Equipe de cuidado](/guia/recursos/careteam) —, e é por isso que ela costuma ser a
primeira coisa que uma integração cadastra.

## Campos

A coluna **No Nilo Care** traz o rótulo com que o dado aparece para a equipe; são rótulos,
não caminhos de navegação.

| Campo          | Obrigatório | O que significa                                                                                           | No Nilo Care                                          |
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `resourceType` | **sim**     | Constante `Organization`                                                                                  | —                                                     |
| `identifier`   | **sim**     | Suas chaves da unidade. É por elas que a API decide entre criar uma unidade nova e renomear uma existente | —                                                     |
| `name`         | **sim**     | Nome da unidade, com no máximo **200 caracteres**                                                         | **Unidade de cuidado**, o rótulo escolhido nas listas |
| `active`       | não         | Só resposta: constante `true`                                                                             | —                                                     |
| `alias`        | não         | Só resposta: repete o `name`                                                                              | —                                                     |
| `telecom`      | não         | Só resposta: o telefone da **sua operação**, não desta unidade                                            | —                                                     |
| `id` · `meta`  | não         | Só resposta: identificador Nilo FHIR da unidade e metadados da gravação                                   | —                                                     |

> **Note**
>
> A referência declara `name` como obrigatório porque é o **único** dado que a plataforma
> guarda desta unidade. O `Organization` do FHIR R4, em si, não exige o nome — quem recusa o
> payload sem nome é a plataforma, e por isso essa recusa tem uma forma diferente das outras:
> vem como `code: exception`, sem `expression`. Veja [Erros](#erros).

### Campos que a Nilo não usa

O `Organization` canônico traz muito mais do que esta integração lê: `type`, `address`,
`partOf`, `contact`, `endpoint`, `text` e `contained`. Nenhum deles é lido, e por isso nenhum
aparece na referência do recurso.

> **Note**
>
> A referência lista só os campos suportados e por isso **rejeita os demais no seu validador**,
> mas a API em si **não recusa** quem os manda. O que acontece com eles é que ficam guardados no
> recurso e voltam nas leituras seguintes — sem nunca terem significado nada para a plataforma, e
> sem aparecer em lugar nenhum do Nilo Care. Um `address` enviado assim parece o endereço da
> unidade, e não é. Omita-os.

## Cadastrar ou atualizar

### Request

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

**`Cadastrar uma unidade`**

```curl Cadastrar uma unidade
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Organization \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Organization",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    }
  ],
  "name": "Unidade Centro"
}'
```

**`Cadastrar uma unidade`**

```python Cadastrar uma unidade
import requests

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

payload = {
    "resourceType": "Organization",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/unidade/",
            "value": "UC-01",
            "use": "usual"
        }
    ],
    "name": "Unidade Centro"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cadastrar uma unidade`**

```javascript Cadastrar uma unidade
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Organization';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Organization","identifier":[{"system":"https://www.acmesaude.com.br/integracao/unidade/","value":"UC-01","use":"usual"}],"name":"Unidade Centro"}'
};

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

**`Cadastrar uma unidade`**

```go Cadastrar uma unidade
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro\"\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))

}
```

**`Cadastrar uma unidade`**

```ruby Cadastrar uma unidade
require 'uri'
require 'net/http'

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

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\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro\"\n}"

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

**`Cadastrar uma unidade`**

```java Cadastrar uma unidade
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/Organization")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro\"\n}")
  .asString();
```

**`Cadastrar uma unidade`**

```php Cadastrar uma unidade
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Organization', [
  'body' => '{
  "resourceType": "Organization",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    }
  ],
  "name": "Unidade Centro"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cadastrar uma unidade`**

```csharp Cadastrar uma unidade
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Organization");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cadastrar uma unidade`**

```swift Cadastrar uma unidade
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Organization",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    ]
  ],
  "name": "Unidade Centro"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Organization")! 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": "Organization",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--care-unit",
      "value": "812",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    }
  ],
  "name": "Unidade Centro",
  "id": "3f2b91d7-64c8-4a15-8e77-51a0b9c3d204",
  "meta": {
    "lastUpdated": "2026-08-24T11:20:41.207000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "active": true,
  "alias": [
    "Unidade Centro"
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "+551155556473"
    }
  ]
}
```

Guarde o `id`: é por ele que se faz a leitura direta. Ao lado do seu `identifier`, a resposta
traz o identificador Nilo da unidade, no `system`
`…/NamingSystem/sorting-hat-api--care-unit` — é esse valor que aparece nas referências dos
outros recursos quando a sua implantação não usa identificadores externos.

O mesmo `POST` cria e atualiza. Reenviando um `identifier` que já corresponde a uma unidade,
ela é **renomeada**:

### Request

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

**`Renomear uma unidade`**

```curl Renomear uma unidade
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Organization \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Organization",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    }
  ],
  "name": "Unidade Centro — Matriz"
}'
```

**`Renomear uma unidade`**

```python Renomear uma unidade
import requests

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

payload = {
    "resourceType": "Organization",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/unidade/",
            "value": "UC-01",
            "use": "usual"
        }
    ],
    "name": "Unidade Centro — Matriz"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Renomear uma unidade`**

```javascript Renomear uma unidade
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Organization';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Organization","identifier":[{"system":"https://www.acmesaude.com.br/integracao/unidade/","value":"UC-01","use":"usual"}],"name":"Unidade Centro — Matriz"}'
};

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

**`Renomear uma unidade`**

```go Renomear uma unidade
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro — Matriz\"\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))

}
```

**`Renomear uma unidade`**

```ruby Renomear uma unidade
require 'uri'
require 'net/http'

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

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\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro — Matriz\"\n}"

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

**`Renomear uma unidade`**

```java Renomear uma unidade
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/Organization")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro — Matriz\"\n}")
  .asString();
```

**`Renomear uma unidade`**

```php Renomear uma unidade
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Organization', [
  'body' => '{
  "resourceType": "Organization",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    }
  ],
  "name": "Unidade Centro — Matriz"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Renomear uma unidade`**

```csharp Renomear uma unidade
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Organization");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Organization\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/unidade/\",\n      \"value\": \"UC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Unidade Centro — Matriz\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Renomear uma unidade`**

```swift Renomear uma unidade
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Organization",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    ]
  ],
  "name": "Unidade Centro — Matriz"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Organization")! 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()
```

> **Warning**
>
> **Não há como desativar nem excluir uma unidade por esta API.** O `active` da resposta é
> sempre `true`, e enviá-lo como `false` não muda nada. Encerrar uma unidade é assunto do
> **Suporte**.

> **Note**
>
> Renomear é seguro: nenhum vínculo de paciente, profissional ou equipe é afetado. O que muda é
> o rótulo, em todos os lugares onde a unidade aparece.

## Buscar

### Request

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

**`Busca com resultados`**

```curl Busca com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/Organization \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     -d active=true \
     --data-urlencode identifier=https://www.acmesaude.com.br/integracao/unidade/|UC-01 \
     -d name=Centro
```

**`Busca com resultados`**

```python Busca com resultados
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","active":"true","identifier":"https://www.acmesaude.com.br/integracao/unidade/|UC-01","name":"Centro"}

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/Organization?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&active=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Funidade%2F%7CUC-01&name=Centro';
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/Organization?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&active=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Funidade%2F%7CUC-01&name=Centro"

	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/Organization?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&active=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Funidade%2F%7CUC-01&name=Centro")

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/Organization?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&active=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Funidade%2F%7CUC-01&name=Centro")
  .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/Organization?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&active=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Funidade%2F%7CUC-01&name=Centro', [
  '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/Organization?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&active=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Funidade%2F%7CUC-01&name=Centro");
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/Organization?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&active=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Funidade%2F%7CUC-01&name=Centro")! 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/Organization/3f2b91d7-64c8-4a15-8e77-51a0b9c3d204",
      "resource": {
        "resourceType": "Organization",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--care-unit",
            "value": "812",
            "use": "usual"
          },
          {
            "system": "https://www.acmesaude.com.br/integracao/unidade/",
            "value": "UC-01",
            "use": "usual"
          }
        ],
        "name": "Unidade Centro",
        "id": "3f2b91d7-64c8-4a15-8e77-51a0b9c3d204",
        "active": true,
        "alias": [
          "Unidade Centro"
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "+551155556473"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Organization/9c4e5b60-1f8a-42d3-b7e1-6d0a2f3c8815",
      "resource": {
        "resourceType": "Organization",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--care-unit",
            "value": "813",
            "use": "usual"
          }
        ],
        "name": "Unidade Zona Sul",
        "id": "9c4e5b60-1f8a-42d3-b7e1-6d0a2f3c8815",
        "active": true,
        "alias": [
          "Unidade Zona Sul"
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "+551155556473"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

> **Note**
>
> Busca sem resultados não é erro: volta `200` com um `Bundle` cujo `entry` é uma lista vazia.
> Trate a ausência de resultados pela lista vazia, não esperando um `404`.

### 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 unidade, em `system\|value`. Aceita a sua chave ou o identificador Nilo | `Organization.identifier`                 |
| `name`         | [string](https://hl7.org/fhir/R4/search.html#string) | Parte do nome da unidade. Casa também com o `alias`, que repete o nome                   | `Organization.name \| Organization.alias` |
| `active`       | [token](https://hl7.org/fhir/R4/search.html#token)   | Aceito, e inútil: toda unidade é `true`                                                  | `Organization.active`                     |
| `_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 `Organization` existem e **não encontram nada** aqui,
> porque a Nilo não preenche o campo correspondente: `address` e as suas variações,
> `type`, `partof` e `endpoint`. A exceção é o campo que **você mesmo** tenha enviado: ele fica
> no recurso e passa a ser encontrável — mais um motivo para omitir o que a plataforma não usa.

A busca sem filtro nenhum é a chamada mais útil deste recurso: as unidades de um ambiente são
poucas, e listá-las é como se descobre o identificador para referenciar em outros recursos.

```bash
curl --request GET \
  --url 'https://landing-zone-api.nilo.services/fhir/resources/Organization' \
  --header 'x-api-key: SUA_API_KEY'
```

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

> **Note**
>
> A consulta não devolve só as unidades que você criou: as criadas ou alteradas dentro do Nilo
> Care também aparecem. Elas trazem apenas o identificador Nilo, no `system`
> `…/NamingSystem/sorting-hat-api--care-unit`; só as que vieram por integração trazem também a
> sua chave. É por essa diferença que você separa umas das outras.
>
> Uma unidade antiga, que ninguém tenha tocado desde que a sua integração começou, pode não
> aparecer na lista. Se você espera uma unidade e ela não vem, peça ao **Suporte** — a busca não
> é um inventário garantido do ambiente.

### Adotar uma unidade que já existe

Para passar a referenciar pela **sua** chave uma unidade que já estava na plataforma, envie um
`POST` com os **dois** identificadores: o Nilo, que casa com a unidade existente, e o seu, que
fica gravado ao lado. A partir daí as duas chaves encontram a mesma unidade, e você não precisa
mais carregar o identificador Nilo.

Mande no `name` o nome que a unidade já tem — lembre que o `name` é sempre gravado, e um nome
diferente renomeia a unidade.

## Ler por ID

### Request

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

**`Unidade encontrada`**

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

**`Unidade encontrada`**

```python Unidade encontrada
import requests

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

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

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

print(response.json())
```

**`Unidade encontrada`**

```javascript Unidade encontrada
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Organization/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);
}
```

**`Unidade encontrada`**

```go Unidade encontrada
package main

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

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Organization/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))

}
```

**`Unidade encontrada`**

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

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Organization/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
```

**`Unidade encontrada`**

```java Unidade 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/Organization/id")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Unidade encontrada`**

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

$client = new \GuzzleHttp\Client();

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

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

**`Unidade encontrada`**

```csharp Unidade encontrada
using RestSharp;

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

**`Unidade encontrada`**

```swift Unidade encontrada
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Organization/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 unidade está em
> `resource`. Ler `name` na raiz da resposta não encontra nada.

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Organization/3f2b91d7-64c8-4a15-8e77-51a0b9c3d204",
  "resource": {
    "resourceType": "Organization",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--care-unit",
        "value": "812",
        "use": "usual"
      },
      {
        "system": "https://www.acmesaude.com.br/integracao/unidade/",
        "value": "UC-01",
        "use": "usual"
      }
    ],
    "name": "Unidade Centro",
    "id": "3f2b91d7-64c8-4a15-8e77-51a0b9c3d204",
    "meta": {
      "lastUpdated": "2026-08-24T11:20:41.207000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "active": true,
    "alias": [
      "Unidade Centro"
    ],
    "telecom": [
      {
        "system": "phone",
        "value": "+551155556473"
      }
    ]
  },
  "search": {
    "mode": "match"
  }
}
```

## Valores devolvidos que não são da unidade

Dois campos da resposta enganam, e vale saber antes de construir tela em cima deles:

> **Warning**
>
> **`telecom` é o telefone da sua operação, não o desta unidade.** Todas as unidades do ambiente
> devolvem o mesmo número — o cadastrado para o seu ambiente. Ele é omitido quando não há
> telefone cadastrado. Não trate esse valor como contato da unidade.
>
> E ao contrário dos campos não suportados, um `telecom` que **você** envie não sobrevive: ele é
> substituído pelo telefone do ambiente na gravação. Não há como registrar um telefone próprio da
> unidade por esta API.

> **Note**
>
> **`alias` repete o `name`.** É sempre uma lista de um item, com o mesmo texto do nome, e
> nunca traz um nome alternativo de verdade. Existe para quem lê o `alias` do `Organization`
> canônico e não encontraria nada.

## Onde a unidade é referenciada

| Recurso                                      | Campo                                | O que a unidade faz ali                                                                                                                                     |
| -------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Paciente](/guia/recursos/patient)           | `managingOrganization`               | A unidade responsável pelo paciente. Omitido, um paciente já cadastrado mantém a unidade que tem; um paciente novo vai para a unidade padrão da implantação |
| [Profissional](/guia/recursos/practitioner)  | extensão `practitioner-organization` | Vincula o profissional à unidade, e com ela ao acesso aos pacientes dela. Repetível, e só adiciona                                                          |
| [Equipe de cuidado](/guia/recursos/careteam) | `managingOrganization`               | A unidade da equipe. Havendo mais de um item, vale o último reconhecido                                                                                     |

Nos três casos a unidade precisa já existir, e é referenciada **por identificador**. Cadastre
as unidades antes de cadastrar paciente, profissional ou equipe.

> **Warning**
>
> **Qual identificador vale muda conforme o recurso.** Paciente e Profissional aceitam qualquer
> identificador da unidade, inclusive a sua chave — no Paciente, a referência precisa vir com
> `"type": "Organization"` para a chave própria ser resolvida. A Equipe de cuidado é a exceção:
> ela lê **só o identificador Nilo** da unidade, e um identificador do seu sistema é ignorado em
> silêncio, caindo na unidade padrão.

> **Note**
>
> Alguns desses campos caem numa **unidade padrão** da implantação quando você os omite. Isso é
> configuração do seu ambiente, não do recurso: se não houver unidade padrão configurada, a
> escrita do outro recurso é recusada. Veja a página de cada um.

## Efeitos colaterais

> **Note**
>
> Criar uma unidade **não move ninguém para ela**. A unidade nasce vazia; pacientes,
> profissionais e equipes só passam a pertencer a ela quando os recursos deles a referenciam.

> **Note**
>
> Este endpoint nunca responde `204`: não há remoção de unidade por integração.

## Erros

Recusa é `400`, e o corpo é um `OperationOutcome`: `issue[].details.text` explica o motivo e,
quando a recusa é de um campo conferido por esta API, `issue[].expression` aponta qual.

| `code`          | `expression`              | Mensagem                                                                                                     | Quando                                                                                  |
| --------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `required`      | `Organization.identifier` | `Field is required`                                                                                          | O payload não tem `identifier`                                                          |
| `business-rule` | `Organization.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 — falta `system` ou falta `value`                |
| `structure`     | —                         | `Resource has identifier from a Nilo environment that is not the current environment.`                       | O payload traz um identificador Nilo gerado em outro ambiente                           |
| `structure`     | o campo recusado          | mensagem da validação FHIR                                                                                   | O payload não é um `Organization` válido — tipo errado num campo, valor fora do formato |
| `exception`     | —                         | `HTTPBadRequest: …`                                                                                          | O `name` está ausente, ou passa de 200 caracteres                                       |

> **Warning**
>
> A última linha não é uma validação desta API — é a recusa da própria plataforma, repassada
> como está. Ela sai com `code: exception`, **sem `expression`**, e com uma mensagem de erro de
> linguagem em vez de uma explicação do campo. Não tente interpretar o texto: trate
> `code: exception` como "payload recusado, motivo não classificado" e confira o `name`.

### Response (200)

```json
{
  "resourceType": "Organization",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--care-unit",
      "value": "812",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/unidade/",
      "value": "UC-01",
      "use": "usual"
    }
  ],
  "name": "Unidade Centro",
  "id": "3f2b91d7-64c8-4a15-8e77-51a0b9c3d204",
  "meta": {
    "lastUpdated": "2026-08-24T11:20:41.207000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "active": true,
  "alias": [
    "Unidade Centro"
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "+551155556473"
    }
  ]
}
```

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