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

# Local de atendimento

> Cadastrar e consultar os estabelecimentos de saúde onde o cuidado acontece, no padrão FHIR Location.

Um **local de atendimento** é o espaço físico onde o cuidado acontece: o hospital, a clínica,
o ambulatório. Ele guarda três coisas — o **nome**, o **código CNES** e o **endereço** — e
existe para que todo mundo saiba onde um evento de saúde aconteceu ou vai acontecer.

No Nilo Care esses registros ficam em **Estabelecimentos de saúde**, nas configurações do
ambiente, visíveis para quem tem perfil de gestor. É lá que aparecem os campos **Nome**,
**Código CNES** e o bloco **Endereço**. O mesmo cadastro aparece como **Locais de
atendimento** no formulário do profissional, onde se escolhe onde cada um atende.

No FHIR o recurso é o [`Location`](https://hl7.org/fhir/R4/location.html).

## 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 `Location`                                                      | —                  |
| `identifier`                                             | **sim**                      | Suas chaves do local. É por elas que a API decide entre criar e atualizar | —                  |
| `identifier` com `system` `https://cnes.datasus.gov.br/` | não                          | Tratado à parte: o `value` vira o **código CNES** do estabelecimento      | **Código CNES**    |
| `name`                                                   | **sim**                      | Nome do estabelecimento, com no máximo 200 caracteres                     | **Nome**           |
| `address`                                                | não                          | Endereço do estabelecimento                                               | seção **Endereço** |
| `address.line`                                           | **sim**, se houver `address` | Logradouro, número e complemento, por posição                             | —                  |
| `address.line[0]`                                        | —                            | Logradouro                                                                | **Rua**            |
| `address.line[1]`                                        | —                            | Número, com no máximo 10 caracteres                                       | **Número**         |
| `address.line[2]`                                        | —                            | Complemento                                                               | **Complemento**    |
| `address.district`                                       | não                          | Bairro                                                                    | **Bairro**         |
| `address.city`                                           | não                          | Cidade                                                                    | **Cidade**         |
| `address.state`                                          | não                          | Estado, por extenso ou pela sigla                                         | **Estado (UF)**    |
| `address.country`                                        | não                          | País                                                                      | **País**           |
| `address.postalCode`                                     | **sim**, se houver `address` | CEP                                                                       | **CEP**            |
| `address.text` · `address.use` · `address.type`          | não                          | Só resposta: o endereço em uma linha, e as constantes `work` e `both`     | —                  |
| `id` · `meta`                                            | não                          | Só resposta: identificador Nilo FHIR do local e metadados da gravação     | —                  |

> **Warning**
>
> **Enviando `address`, o `line` e o `postalCode` vão junto.** São os dois campos sem os quais a
> chamada é recusada; bairro, cidade, estado e país são opcionais. Se você não tem o CEP ou o
> logradouro, é melhor **omitir o `address` inteiro** numa criação — mas veja o aviso sobre
> atualização logo abaixo.
>
> Um `address` sem `line` não é recusado com uma mensagem de campo: cai num erro genérico
> (`code: exception`), que é a forma mais difícil de diagnosticar. Mande sempre o `line`.

### Campos que a Nilo não usa

O `Location` canônico traz muito mais do que esta integração lê: `status`,
`operationalStatus`, `alias`, `description`, `mode`, `type`, `telecom`, `physicalType`,
`position`, `managingOrganization`, `partOf`, `hoursOfOperation`, `availabilityExceptions` e
`endpoint`. Nenhum deles é lido, e por isso nenhum aparece na referência do recurso.

> **Note**
>
> A referência lista só os campos suportados, e é assim que ela deve ser lida: **o que mandar na
> escrita**. 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. Um
> `telecom` enviado assim parece o telefone do estabelecimento, e não é: o contato do
> estabelecimento existe no Nilo Care — **Celular**, **E-mail**, **Telefone comercial**, **Site**
> —, mas **não é exposto nem gravável por esta API**.

> **Warning**
>
> Isso vale para os campos **de topo**. Dentro de `address`, não: o endereço é remontado inteiro a
> cada leitura, e o que a Nilo não usa é **descartado**. Um `address.period`, um `line[3]` ou um
> `address.use` que você envie somem sem aviso.

## Cadastrar ou atualizar

### Request

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

**`Cadastrar um local com endereço`**

```curl Cadastrar um local com endereço
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Location \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Location",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    }
  ],
  "name": "Hospital Central Acme",
  "address": {
    "line": [
      "Rua Tamandaré",
      "321",
      "Casa 2"
    ],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  }
}'
```

**`Cadastrar um local com endereço`**

```python Cadastrar um local com endereço
import requests

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

payload = {
    "resourceType": "Location",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/local/",
            "value": "HC-01",
            "use": "usual"
        }
    ],
    "name": "Hospital Central Acme",
    "address": {
        "line": ["Rua Tamandaré", "321", "Casa 2"],
        "postalCode": "01503-001",
        "district": "Liberdade",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil"
    }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cadastrar um local com endereço`**

```javascript Cadastrar um local com endereço
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Location';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Location","identifier":[{"system":"https://www.acmesaude.com.br/integracao/local/","value":"HC-01","use":"usual"}],"name":"Hospital Central Acme","address":{"line":["Rua Tamandaré","321","Casa 2"],"postalCode":"01503-001","district":"Liberdade","city":"São Paulo","state":"SP","country":"Brasil"}}'
};

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

**`Cadastrar um local com endereço`**

```go Cadastrar um local com endereço
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\",\n      \"Casa 2\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\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))

}
```

**`Cadastrar um local com endereço`**

```ruby Cadastrar um local com endereço
require 'uri'
require 'net/http'

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

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\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\",\n      \"Casa 2\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\n  }\n}"

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

**`Cadastrar um local com endereço`**

```java Cadastrar um local com endereço
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/Location")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\",\n      \"Casa 2\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\n  }\n}")
  .asString();
```

**`Cadastrar um local com endereço`**

```php Cadastrar um local com endereço
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Location', [
  'body' => '{
  "resourceType": "Location",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    }
  ],
  "name": "Hospital Central Acme",
  "address": {
    "line": [
      "Rua Tamandaré",
      "321",
      "Casa 2"
    ],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cadastrar um local com endereço`**

```csharp Cadastrar um local com endereço
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Location");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\",\n      \"Casa 2\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cadastrar um local com endereço`**

```swift Cadastrar um local com endereço
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Location",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    ]
  ],
  "name": "Hospital Central Acme",
  "address": [
    "line": ["Rua Tamandaré", "321", "Casa 2"],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Location")! 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": "Location",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--health-facility",
      "value": "295",
      "use": "usual"
    },
    {
      "system": "https://cnes.datasus.gov.br/",
      "value": "2077485",
      "use": "official"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    }
  ],
  "name": "Hospital Central Acme",
  "id": "8b53f107-2d94-4c6e-a71f-9042e5b8c316",
  "meta": {
    "lastUpdated": "2026-08-24T13:42:07.554000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "address": {
    "line": [
      "Rua Tamandaré",
      "321",
      "Casa 2"
    ],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil",
    "text": "Rua Tamandaré, 321, Casa 2 - Liberdade, São Paulo/SP. 01503-001.",
    "use": "work",
    "type": "both"
  }
}
```

Guarde o `id`: é por ele que se faz a leitura direta. Ao lado das suas chaves, a resposta traz
o identificador Nilo do local, no `system` `…/NamingSystem/almanac-api--health-facility`.

### O endereço é posicional

`address.line` não é texto livre: as três posições têm significado fixo.

| Posição   | Significado | No Nilo Care    |
| --------- | ----------- | --------------- |
| `line[0]` | Logradouro  | **Rua**         |
| `line[1]` | Número      | **Número**      |
| `line[2]` | Complemento | **Complemento** |

> **Warning**
>
> **Não pule posições encurtando a lista.** Enviar `["Rua Tamandaré", "Casa 2"]` grava *Casa 2*
> como **número**, não como complemento.
>
> E **não há como deixar uma posição em branco**: string vazia é recusada pela validação do
> FHIR, com `code: structure` apontando a posição. Endereço sem número usa a convenção `S/N` no
> lugar — `["Rua Tamandaré", "S/N", "Casa 2"]`.

> **Warning**
>
> **A leitura encurta a lista.** Posições sem valor são **omitidas** na resposta: um local sem
> complemento volta com `line` de dois itens, e um local sem número volta com dois itens em que
> o segundo é o complemento.
>
> Reenviar uma resposta como ela veio pode, por isso, mover o complemento para o número. Ao
> reenviar um endereço lido, reconstrua as três posições a partir do que cada uma significa, não
> da ordem em que vieram.

### O endereço é completado pela plataforma

> **Note**
>
> O endereço enviado é **conferido e completado** contra uma base de endereços antes de ser
> gravado. O que você mandou preenchido **volta como você mandou** — `state: SP` volta `SP`. O
> que muda é o resto:
>
> * os campos que você **deixou de fora** podem voltar preenchidos, completados a partir dos que
>   você enviou — bairro, cidade, estado ou país, por exemplo;
> * a **capitalização** é normalizada: `rua tamandaré` volta `Rua Tamandaré`.
>
> Por isso a resposta de uma escrita raramente é idêntica ao que você mandou. Isso é esperado, e
> não indica erro.

> **Warning**
>
> Numa **atualização** que traga `postalCode`, os demais campos do endereço são recalculados a
> partir dele. Reenviar o endereço inteiro é o caminho seguro; reenviar só o CEP pode trocar o
> resto.

### Atualizar

O mesmo `POST` cria e atualiza. Reenviando um `identifier` que já corresponde a um local, ele
é atualizado.

> **Warning**
>
> **Omitir `address` numa atualização apaga o endereço já cadastrado.** Ao contrário dos demais
> campos, o endereço não é preservado por omissão: um `POST` só com `identifier` e `name` sobre
> um local que tinha endereço deixa o estabelecimento **sem endereço nenhum** no Nilo Care.
>
> Se você só quer corrigir o nome, reenvie o endereço junto — inteiro, com o `line` e o
> `postalCode`.

> **Warning**
>
> **E essa remoção é invisível por aqui.** O recurso FHIR guarda o último endereço gravado, então
> a resposta do `POST` e todas as leituras seguintes continuam mostrando o endereço que sumiu do
> cadastro. Não use o `GET` para confirmar que o endereço foi removido: ele não vai refletir isso.

> **Note**
>
> O **código CNES**, esse sim, é preservado: uma atualização sem o identificador
> `https://cnes.datasus.gov.br/` mantém o CNES que o estabelecimento já tinha. Para trocá-lo,
> mande o identificador novo.

### O código CNES

O CNES entra como um identificador com o `system` `https://cnes.datasus.gov.br/`:

### Request

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

**`Cadastrar com código CNES`**

```curl Cadastrar com código CNES
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Location \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Location",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    },
    {
      "system": "https://cnes.datasus.gov.br/",
      "value": "2077485",
      "use": "official"
    }
  ],
  "name": "Hospital Central Acme",
  "address": {
    "line": [
      "Rua Tamandaré",
      "321"
    ],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  }
}'
```

**`Cadastrar com código CNES`**

```python Cadastrar com código CNES
import requests

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

payload = {
    "resourceType": "Location",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/local/",
            "value": "HC-01",
            "use": "usual"
        },
        {
            "system": "https://cnes.datasus.gov.br/",
            "value": "2077485",
            "use": "official"
        }
    ],
    "name": "Hospital Central Acme",
    "address": {
        "line": ["Rua Tamandaré", "321"],
        "postalCode": "01503-001",
        "district": "Liberdade",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil"
    }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cadastrar com código CNES`**

```javascript Cadastrar com código CNES
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Location';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Location","identifier":[{"system":"https://www.acmesaude.com.br/integracao/local/","value":"HC-01","use":"usual"},{"system":"https://cnes.datasus.gov.br/","value":"2077485","use":"official"}],"name":"Hospital Central Acme","address":{"line":["Rua Tamandaré","321"],"postalCode":"01503-001","district":"Liberdade","city":"São Paulo","state":"SP","country":"Brasil"}}'
};

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

**`Cadastrar com código CNES`**

```go Cadastrar com código CNES
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    },\n    {\n      \"system\": \"https://cnes.datasus.gov.br/\",\n      \"value\": \"2077485\",\n      \"use\": \"official\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\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))

}
```

**`Cadastrar com código CNES`**

```ruby Cadastrar com código CNES
require 'uri'
require 'net/http'

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

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\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    },\n    {\n      \"system\": \"https://cnes.datasus.gov.br/\",\n      \"value\": \"2077485\",\n      \"use\": \"official\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\n  }\n}"

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

**`Cadastrar com código CNES`**

```java Cadastrar com código CNES
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/Location")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    },\n    {\n      \"system\": \"https://cnes.datasus.gov.br/\",\n      \"value\": \"2077485\",\n      \"use\": \"official\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\n  }\n}")
  .asString();
```

**`Cadastrar com código CNES`**

```php Cadastrar com código CNES
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Location', [
  'body' => '{
  "resourceType": "Location",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    },
    {
      "system": "https://cnes.datasus.gov.br/",
      "value": "2077485",
      "use": "official"
    }
  ],
  "name": "Hospital Central Acme",
  "address": {
    "line": [
      "Rua Tamandaré",
      "321"
    ],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cadastrar com código CNES`**

```csharp Cadastrar com código CNES
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Location");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"HC-01\",\n      \"use\": \"usual\"\n    },\n    {\n      \"system\": \"https://cnes.datasus.gov.br/\",\n      \"value\": \"2077485\",\n      \"use\": \"official\"\n    }\n  ],\n  \"name\": \"Hospital Central Acme\",\n  \"address\": {\n    \"line\": [\n      \"Rua Tamandaré\",\n      \"321\"\n    ],\n    \"postalCode\": \"01503-001\",\n    \"district\": \"Liberdade\",\n    \"city\": \"São Paulo\",\n    \"state\": \"SP\",\n    \"country\": \"Brasil\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cadastrar com código CNES`**

```swift Cadastrar com código CNES
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Location",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    ],
    [
      "system": "https://cnes.datasus.gov.br/",
      "value": "2077485",
      "use": "official"
    ]
  ],
  "name": "Hospital Central Acme",
  "address": [
    "line": ["Rua Tamandaré", "321"],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Location")! 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**
>
> **O código CNES é único no ambiente.** Enviar um CNES que já pertence a outro estabelecimento
> responde `409`, e nada é gravado. É o único `409` deste recurso.

> **Warning**
>
> **E há um segundo desfecho, pior que o `409`.** O CNES também serve para **reconhecer** o
> local: se a sua chave ainda não existe mas o CNES bate com um estabelecimento já cadastrado, a
> escrita não cria nada nem recusa — ela **atualiza aquele estabelecimento**, trocando o nome
> dele e agregando a sua chave. A chamada responde `200`, e você só descobre olhando o `id` que
> voltou.
>
> Trate o CNES como chave: não o reaproveite entre locais, e confira com um `GET` antes de
> cadastrar um estabelecimento cujo CNES você não tem certeza de que é novo.

### Sem endereço

`address` é opcional na criação, e um local sem endereço é um cadastro válido:

### Request

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

**`Cadastrar sem endereço`**

```curl Cadastrar sem endereço
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Location \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Location",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "AZS-01",
      "use": "usual"
    }
  ],
  "name": "Ambulatório Zona Sul"
}'
```

**`Cadastrar sem endereço`**

```python Cadastrar sem endereço
import requests

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

payload = {
    "resourceType": "Location",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/local/",
            "value": "AZS-01",
            "use": "usual"
        }
    ],
    "name": "Ambulatório Zona Sul"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cadastrar sem endereço`**

```javascript Cadastrar sem endereço
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Location';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Location","identifier":[{"system":"https://www.acmesaude.com.br/integracao/local/","value":"AZS-01","use":"usual"}],"name":"Ambulatório Zona Sul"}'
};

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

**`Cadastrar sem endereço`**

```go Cadastrar sem endereço
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"AZS-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Ambulatório Zona Sul\"\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 sem endereço`**

```ruby Cadastrar sem endereço
require 'uri'
require 'net/http'

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

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\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"AZS-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Ambulatório Zona Sul\"\n}"

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

**`Cadastrar sem endereço`**

```java Cadastrar sem endereço
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/Location")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Location\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/local/\",\n      \"value\": \"AZS-01\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Ambulatório Zona Sul\"\n}")
  .asString();
```

**`Cadastrar sem endereço`**

```php Cadastrar sem endereço
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

**`Cadastrar sem endereço`**

```csharp Cadastrar sem endereço
using RestSharp;

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

**`Cadastrar sem endereço`**

```swift Cadastrar sem endereço
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Location",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "AZS-01",
      "use": "usual"
    ]
  ],
  "name": "Ambulatório Zona Sul"
] as [String : Any]

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

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

## Buscar

### Request

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

**`Busca com resultados`**

```curl Busca com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/Location \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     -d address=Liberdade \
     --data-urlencode "address-city=São Paulo" \
     -d address-country=Brasil \
     -d address-postalcode=01503-001 \
     --data-urlencode "address-state=São Paulo" \
     --data-urlencode identifier=https://cnes.datasus.gov.br/|2077485 \
     -d name=Central
```

**`Busca com resultados`**

```python Busca com resultados
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","address":"Liberdade","address-city":"São Paulo","address-country":"Brasil","address-postalcode":"01503-001","address-state":"São Paulo","identifier":"https://cnes.datasus.gov.br/|2077485","name":"Central"}

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/Location?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&address=Liberdade&address-city=S%C3%A3o+Paulo&address-country=Brasil&address-postalcode=01503-001&address-state=S%C3%A3o+Paulo&identifier=https%3A%2F%2Fcnes.datasus.gov.br%2F%7C2077485&name=Central';
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/Location?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&address=Liberdade&address-city=S%C3%A3o+Paulo&address-country=Brasil&address-postalcode=01503-001&address-state=S%C3%A3o+Paulo&identifier=https%3A%2F%2Fcnes.datasus.gov.br%2F%7C2077485&name=Central"

	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/Location?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&address=Liberdade&address-city=S%C3%A3o+Paulo&address-country=Brasil&address-postalcode=01503-001&address-state=S%C3%A3o+Paulo&identifier=https%3A%2F%2Fcnes.datasus.gov.br%2F%7C2077485&name=Central")

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/Location?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&address=Liberdade&address-city=S%C3%A3o+Paulo&address-country=Brasil&address-postalcode=01503-001&address-state=S%C3%A3o+Paulo&identifier=https%3A%2F%2Fcnes.datasus.gov.br%2F%7C2077485&name=Central")
  .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/Location?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&address=Liberdade&address-city=S%C3%A3o+Paulo&address-country=Brasil&address-postalcode=01503-001&address-state=S%C3%A3o+Paulo&identifier=https%3A%2F%2Fcnes.datasus.gov.br%2F%7C2077485&name=Central', [
  '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/Location?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&address=Liberdade&address-city=S%C3%A3o+Paulo&address-country=Brasil&address-postalcode=01503-001&address-state=S%C3%A3o+Paulo&identifier=https%3A%2F%2Fcnes.datasus.gov.br%2F%7C2077485&name=Central");
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/Location?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&address=Liberdade&address-city=S%C3%A3o+Paulo&address-country=Brasil&address-postalcode=01503-001&address-state=S%C3%A3o+Paulo&identifier=https%3A%2F%2Fcnes.datasus.gov.br%2F%7C2077485&name=Central")! 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/Location/8b53f107-2d94-4c6e-a71f-9042e5b8c316",
      "resource": {
        "resourceType": "Location",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--health-facility",
            "value": "295",
            "use": "usual"
          },
          {
            "system": "https://cnes.datasus.gov.br/",
            "value": "2077485",
            "use": "official"
          },
          {
            "system": "https://www.acmesaude.com.br/integracao/local/",
            "value": "HC-01",
            "use": "usual"
          }
        ],
        "name": "Hospital Central Acme",
        "id": "8b53f107-2d94-4c6e-a71f-9042e5b8c316",
        "address": {
          "line": [
            "Rua Tamandaré",
            "321",
            "Casa 2"
          ],
          "postalCode": "01503-001",
          "district": "Liberdade",
          "city": "São Paulo",
          "state": "SP",
          "country": "Brasil",
          "text": "Rua Tamandaré, 321, Casa 2 - Liberdade, São Paulo/SP. 01503-001.",
          "use": "work",
          "type": "both"
        }
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Location/c1d09a4e-6b72-4f38-9de5-0a83b7f2c145",
      "resource": {
        "resourceType": "Location",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--health-facility",
            "value": "296",
            "use": "usual"
          }
        ],
        "name": "Ambulatório Zona Sul",
        "id": "c1d09a4e-6b72-4f38-9de5-0a83b7f2c145"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

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 do local, em `system\|value`. Aceita a sua chave, o identificador Nilo ou o código CNES | `Location.identifier`         |
| `name`               | [string](https://hl7.org/fhir/R4/search.html#string) | Parte do nome do estabelecimento                                                                      | `Location.name`               |
| `address`            | [string](https://hl7.org/fhir/R4/search.html#string) | Parte de qualquer campo do endereço                                                                   | `Location.address`            |
| `address-city`       | [string](https://hl7.org/fhir/R4/search.html#string) | Cidade                                                                                                | `Location.address.city`       |
| `address-state`      | [string](https://hl7.org/fhir/R4/search.html#string) | Estado, **na forma em que foi gravado** — quem cadastrou `SP` não é encontrado por `São Paulo`        | `Location.address.state`      |
| `address-postalcode` | [string](https://hl7.org/fhir/R4/search.html#string) | CEP                                                                                                   | `Location.address.postalCode` |
| `address-country`    | [string](https://hl7.org/fhir/R4/search.html#string) | País                                                                                                  | `Location.address.country`    |
| `address-use`        | [token](https://hl7.org/fhir/R4/search.html#token)   | Aceito, e inútil: todo endereço é `work`                                                              | `Location.address.use`        |
| `_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 `Location` existem e **não encontram nada** aqui, porque a
> Nilo não preenche o campo correspondente: `status`, `operational-status`, `type`, `near`,
> `organization`, `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 paginação é por `_count` e `_page_token`; havendo página seguinte, o `Bundle` traz a URL
pronta em `link`.

> **Note**
>
> Um estabelecimento antigo, que ninguém tenha tocado desde que a sua integração começou, pode
> não aparecer na lista. Se você espera um local e ele não vem, peça ao **Suporte**: a busca não
> é um inventário garantido do cadastro.

## Ler por ID

### Request

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

**`Local encontrado`**

```curl Local encontrado
curl https://landing-zone-api.nilo.services/fhir/resources/Location/id \
     -H "x-api-key: <apiKey>"
```

**`Local encontrado`**

```python Local encontrado
import requests

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

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

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

print(response.json())
```

**`Local encontrado`**

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

**`Local encontrado`**

```go Local encontrado
package main

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

func main() {

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

}
```

**`Local encontrado`**

```ruby Local encontrado
require 'uri'
require 'net/http'

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

**`Local encontrado`**

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

**`Local encontrado`**

```php Local encontrado
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

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

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

**`Local encontrado`**

```csharp Local encontrado
using RestSharp;

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

**`Local encontrado`**

```swift Local encontrado
import Foundation

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

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

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Location/8b53f107-2d94-4c6e-a71f-9042e5b8c316",
  "resource": {
    "resourceType": "Location",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--health-facility",
        "value": "295",
        "use": "usual"
      },
      {
        "system": "https://cnes.datasus.gov.br/",
        "value": "2077485",
        "use": "official"
      }
    ],
    "name": "Hospital Central Acme",
    "id": "8b53f107-2d94-4c6e-a71f-9042e5b8c316",
    "meta": {
      "lastUpdated": "2026-08-24T13:42:07.554000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "address": {
      "line": [
        "Rua Tamandaré",
        "321",
        "Casa 2"
      ],
      "postalCode": "01503-001",
      "district": "Liberdade",
      "city": "São Paulo",
      "state": "SP",
      "country": "Brasil",
      "text": "Rua Tamandaré, 321, Casa 2 - Liberdade, São Paulo/SP. 01503-001.",
      "use": "work",
      "type": "both"
    }
  },
  "search": {
    "mode": "match"
  }
}
```

## Onde o local é referenciado

O `Location` é o cadastro; quem o usa são os registros de cuidado.

| Recurso                                                    | Campo                  | Como o local entra                                                                                                                    |
| ---------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| [Hospitalização](/guia/recursos/encounter-hospitalization) | `location[0].location` | Por `display`, em texto livre — ou por `identifier` de um `Location` cadastrado, e aí o **nome** dele é copiado como texto            |
| [Pronto atendimento](/guia/recursos/encounter-emergency)   | `location[0].location` | Idem                                                                                                                                  |
| [Profissional](/guia/recursos/practitioner)                | `address[]`            | Cada endereço com `use: work` **cria um local novo** e o vincula ao profissional — é o que alimenta os **Locais de atendimento** dele |

> **Warning**
>
> **Não há vínculo vivo entre o evento e o local.** O que o evento guarda é o **nome** do local
> no momento da gravação, copiado como texto. Renomear ou mudar o endereço de um `Location`
> depois **não altera** o que ficou registrado no evento.

> **Warning**
>
> **Os dois caminhos de cadastro não se encontram.** O endereço `work` de um profissional
> **sempre cria um local novo** — não há como apontar para um `Location` já cadastrado a partir
> do profissional. Repetir o mesmo endereço em vários profissionais gera vários locais
> diferentes, todos com o mesmo endereço. Se o seu ambiente cadastra locais por aqui, evite
> mandar `address` com `use: work` no profissional.

## Valores devolvidos que você não enviou

> **Note**
>
> `address.use` é sempre `work` e `address.type` é sempre `both`. São constantes da leitura, não
> uma classificação do endereço — não há como registrar um endereço residencial ou postal aqui.

> **Note**
>
> `address.text` é o endereço montado numa linha só pela plataforma, para exibição. Enviá-lo não
> tem efeito, e o formato dele não é contrato: monte a sua própria exibição a partir dos campos.

## Efeitos colaterais

> **Warning**
>
> **Atualizar sem `address` apaga o endereço.** É o efeito de maior consequência deste recurso,
> e vale repetir aqui: o endereço não é preservado por omissão.

> **Note**
>
> Alterar um local **não altera nenhum evento já registrado**: os eventos guardam o nome do
> local como texto, e continuam com o nome antigo.

> **Note**
>
> Este endpoint nunca responde `204`: não há remoção de local 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. A
única exceção é o `409` do CNES duplicado.

| Status | `code`          | `expression`          | Mensagem                                                                                                     | Quando                                                                                    |
| ------ | --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `400`  | `required`      | `Location.identifier` | `Field is required`                                                                                          | O payload não tem `identifier`                                                            |
| `400`  | `business-rule` | `Location.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`                  |
| `400`  | `structure`     | —                     | `Resource has identifier from a Nilo environment that is not the current environment.`                       | O payload traz um identificador Nilo gerado em outro ambiente                             |
| `400`  | `structure`     | o campo recusado      | mensagem da validação FHIR                                                                                   | O payload não é um `Location` válido                                                      |
| `400`  | `exception`     | —                     | `HTTPBadRequest: …`                                                                                          | `address` sem `postalCode`, `name` ausente ou longo demais, número acima de 10 caracteres |
| `400`  | `exception`     | —                     | `TypeError: …`                                                                                               | `address` enviado sem `line`                                                              |
| `409`  | `conflict`      | —                     | `Resource conflicts with other existing resource(s)`, mais um `diagnostics`                                  | O código CNES já pertence a outro estabelecimento                                         |

### Response (200)

```json
{
  "resourceType": "Location",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/almanac-api--health-facility",
      "value": "295",
      "use": "usual"
    },
    {
      "system": "https://cnes.datasus.gov.br/",
      "value": "2077485",
      "use": "official"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/local/",
      "value": "HC-01",
      "use": "usual"
    }
  ],
  "name": "Hospital Central Acme",
  "id": "8b53f107-2d94-4c6e-a71f-9042e5b8c316",
  "meta": {
    "lastUpdated": "2026-08-24T13:42:07.554000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "address": {
    "line": [
      "Rua Tamandaré",
      "321",
      "Casa 2"
    ],
    "postalCode": "01503-001",
    "district": "Liberdade",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil",
    "text": "Rua Tamandaré, 321, Casa 2 - Liberdade, São Paulo/SP. 01503-001.",
    "use": "work",
    "type": "both"
  }
}
```

> **Warning**
>
> As linhas `exception` não são validações desta API — são falhas repassadas como estão. Elas
> saem **sem `expression`** e com uma mensagem de erro de linguagem, que inclui o endereço
> interno chamado. O mesmo vale para o `diagnostics` do `409`.
>
> **Nada disso é contrato:** não tente interpretar o texto, não o exiba para o usuário final e
> não o registre em log de longa duração. Trate `code: exception` como "payload recusado, motivo
> não classificado" e confira o `line`, o `postalCode` e o `name`.

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