Grupo de pacientes | Nilo Saúde · Interoperabilidade FHIR

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, e ele é mínimo: guarda só o nome.

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

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.

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

POST

/fhir/resources/Group

1 curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Group \
2      -H "x-api-key: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "resourceType": "Group",
6   "identifier": [
7     {
8       "system": "https://www.acmesaude.com.br/integracao/grupo/",
9       "value": "GR-500",
10       "use": "usual"
11     }
12   ],
13   "name": "Gestantes de alto risco"
14 }'

Try it

A resposta é o recurso gravado, sem envelope:

Response

1 {
2   "resourceType": "Group",
3   "identifier": [
4     {
5       "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--cohort",
6       "value": "1042",
7       "use": "usual"
8     },
9     {
10       "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--cohort",
11       "value": "1042",
12       "use": "usual"
13     },
14     {
15       "system": "https://www.acmesaude.com.br/integracao/grupo/",
16       "value": "GR-500",
17       "use": "usual"
18     }
19   ],
20   "name": "Gestantes de alto risco",
21   "id": "6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
22   "meta": {
23     "lastUpdated": "2026-02-19T13:44:07.615000Z",
24     "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
25   },
26   "active": true,
27   "actual": true,
28   "type": "person"
29 }

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.

POST

/fhir/resources/Group

1 curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Group \
2      -H "x-api-key: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "resourceType": "Group",
6   "identifier": [
7     {
8       "system": "https://www.acmesaude.com.br/integracao/grupo/",
9       "value": "GR-500",
10       "use": "usual"
11     }
12   ],
13   "name": "Gestantes — acompanhamento intensivo"
14 }'

Try it

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.

Dentro de uma carga em lote, 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.

POST

/fhir/resources/Group

1 curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Group \
2      -H "x-api-key: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "resourceType": "Group",
6   "identifier": [
7     {
8       "system": "https://www.acmesaude.com.br/integracao/grupo/",
9       "value": "GR-500",
10       "use": "usual"
11     }
12   ],
13   "name": "Gestantes de alto risco",
14   "active": false
15 }'

Try it

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.

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, não por aqui.

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

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.

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

GET

/fhir/resources/Group

1 curl -G https://landing-zone-api.nilo.services/fhir/resources/Group \
2      -H "x-api-key: <apiKey>" \
3      -d _count=50 \
4      -d _lastUpdated=eq2013-01-14 \
5      --data-urlencode _page_token=Cjj3YopYuf%2F%2F%2F%2F%2BABd%2BbgE0m...dSANQAFoLCUSM7w9VYUqaEANglLWUugQ%3D \
6      -d actual=true \
7      --data-urlencode identifier=https://www.acmesaude.com.br/integracao/grupo/|GR-500 \
8      -d type=person

Try it

A resposta é sempre um Bundle do tipo searchset:

Response

1 {
2   "resourceType": "Bundle",
3   "type": "searchset",
4   "entry": [
5     {
6       "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Group/6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
7       "resource": {
8         "resourceType": "Group",
9         "identifier": [
10           {
11             "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--cohort",
12             "value": "1042",
13             "use": "usual"
14           },
15           {
16             "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--cohort",
17             "value": "1042",
18             "use": "usual"
19           },
20           {
21             "system": "https://www.acmesaude.com.br/integracao/grupo/",
22             "value": "GR-500",
23             "use": "usual"
24           }
25         ],
26         "name": "Gestantes de alto risco",
27         "id": "6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
28         "meta": {
29           "lastUpdated": "2026-02-19T13:44:07.615000Z",
30           "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
31         },
32         "active": true,
33         "actual": true,
34         "type": "person"
35       },
36       "search": {
37         "mode": "match"
38       }
39     }
40   ],
41   "link": []
42 }

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

Response

1 {
2   "resourceType": "Bundle",
3   "type": "searchset",
4   "entry": [],
5   "link": []
6 }

Parâmetros de busca suportados

Nome	Tipo	Descrição	Expressão
`identifier`	token	Identificador do grupo, em `system\|value`	`Group.identifier`
`type`	token	Aceito, e inútil: todo grupo é `person`	`Group.type`
`actual`	token	Aceito, e inútil: todo grupo é `true`	`Group.actual`
`_lastUpdated`	date	Data da última gravação no store, com os prefixos `eq`, `ge`, `le`	—

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.

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.

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

Ler por ID

GET

/fhir/resources/Group/:id

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

Try it

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

1 {
2   "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Group/6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
3   "resource": {
4     "resourceType": "Group",
5     "identifier": [
6       {
7         "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/sorting-hat-api--cohort",
8         "value": "1042",
9         "use": "usual"
10       },
11       {
12         "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--cohort",
13         "value": "1042",
14         "use": "usual"
15       }
16     ],
17     "name": "Gestantes de alto risco",
18     "id": "6b41e097-2c58-4a3d-91f0-7e25c48b0a63",
19     "meta": {
20       "lastUpdated": "2026-02-19T13:44:07.615000Z",
21       "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
22     },
23     "active": true,
24     "actual": true,
25     "type": "person"
26   },
27   "search": {
28     "mode": "match"
29   }
30 }

Efeitos colaterais

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

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

1 {
2   "issue": [
3     {
4       "code": "business-rule",
5       "details": {
6         "text": "The Group cannot be deactivated as it contains patients."
7       },
8       "severity": "error"
9     }
10   ],
11   "resourceType": "OperationOutcome"
12 }

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