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

# Grupo de pacientes

> Criar, renomear e apagar grupos de pacientes, no padrão FHIR Group.

Um **grupo de pacientes** é uma etiqueta de organização da carteira: *Gestantes de alto risco*,
*Pós-operatório*, *Piloto de telemedicina*. Todo paciente pertence a pelo menos um.

No FHIR o recurso é o [`Group`](https://hl7.org/fhir/R4/group.html), e ele é mínimo: guarda
**só o nome**.

> **Warning**
>
> **A participação dos pacientes não está aqui.** O `Group` do FHIR tem um campo `member[]`, e
> esta integração **não o usa** — nem na leitura, nem na escrita. Quem diz a que grupos um
> paciente pertence é o recurso do **paciente**.
>
> Para colocar ou tirar um paciente de um grupo, veja
> [Paciente](/guia/recursos/patient). Para listar os pacientes de um grupo, você precisa
> percorrer os pacientes: não há busca que faça o caminho inverso.

## Campos

| Campo          | Obrigatório | O que significa                                                            | No Nilo Care            |
| -------------- | ----------- | -------------------------------------------------------------------------- | ----------------------- |
| `resourceType` | **sim**     | Constante `Group`                                                          | —                       |
| `identifier`   | **sim**     | Suas chaves do grupo. É por elas que a API decide entre criar e atualizar  | —                       |
| `name`         | **sim**     | Nome do grupo. É **único por prestador**, comparado sem caixa e sem acento | **Grupos de pacientes** |
| `active`       | não         | Na escrita, `false` **apaga o grupo**. Na leitura, constante `true`        | —                       |
| `actual`       | não         | Só resposta: constante `true`                                              | —                       |
| `type`         | não         | Só resposta: constante `person`                                            | —                       |
| `id` · `meta`  | não         | Só resposta: identificador Nilo FHIR e metadados da gravação               | —                       |

> **Note**
>
> A leitura devolve **dois** identificadores Nilo para o mesmo grupo, nos `system`
> `…/NamingSystem/sorting-hat-api--cohort` e `…/NamingSystem/care-api--cohort`, com o mesmo
> `value`. O segundo é preservado por compatibilidade; os dois funcionam na busca e nas
> referências.

### Campos que a Nilo não usa

O `Group` canônico traz `code`, `quantity`, `managingEntity`, `characteristic` e — o mais
importante — **`member[]`**. Nenhum deles é lido.

> **Note**
>
> A referência lista só os campos **suportados**, não os permitidos: a API não recusa quem manda
> os outros, e eles ficam guardados no recurso, voltando nas leituras seguintes sem nunca terem
> significado nada. Um `member[]` enviado assim parece a lista de pacientes do grupo, e não é.

## Criar ou renomear

### Request

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

**`Criar um grupo`**

```curl Criar um grupo
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Group \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Group",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes de alto risco"
}'
```

**`Criar um grupo`**

```python Criar um grupo
import requests

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

payload = {
    "resourceType": "Group",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/grupo/",
            "value": "GR-500",
            "use": "usual"
        }
    ],
    "name": "Gestantes de alto risco"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Criar um grupo`**

```javascript Criar um grupo
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Group';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Group","identifier":[{"system":"https://www.acmesaude.com.br/integracao/grupo/","value":"GR-500","use":"usual"}],"name":"Gestantes de alto risco"}'
};

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

**`Criar um grupo`**

```go Criar um grupo
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes de alto risco\"\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))

}
```

**`Criar um grupo`**

```ruby Criar um grupo
require 'uri'
require 'net/http'

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

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\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes de alto risco\"\n}"

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

**`Criar um grupo`**

```java Criar um grupo
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/Group")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes de alto risco\"\n}")
  .asString();
```

**`Criar um grupo`**

```php Criar um grupo
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Group', [
  'body' => '{
  "resourceType": "Group",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes de alto risco"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Criar um grupo`**

```csharp Criar um grupo
using RestSharp;

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

**`Criar um grupo`**

```swift Criar um grupo
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Group",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    ]
  ],
  "name": "Gestantes de alto risco"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Group")! 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": "Group",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--cohort",
      "value": "1042",
      "use": "usual"
    },
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--cohort",
      "value": "1042",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes de alto risco",
  "id": "6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
  "meta": {
    "lastUpdated": "2026-02-19T13:44:07.615000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "active": true,
  "actual": true,
  "type": "person"
}
```

Guarde o `id`: é por ele que se faz a leitura direta.

O mesmo `POST` cria e renomeia. Reenviando um `identifier` que já corresponde a um grupo, ele é
renomeado — e os pacientes dele não são afetados.

### Request

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

**`Renomear um grupo`**

```curl Renomear um grupo
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Group \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Group",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes — acompanhamento intensivo"
}'
```

**`Renomear um grupo`**

```python Renomear um grupo
import requests

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

payload = {
    "resourceType": "Group",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/grupo/",
            "value": "GR-500",
            "use": "usual"
        }
    ],
    "name": "Gestantes — acompanhamento intensivo"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Renomear um grupo`**

```javascript Renomear um grupo
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Group';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Group","identifier":[{"system":"https://www.acmesaude.com.br/integracao/grupo/","value":"GR-500","use":"usual"}],"name":"Gestantes — acompanhamento intensivo"}'
};

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

**`Renomear um grupo`**

```go Renomear um grupo
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes — acompanhamento intensivo\"\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 um grupo`**

```ruby Renomear um grupo
require 'uri'
require 'net/http'

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

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\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes — acompanhamento intensivo\"\n}"

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

**`Renomear um grupo`**

```java Renomear um grupo
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/Group")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes — acompanhamento intensivo\"\n}")
  .asString();
```

**`Renomear um grupo`**

```php Renomear um grupo
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Group', [
  'body' => '{
  "resourceType": "Group",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes — acompanhamento intensivo"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Renomear um grupo`**

```csharp Renomear um grupo
using RestSharp;

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

**`Renomear um grupo`**

```swift Renomear um grupo
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Group",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    ]
  ],
  "name": "Gestantes — acompanhamento intensivo"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Group")! 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 nome é único por prestador**, e a comparação **ignora caixa e acento**: `São João`,
> `Sao Joao` e `são joão` são o mesmo nome. Criar um grupo com um nome que já existe responde
> `409`, e renomear para um nome já usado também. É o único `409` deste recurso.

> **Note**
>
> Dentro de uma [carga em lote](https://hl7.org/fhir/R4/http.html#transaction), o conflito é
> reportado no `response.status` daquela entrada, como `409`, **sem interromper** o processamento
> das demais.

## Apagar um grupo

Enviar `active: false` **apaga** o grupo. A resposta é `204`, sem corpo.

### Request

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

**`Apagar um grupo`**

```curl Apagar um grupo
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Group \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "Group",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes de alto risco",
  "active": false
}'
```

**`Apagar um grupo`**

```python Apagar um grupo
import requests

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

payload = {
    "resourceType": "Group",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/grupo/",
            "value": "GR-500",
            "use": "usual"
        }
    ],
    "name": "Gestantes de alto risco",
    "active": False
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Apagar um grupo`**

```javascript Apagar um grupo
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Group';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"Group","identifier":[{"system":"https://www.acmesaude.com.br/integracao/grupo/","value":"GR-500","use":"usual"}],"name":"Gestantes de alto risco","active":false}'
};

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

**`Apagar um grupo`**

```go Apagar um grupo
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes de alto risco\",\n  \"active\": false\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))

}
```

**`Apagar um grupo`**

```ruby Apagar um grupo
require 'uri'
require 'net/http'

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

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\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes de alto risco\",\n  \"active\": false\n}"

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

**`Apagar um grupo`**

```java Apagar um grupo
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/Group")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes de alto risco\",\n  \"active\": false\n}")
  .asString();
```

**`Apagar um grupo`**

```php Apagar um grupo
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Group', [
  'body' => '{
  "resourceType": "Group",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes de alto risco",
  "active": false
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Apagar um grupo`**

```csharp Apagar um grupo
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Group");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"Group\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/grupo/\",\n      \"value\": \"GR-500\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Gestantes de alto risco\",\n  \"active\": false\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Apagar um grupo`**

```swift Apagar um grupo
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "Group",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    ]
  ],
  "name": "Gestantes de alto risco",
  "active": false
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Group")! 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 é uma desativação: é uma remoção.** O grupo deixa de existir, e o `id` que você já leu
> passa a responder `404`. Não há como reativá-lo — só criar outro.

> **Warning**
>
> **Um grupo com pacientes não pode ser apagado.** A chamada é recusada com
> `The Group cannot be deactivated as it contains patients.` Tire os pacientes do grupo antes —
> o que se faz pelo recurso de cada [paciente](/guia/recursos/patient), não por aqui.

> **Note**
>
> Criar um grupo já com `active: false` também é recusado: não faz sentido nascer apagado.

> **Note**
>
> Este é um dos poucos endpoints da API que respondem `204`. Um `POST` de grupo que devolve `204`
> em vez de `200` significa que o grupo foi apagado, não que a chamada falhou.

> **Warning**
>
> **Não reenvie o `id` que veio de uma leitura.** Com `id` no corpo, a resposta do apagamento é
> `200` com o recurso, não `204` — e é fácil concluir que nada aconteceu. Monte o payload de
> apagamento com `identifier`, `name` e `active: false`, só.

## Buscar

### Request

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

**`Busca com resultados`**

```curl Busca com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/Group \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     -d actual=true \
     --data-urlencode identifier=https://www.acmesaude.com.br/integracao/grupo/|GR-500 \
     -d type=person
```

**`Busca com resultados`**

```python Busca com resultados
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","actual":"true","identifier":"https://www.acmesaude.com.br/integracao/grupo/|GR-500","type":"person"}

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/Group?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&actual=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fgrupo%2F%7CGR-500&type=person';
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/Group?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&actual=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fgrupo%2F%7CGR-500&type=person"

	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/Group?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&actual=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fgrupo%2F%7CGR-500&type=person")

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/Group?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&actual=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fgrupo%2F%7CGR-500&type=person")
  .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/Group?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&actual=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fgrupo%2F%7CGR-500&type=person', [
  '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/Group?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&actual=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fgrupo%2F%7CGR-500&type=person");
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/Group?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&actual=true&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fgrupo%2F%7CGR-500&type=person")! 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/Group/6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
      "resource": {
        "resourceType": "Group",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--cohort",
            "value": "1042",
            "use": "usual"
          },
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--cohort",
            "value": "1042",
            "use": "usual"
          },
          {
            "system": "https://www.acmesaude.com.br/integracao/grupo/",
            "value": "GR-500",
            "use": "usual"
          }
        ],
        "name": "Gestantes de alto risco",
        "id": "6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
        "meta": {
          "lastUpdated": "2026-02-19T13:44:07.615000Z",
          "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
        },
        "active": true,
        "actual": true,
        "type": "person"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

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

### Response (200)

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

### Parâmetros de busca suportados

| Nome           | Tipo                                               | Descrição                                                          | Expressão          |
| -------------- | -------------------------------------------------- | ------------------------------------------------------------------ | ------------------ |
| `identifier`   | [token](https://hl7.org/fhir/R4/search.html#token) | Identificador do grupo, em `system\|value`                         | `Group.identifier` |
| `type`         | [token](https://hl7.org/fhir/R4/search.html#token) | Aceito, e inútil: todo grupo é `person`                            | `Group.type`       |
| `actual`       | [token](https://hl7.org/fhir/R4/search.html#token) | Aceito, e inútil: todo grupo é `true`                              | `Group.actual`     |
| `_lastUpdated` | [date](https://hl7.org/fhir/R4/search.html#date)   | Data da última gravação no store, com os prefixos `eq`, `ge`, `le` | —                  |

> **Warning**
>
> **Não há busca por nome.** O `Group` do FHIR R4 não define parâmetro de busca sobre `name` — e
> como o `name` é o único dado do recurso, a busca útil é listar tudo e filtrar do seu lado. São
> listas curtas.

> **Note**
>
> Os demais parâmetros canônicos do `Group` existem e **não encontram nada**, porque a plataforma
> não preenche o campo correspondente: `code`, `member`, `managing-entity`,
> `characteristic`, `value`, `exclude` e `characteristic-value`.
>
> Repare em **`member`**: não há como perguntar "quais grupos este paciente tem" pelo `Group`. A
> resposta está no recurso do [paciente](/guia/recursos/patient).

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

## Ler por ID

### Request

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

**`Grupo encontrado`**

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

**`Grupo encontrado`**

```python Grupo encontrado
import requests

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

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

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

print(response.json())
```

**`Grupo encontrado`**

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

**`Grupo encontrado`**

```go Grupo encontrado
package main

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

func main() {

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

}
```

**`Grupo encontrado`**

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

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

**`Grupo encontrado`**

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

**`Grupo encontrado`**

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

$client = new \GuzzleHttp\Client();

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

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

**`Grupo encontrado`**

```csharp Grupo encontrado
using RestSharp;

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

**`Grupo encontrado`**

```swift Grupo encontrado
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Group/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 grupo está em
> `resource`.

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Group/6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
  "resource": {
    "resourceType": "Group",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--cohort",
        "value": "1042",
        "use": "usual"
      },
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--cohort",
        "value": "1042",
        "use": "usual"
      }
    ],
    "name": "Gestantes de alto risco",
    "id": "6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
    "meta": {
      "lastUpdated": "2026-02-19T13:44:07.615000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "active": true,
    "actual": true,
    "type": "person"
  },
  "search": {
    "mode": "match"
  }
}
```

## Efeitos colaterais

> **Note**
>
> Criar um grupo **não coloca ninguém nele**. O grupo nasce vazio, e os pacientes entram quando o
> recurso deles o referencia.

> **Note**
>
> Renomear um grupo **não afeta os pacientes**: eles continuam nele, e passam a ver o nome novo.

## Erros

Recusa é `400`, com uma exceção: o `409` do nome repetido. O corpo é um `OperationOutcome`.

| Status | `code`          | `expression`       | Mensagem                                                                                                     | Quando                                                                        |
| ------ | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `400`  | `required`      | `Group.identifier` | `Field is required`                                                                                          | O payload não tem `identifier`                                                |
| `400`  | `business-rule` | `Group.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                                        |
| `400`  | `business-rule` | —                  | `The Group cannot be deactivated as it contains patients.`                                                   | `active: false` num grupo que ainda tem pacientes                             |
| `400`  | `business-rule` | `Group.active`     | `The cohort cannot be created with active False.`                                                            | Grupo novo criado com `active: false`                                         |
| `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`  | `exception`     | —                  | mensagem da plataforma                                                                                       | O `name` está ausente — esta API não o valida, e a recusa vem crua do serviço |
| `409`  | `conflict`      | `Group.name`       | `A cohort named '…' already exists for this care provider.`                                                  | Já existe um grupo com esse nome                                              |

### Response (200)

```json
{
  "resourceType": "Group",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--cohort",
      "value": "1042",
      "use": "usual"
    },
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--cohort",
      "value": "1042",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/grupo/",
      "value": "GR-500",
      "use": "usual"
    }
  ],
  "name": "Gestantes de alto risco",
  "id": "6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
  "meta": {
    "lastUpdated": "2026-02-19T13:44:07.615000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "active": true,
  "actual": true,
  "type": "person"
}
```

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