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

# Diretriz aplicada

> Aplicar uma diretriz a um paciente e acompanhar essa diretriz aplicada, uma por paciente e diretriz, no padrão FHIR CarePlan.

Uma **diretriz** é o desenho do cuidado: a sequência de consultas, tarefas, questionários e
mensagens que a equipe deve executar para acompanhar um paciente. A **diretriz aplicada** é uma
diretriz posta em prática para **um** paciente — o par paciente × diretriz, que liga uma pessoa
a um roteiro de acompanhamento. Um paciente em três diretrizes tem três diretrizes aplicadas,
uma para cada.

No FHIR, a diretriz é um [`PlanDefinition`](https://hl7.org/fhir/R4/plandefinition.html) e a
aplicação dela é um [`CarePlan`](https://hl7.org/fhir/R4/careplan.html). Esta página cobre a
segunda metade: como colocar um paciente numa diretriz, como acompanhar o que foi gerado para
ele e como encerrar o acompanhamento.

> **Note**
>
> O **conteúdo** da diretriz — as consultas, tarefas e questionários que ela gera — é montado
> pela equipe no NiloCare, não por esta API. O que você faz aqui é aplicá-la, e para isso precisa
> da URL da diretriz, que a [busca de diretrizes](#encontrar-a-diretriz) devolve. O cabeçalho da
> diretriz (nome, descrição e tipo) esse sim é gravável — veja
> [Diretriz](/guia/recursos/plandefinition).

## Linha de cuidado e protocolo

A plataforma organiza as diretrizes em dois tipos:

| Tipo                 | Como a equipe o usa                                       | Exemplo                       |
| -------------------- | --------------------------------------------------------- | ----------------------------- |
| **Linha de cuidado** | Acompanhamento contínuo de uma condição crônica           | Diabetes, hipertensão         |
| **Protocolo**        | Um roteiro com começo, meio e fim, de tarefas sequenciais | Acompanhamento pós-operatório |

O tipo vem na leitura em `category[0].text`, com os códigos `care_line` e `protocol`. Não é
algo que você escolha no payload deste recurso: ele é propriedade da diretriz — veja
[Diretriz](/guia/recursos/plandefinition).

## Antes de aplicar

A aplicação de uma diretriz não depende só da diretriz aplicada — depende de como o paciente está
cadastrado. Dois requisitos, os dois verificados pela plataforma no momento da aplicação:

1. **O paciente tem equipe de cuidado.** Um paciente sem equipe é recusado.
2. **A equipe cobre as especialidades que a diretriz exige.** Precisa haver ao menos um
   profissional para cada especialidade pedida — pode ser o mesmo profissional cobrindo mais
   de uma. Faltando alguma, a aplicação é bloqueada.

> **Warning**
>
> Os dois erros vêm da plataforma, não da validação do recurso: saem com `expression` igual a
> `CarePlan.?` e com o motivo em texto (`patient_without_care_team`,
> `todo_without_responsible`). `CarePlan.?` **não é FHIRPath válido** — não tente resolvê-lo
> automaticamente para apontar o campo culpado.

## Campos

A coluna **No NiloCare** 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 NiloCare                          |
| ----------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `resourceType`          | **sim**                                | Constante `CarePlan`                                                                                                  | —                                    |
| `status`                | **sim**                                | Na escrita, escolhe o que acontece — veja [Aplicar](#aplicar-a-diretriz). Na leitura, a situação da diretriz aplicada | selo **Encerrada** na diretriz       |
| `intent`                | **sim**                                | Exigido pelo FHIR R4 e não lido pela Nilo. Envie `order`                                                              | —                                    |
| `subject`               | **sim**                                | O paciente, por um identificador dele. `type` tem de ser `Patient`                                                    | **Paciente**                         |
| `instantiatesCanonical` | **sim**                                | A diretriz a aplicar, pela URL do `PlanDefinition`. Só o primeiro item é lido                                         | **Diretriz**                         |
| `identifier`            | não pela validação, **sim na prática** | Suas chaves da diretriz aplicada. É por aqui que a API reconhece uma diretriz aplicada já existente                   | —                                    |
| `title`                 | não                                    | Só resposta: nome da diretriz                                                                                         | **Diretriz**                         |
| `description`           | não                                    | Só resposta: descrição da diretriz                                                                                    | —                                    |
| `category`              | não                                    | Só resposta: `care_line` ou `protocol`, em texto livre                                                                | **Linha de cuidado** / **Protocolo** |
| `period`                | não                                    | Só resposta: início e fim da aplicação ao paciente                                                                    | **Início da diretriz**               |
| `created`               | não                                    | Só resposta: data de criação da diretriz aplicada, sem hora                                                           | —                                    |
| `activity`              | não                                    | Só resposta: os itens gerados pela diretriz                                                                           | itens do plano                       |
| `note`                  | não                                    | Só resposta, e só quando a alocação em massa falhou: o motivo da falha                                                | —                                    |
| `id` · `meta`           | não                                    | Só resposta: identificador Nilo FHIR e metadados da gravação                                                          | —                                    |

### Campos que a Nilo não usa

A `CarePlan` canônica traz muito mais do que esta integração lê: `basedOn`, `replaces`,
`partOf`, `encounter`, `careTeam`, `addresses`, `goal`, `contributor`, `supportingInfo`,
`instantiatesUri`, `partOf` e `contained`. Nenhum deles é lido, e por isso nenhum aparece na
referência do recurso.

> **Warning**
>
> **`author` é a exceção que morde.** Ele não grava nada — nem o profissional que aplicou a
> diretriz — mas, ao contrário dos outros, **é validado**. O `type` é conferido em toda escrita:
> qualquer coisa diferente de `Practitioner` recusa a chamada. E, nas chamadas que **criam** ou
> recriam a diretriz aplicada, o identificador também é resolvido: um profissional inexistente ou
> inativo recusa a escrita inteira. Num encerramento ou cancelamento o identificador nem chega a
> ser consultado.
>
> Como não há benefício algum em enviá-lo, não envie. Ele não aparece na referência do recurso
> justamente por isso; as linhas de erro abaixo existem para quem já o manda hoje.

## Encontrar a diretriz

`instantiatesCanonical` é a URL da diretriz. Você a obtém listando as diretrizes disponíveis
— veja [Diretriz](/guia/recursos/plandefinition):

### Request

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

**`Busca com resultados`**

```curl Busca com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     --data-urlencode identifier=https://www.acmesaude.com.br/integracao/diretriz/|DM2 \
     -d name=Acompanhamento \
     -d status=active \
     --data-urlencode type=http://terminology.hl7.org/CodeSystem/plan-definition-type|order-set \
     --data-urlencode url=https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2
```

**`Busca com resultados`**

```python Busca com resultados
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","identifier":"https://www.acmesaude.com.br/integracao/diretriz/|DM2","name":"Acompanhamento","status":"active","type":"http://terminology.hl7.org/CodeSystem/plan-definition-type|order-set","url":"https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2"}

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/PlanDefinition?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fdiretriz%2F%7CDM2&name=Acompanhamento&status=active&type=http%3A%2F%2Fterminology.hl7.org%2FCodeSystem%2Fplan-definition-type%7Corder-set&url=https%3A%2F%2Fwww.acmesaude.com.br%2Fdiretrizes%2Fdiabetes-tipo-2';
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/PlanDefinition?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fdiretriz%2F%7CDM2&name=Acompanhamento&status=active&type=http%3A%2F%2Fterminology.hl7.org%2FCodeSystem%2Fplan-definition-type%7Corder-set&url=https%3A%2F%2Fwww.acmesaude.com.br%2Fdiretrizes%2Fdiabetes-tipo-2"

	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/PlanDefinition?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fdiretriz%2F%7CDM2&name=Acompanhamento&status=active&type=http%3A%2F%2Fterminology.hl7.org%2FCodeSystem%2Fplan-definition-type%7Corder-set&url=https%3A%2F%2Fwww.acmesaude.com.br%2Fdiretrizes%2Fdiabetes-tipo-2")

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/PlanDefinition?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fdiretriz%2F%7CDM2&name=Acompanhamento&status=active&type=http%3A%2F%2Fterminology.hl7.org%2FCodeSystem%2Fplan-definition-type%7Corder-set&url=https%3A%2F%2Fwww.acmesaude.com.br%2Fdiretrizes%2Fdiabetes-tipo-2")
  .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/PlanDefinition?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fdiretriz%2F%7CDM2&name=Acompanhamento&status=active&type=http%3A%2F%2Fterminology.hl7.org%2FCodeSystem%2Fplan-definition-type%7Corder-set&url=https%3A%2F%2Fwww.acmesaude.com.br%2Fdiretrizes%2Fdiabetes-tipo-2', [
  '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/PlanDefinition?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fdiretriz%2F%7CDM2&name=Acompanhamento&status=active&type=http%3A%2F%2Fterminology.hl7.org%2FCodeSystem%2Fplan-definition-type%7Corder-set&url=https%3A%2F%2Fwww.acmesaude.com.br%2Fdiretrizes%2Fdiabetes-tipo-2");
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/PlanDefinition?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fdiretriz%2F%7CDM2&name=Acompanhamento&status=active&type=http%3A%2F%2Fterminology.hl7.org%2FCodeSystem%2Fplan-definition-type%7Corder-set&url=https%3A%2F%2Fwww.acmesaude.com.br%2Fdiretrizes%2Fdiabetes-tipo-2")! 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 URL a enviar é `{host}/fhir/resources/PlanDefinition/{id}`, com o `id` do recurso
encontrado — ou a `url` canônica da diretriz, quando ela tiver uma.

> **Note**
>
> A resolução aceita duas formas: a API tenta primeiro o **último segmento da URL** como `id` do
> recurso e, não achando, procura uma diretriz cujo campo `url` seja exatamente o que você
> enviou. Nos dois caminhos a diretriz precisa estar com `status: active`.

> **Warning**
>
> A URL embute o **host do ambiente**. Um payload com a URL de produção enviado para o ambiente
> de homologação é recusado antes de qualquer validação de negócio, com a mensagem
> `Resource has identifier from a Nilo environment that is not the current environment.` Ao
> promover uma integração entre ambientes, troque o host de todos os `instantiatesCanonical`.

## Aplicar a diretriz

Não há endpoint separado para criar e atualizar: o mesmo `POST` faz os dois, e o `status`
enviado é o que decide o que acontece.

### Os dois modos de aplicação

| `status` | O que acontece                                                                                                                                                              |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `draft`  | **Fila de alocação.** O paciente entra na fila e a plataforma avalia a capacidade da equipe antes de aplicar. Nesta chamada nada é criado na plataforma — só o recurso FHIR |
| `active` | **Aplicação imediata.** A diretriz aplicada é criada durante a requisição, sem passar pela fila                                                                             |

### Request

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

**`Aplicação imediata`**

```curl Aplicação imediata
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/CarePlan \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "active",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    }
  ]
}'
```

**`Aplicação imediata`**

```python Aplicação imediata
import requests

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

payload = {
    "instantiatesCanonical": ["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],
    "intent": "order",
    "resourceType": "CarePlan",
    "status": "active",
    "subject": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    },
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
            "value": "349223",
            "use": "usual"
        }
    ]
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Aplicação imediata`**

```javascript Aplicação imediata
const url = 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"instantiatesCanonical":["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],"intent":"order","resourceType":"CarePlan","status":"active","subject":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"},"identifier":[{"system":"https://www.acmesaude.com.br/integracao/plano-de-cuidado/","value":"349223","use":"usual"}]}'
};

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

**`Aplicação imediata`**

```go Aplicação imediata
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"active\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\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))

}
```

**`Aplicação imediata`**

```ruby Aplicação imediata
require 'uri'
require 'net/http'

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

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  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"active\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\n  ]\n}"

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

**`Aplicação imediata`**

```java Aplicação imediata
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/CarePlan")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"active\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\n  ]\n}")
  .asString();
```

**`Aplicação imediata`**

```php Aplicação imediata
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan', [
  'body' => '{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "active",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Aplicação imediata`**

```csharp Aplicação imediata
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/CarePlan");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"active\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Aplicação imediata`**

```swift Aplicação imediata
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "instantiatesCanonical": ["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "active",
  "subject": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ],
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    ]
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/CarePlan")! 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 devolve o recurso como ficou gravado, sem envelope:

### Response (200)

```json
{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "active",
  "subject": {
    "identifier": {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient",
      "value": "1013441",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "category": [
    {
      "text": "care_line"
    }
  ],
  "created": "2026-04-16",
  "description": "Acompanhamento longitudinal de pacientes com diabetes tipo 2.",
  "id": "3f21a0d5-9c74-4b18-a6e2-51d8c93f7ab0",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    },
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-care-line",
      "value": "184532",
      "use": "usual"
    }
  ],
  "meta": {
    "lastUpdated": "2026-04-16T20:05:03.118000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "period": {
    "start": "2026-04-16"
  },
  "title": "Diabetes tipo 2"
}
```

Guarde o `id`: é por ele que se faz a leitura direta. Ao lado do seu `identifier`, a resposta
traz o identificador Nilo da diretriz aplicada, no `system`
`…/NamingSystem/hippocrates-api--patient-care-line`.

> **Note**
>
> **A aplicação imediata confirma a criação da diretriz aplicada, não a geração dos itens.** As
> tarefas, os agendamentos, os questionários e as mensagens são gerados depois, de forma
> assíncrona, e a geração pode levar alguns minutos.

> **Warning**
>
> O `status` da resposta **repete o que você enviou**, não o estado derivado da diretriz aplicada
> na plataforma. Uma aplicação imediata responde `active` mesmo enquanto os itens ainda estão
> sendo gerados — nesse intervalo a diretriz aplicada vale como pendente do outro lado, e uma
> leitura posterior pode trazê-la como `on-hold`, sem `activity`. O sinal de que a geração
> terminou é a `activity` aparecer numa leitura, não o `status` da resposta ao `POST`.

> **Warning**
>
> Uma diretriz aplicada criada com `status: draft` **não tem identificador Nilo**: nada foi criado na
> plataforma ainda. O recurso FHIR é o seu próprio payload, sem `title`, sem `category`, sem
> `period` e sem `activity`. Não conte com esses campos antes de a alocação acontecer — e veja
> o que isso implica para [cancelar uma diretriz aplicada ainda na fila](#encerrar-ou-cancelar).

> **Note**
>
> `subject.identifier` **volta trocado**. Você envia o identificador do seu sistema, e a
> resposta traz o identificador Nilo do paciente
> (`…/NamingSystem/hippocrates-api--patient`). Não é perda de dado: é a referência que a
> plataforma usa internamente. Leituras posteriores da mesma diretriz aplicada podem trazer o seu
> identificador de volta, dependendo da configuração da sua implantação.

### Como a API reconhece o plano

Duas chaves, nesta ordem.

**Com `identifier`.** A API procura uma diretriz aplicada com aquele par `system` + `value`, em
qualquer estado. Achando, a chamada é uma **atualização** daquela diretriz aplicada, e valem as
regras de [transição de estado](#estados-e-transições).

**Sem `identifier`, ou com um `identifier` que não casa com nada.** A API procura pelo par
`subject` + `instantiatesCanonical`, entre as diretrizes aplicadas nos estados `draft`,
`active`, `on-hold` e `entered-in-error` — as já encerradas ou canceladas não entram nessa
busca.

O que acontece então depende de qual das duas situações é a sua:

| Você enviou                         | Não há diretriz aplicada para o par                                  | Há diretriz aplicada `draft` ou `entered-in-error`      | Há diretriz aplicada `active` ou `on-hold`                                            |
| ----------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `identifier` novo, `status: active` | Cria a diretriz aplicada                                             | **Aplica agora** a diretriz aplicada que estava na fila | O seu `identifier` é **anexado** à diretriz aplicada existente, e ela volta como está |
| `identifier` novo, `status: draft`  | Enfileira                                                            | `identifier` anexado; nada muda                         | `identifier` anexado; nada muda                                                       |
| `identifier` novo, outro `status`   | Recusado: `CarePlan can only be created with status draft or active` | idem                                                    | idem                                                                                  |
| **sem** `identifier`                | Cria, se o `status` for `draft` ou `active`; senão recusado          | Atualização — **menos** com `draft` ou `active`¹        | Atualização — **menos** com `draft` ou `active`¹                                      |

¹ Uma diretriz aplicada já existente não aceita `draft` nem `active` de novo: a chamada é
recusada com `CarePlan can't be updated to status …`. A única exceção é a diretriz aplicada
em `entered-in-error`.

> **Warning**
>
> A célula que costuma surpreender é a da última coluna: enviar um `identifier` novo para um
> paciente que **já está** naquela diretriz **não cria diretriz aplicada nenhuma e não devolve
> erro**. A resposta é `200` com a diretriz aplicada que já existia, agora carregando também a
> sua chave. Se o seu integrador conta chamadas bem-sucedidas como diretrizes aplicadas criadas,
> ele vai contar errado. Confira o identificador Nilo da resposta antes de concluir que aplicou a
> diretriz — e note que o `status` da resposta não ajuda nessa distinção, porque ele repete o que
> você enviou.

> **Note**
>
> Um paciente tem, no máximo, **uma** diretriz aplicada não terminal por diretriz. Havendo mais
> de uma no store — estado inconsistente, que não deveria acontecer — a escrita falha com
> `IntegrityError: has more than one Care Plan for Patient and PlanDefinition`, e o caso é de
> chamado no Suporte.

### Estados e transições

Na leitura, o `status` da diretriz aplicada vem derivado da situação dele na plataforma:

| Situação na plataforma                   | `status` na leitura |
| ---------------------------------------- | ------------------- |
| Pendente, na fila ou em geração de itens | `on-hold`           |
| Em execução                              | `active`            |
| Concluído                                | `completed`         |
| Cancelado, removido ou com falha         | `revoked`           |
| Sem situação registrada                  | `unknown`           |

Na escrita, o `status` é uma instrução, e nem toda transição é permitida:

| De                      | Para `draft` / `active` | Para `on-hold` | Para `completed` | Para `revoked` / `entered-in-error` |
| ----------------------- | ----------------------- | -------------- | ---------------- | ----------------------------------- |
| `draft`                 | recusado                | recusado¹      | recusado¹        | recusado¹                           |
| `active` · `on-hold`    | recusado                | permitido      | permitido        | permitido                           |
| `entered-in-error`      | **permitido**           | permitido²     | permitido²       | permitido²                          |
| `revoked` · `completed` | recusado                | recusado       | recusado         | recusado                            |

¹ Uma diretriz aplicada ainda em `draft` não tem registro na plataforma para atualizar. A
tentativa falha com `CarePlan with nilo identifier does not exist`.

² Com a mesma ressalva: a diretriz aplicada `entered-in-error` típica é a que falhou na
alocação em massa, e ela nasceu em `draft` — então não tem registro na plataforma, e essas
três transições falham pelo mesmo motivo. O que funciona nele é reenviá-lo como `active` ou
como `draft`.

> **Warning**
>
> **`revoked` e `completed` são terminais.** Uma diretriz aplicada nesses estados não aceita mais
> nenhuma atualização: qualquer `POST` que o alcance pelo `identifier` é recusado com `CarePlan
> with status … can't be updated.`
>
> Para aplicar a **mesma** diretriz de novo ao mesmo paciente, envie um `identifier` **novo**.
> Isso é deliberado: cada aplicação é uma entrada distinta no histórico do paciente naquela
> diretriz, com a data em que entrou e a data em que saiu.

> **Note**
>
> `entered-in-error` é o único estado não terminal do qual se volta. Uma diretriz aplicada que
> falhou na alocação em massa pode ser reenviada com `status: active`, e aí uma nova é criada —
> ou com `status: draft`, e ela volta para a fila.

### Encerrar ou cancelar

Para tirar um paciente de uma diretriz, reenvie a diretriz aplicada trocando só o `status`:

* **`completed`** — o acompanhamento chegou ao fim como previsto.
* **`revoked`** — a aplicação foi indevida e está sendo desfeita.

### Request

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

**`Cancelar o plano`**

```curl Cancelar o plano
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/CarePlan \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "revoked",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    }
  ]
}'
```

**`Cancelar o plano`**

```python Cancelar o plano
import requests

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

payload = {
    "instantiatesCanonical": ["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],
    "intent": "order",
    "resourceType": "CarePlan",
    "status": "revoked",
    "subject": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    },
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
            "value": "349223",
            "use": "usual"
        }
    ]
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cancelar o plano`**

```javascript Cancelar o plano
const url = 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"instantiatesCanonical":["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],"intent":"order","resourceType":"CarePlan","status":"revoked","subject":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"},"identifier":[{"system":"https://www.acmesaude.com.br/integracao/plano-de-cuidado/","value":"349223","use":"usual"}]}'
};

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

**`Cancelar o plano`**

```go Cancelar o plano
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\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))

}
```

**`Cancelar o plano`**

```ruby Cancelar o plano
require 'uri'
require 'net/http'

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

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  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\n  ]\n}"

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

**`Cancelar o plano`**

```java Cancelar o plano
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/CarePlan")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\n  ]\n}")
  .asString();
```

**`Cancelar o plano`**

```php Cancelar o plano
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan', [
  'body' => '{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "revoked",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cancelar o plano`**

```csharp Cancelar o plano
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/CarePlan");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/plano-de-cuidado/\",\n      \"value\": \"349223\",\n      \"use\": \"usual\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cancelar o plano`**

```swift Cancelar o plano
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "instantiatesCanonical": ["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "revoked",
  "subject": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ],
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    ]
  ]
] as [String : Any]

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

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

Os dois tiram o paciente do acompanhamento. A diferença é de intenção, e ela fica no
histórico do paciente.

> **Note**
>
> `entered-in-error` tem, na plataforma, o mesmo efeito de `revoked`. A distinção existe no
> recurso FHIR, não no registro.

Não é preciso mandar o `identifier` para encerrar: sem ele, a diretriz aplicada é localizada
pelo par paciente + diretriz.

### Request

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

**`Cancelar sem identificador`**

```curl Cancelar sem identificador
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/CarePlan \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "revoked",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  }
}'
```

**`Cancelar sem identificador`**

```python Cancelar sem identificador
import requests

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

payload = {
    "instantiatesCanonical": ["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],
    "intent": "order",
    "resourceType": "CarePlan",
    "status": "revoked",
    "subject": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cancelar sem identificador`**

```javascript Cancelar sem identificador
const url = 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"instantiatesCanonical":["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],"intent":"order","resourceType":"CarePlan","status":"revoked","subject":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"}}'
};

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

**`Cancelar sem identificador`**

```go Cancelar sem identificador
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\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))

}
```

**`Cancelar sem identificador`**

```ruby Cancelar sem identificador
require 'uri'
require 'net/http'

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

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  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}"

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

**`Cancelar sem identificador`**

```java Cancelar sem identificador
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/CarePlan")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}")
  .asString();
```

**`Cancelar sem identificador`**

```php Cancelar sem identificador
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan', [
  'body' => '{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "revoked",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cancelar sem identificador`**

```csharp Cancelar sem identificador
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/CarePlan");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"instantiatesCanonical\": [\n    \"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7\"\n  ],\n  \"intent\": \"order\",\n  \"resourceType\": \"CarePlan\",\n  \"status\": \"revoked\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cancelar sem identificador`**

```swift Cancelar sem identificador
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "instantiatesCanonical": ["https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "revoked",
  "subject": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/CarePlan")! 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**
>
> **Uma diretriz aplicada ainda em `draft` não pode ser cancelada.** Ela existe só como recurso
> FHIR, e o cancelamento precisa de um registro na plataforma para atualizar — a chamada falha
> com `CarePlan with nilo identifier does not exist`, e o paciente **continua na fila**.
>
> Duas saídas: esperar a alocação acontecer e cancelar depois, ou aplicá-la agora enviando um
> **`identifier` novo** com `status: active` — é esse caminho, e não o reenvio sem `identifier`,
> que promove uma diretriz aplicada da fila. Aplicada, ela passa a aceitar o cancelamento.

> **Note**
>
> Essa mensagem não é exclusiva do `draft`: ela aparece sempre que o recurso alcançado não
> carrega o identificador Nilo da diretriz aplicada. A diretriz aplicada na fila é o caso comum
> porque nunca teve um — mas um recurso `active` que tenha perdido o identificador falha igual.

## Itens do plano

`activity` é o que a diretriz gerou para aquele paciente. É **só leitura**: os itens não são
criados nem alterados por este recurso. Cada item vem de uma de duas formas.

**Com `reference` e `progress`**, quando o item já tem recurso próprio no store:

| O item é                                                   | `reference.type`       | Valores de `progress[0].text`                                       |
| ---------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------- |
| Consulta agendada                                          | `Appointment`          | `not-started` · `scheduled` · `cancelled` · `completed` · `unknown` |
| Tarefa da equipe                                           | `Task`                 | `requested` · `in-progress` · `completed`                           |
| Questionário do paciente                                   | `Task`                 | `requested` · `completed`                                           |
| [Mensagem programada](/guia/recursos/communicationrequest) | `CommunicationRequest` | `requested` · `completed`                                           |

**Com `detail`**, quando a diretriz prevê uma consulta que ainda não virou agendamento:
`detail.kind` é sempre `Appointment`, `detail.description` traz a especialidade prevista,
`detail.scheduledPeriod` a janela em que ela deveria acontecer e `detail.status` o andamento,
com os mesmos valores da consulta agendada.

> **Note**
>
> A janela de `scheduledPeriod` é **fixa em sete dias**: o fim é sempre sete dias depois do
> início. Ela não reflete um prazo configurado na diretriz.

> **Note**
>
> Tarefas e questionários compartilham o `type: Task` da referência, e se distinguem pelo
> `system` do identificador. Nos dois casos o item é lido como [Tarefa](/guia/recursos/task) — o
> questionário da diretriz aplicada é uma tarefa atribuída ao paciente, não a resposta dele. As
> respostas são outro recurso, o [Questionário respondido](/guia/recursos/questionnaireresponse),
> e não é para ele que esta referência aponta.

> **Note**
>
> Um item pode vir **sem `reference`, sem `progress` e sem `detail`**. Acontece quando o item já
> tem agendamento, mas o agendamento está num estado que esta integração não representa.

> **Warning**
>
> Qual identificador as referências de `activity` carregam depende da mesma configuração de
> implantação que vale para `subject`: com identificadores externos ligados, vem o identificador
> do seu sistema; sem ela, o identificador Nilo. Confira numa resposta real antes de casar as
> referências com os seus registros.

> **Warning**
>
> Uma diretriz aplicada na fila ou ainda em geração (`status: on-hold`) volta **sem** `activity`.
> A lista vazia não significa diretriz sem itens: significa que a geração não terminou. Não
> conclua nada sobre o conteúdo de uma diretriz aplicada até ela estar `active`.

## Buscar

### Request

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

**`Busca de planos com resultados`**

```curl Busca de planos com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/CarePlan \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     -d date=ge2026-01-01 \
     --data-urlencode identifier=https://www.acmesaude.com.br/integracao/plano-de-cuidado/|349223 \
     --data-urlencode instantiates-canonical=https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7 \
     --data-urlencode status=active,on-hold \
     --data-urlencode subject=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4 \
     --data-urlencode subject.identifier=https://www.acmesaude.com.br/integracao/paciente/|507823709
```

**`Busca de planos com resultados`**

```python Busca de planos com resultados
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","date":"[\"ge2026-01-01\"]","identifier":"https://www.acmesaude.com.br/integracao/plano-de-cuidado/|349223","instantiates-canonical":"https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7","status":"active,on-hold","subject":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4","subject.identifier":"https://www.acmesaude.com.br/integracao/paciente/|507823709"}

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

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

print(response.json())
```

**`Busca de planos com resultados`**

```javascript Busca de planos com resultados
const url = 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=%5B%22ge2026-01-01%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fplano-de-cuidado%2F%7C349223&instantiates-canonical=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FPlanDefinition%2Faba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active%2Con-hold&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&subject.identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709';
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 de planos com resultados`**

```go Busca de planos com resultados
package main

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

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/CarePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=%5B%22ge2026-01-01%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fplano-de-cuidado%2F%7C349223&instantiates-canonical=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FPlanDefinition%2Faba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active%2Con-hold&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&subject.identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709"

	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 de planos com resultados`**

```ruby Busca de planos com resultados
require 'uri'
require 'net/http'

url = URI("https://landing-zone-api.nilo.services/fhir/resources/CarePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=%5B%22ge2026-01-01%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fplano-de-cuidado%2F%7C349223&instantiates-canonical=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FPlanDefinition%2Faba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active%2Con-hold&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&subject.identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709")

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 de planos com resultados`**

```java Busca de planos 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/CarePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=%5B%22ge2026-01-01%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fplano-de-cuidado%2F%7C349223&instantiates-canonical=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FPlanDefinition%2Faba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active%2Con-hold&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&subject.identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Busca de planos com resultados`**

```php Busca de planos com resultados
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=%5B%22ge2026-01-01%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fplano-de-cuidado%2F%7C349223&instantiates-canonical=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FPlanDefinition%2Faba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active%2Con-hold&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&subject.identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Busca de planos com resultados`**

```csharp Busca de planos com resultados
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/CarePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=%5B%22ge2026-01-01%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fplano-de-cuidado%2F%7C349223&instantiates-canonical=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FPlanDefinition%2Faba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active%2Con-hold&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&subject.identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

**`Busca de planos com resultados`**

```swift Busca de planos com resultados
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/CarePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&date=%5B%22ge2026-01-01%22%5D&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fplano-de-cuidado%2F%7C349223&instantiates-canonical=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FPlanDefinition%2Faba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active%2Con-hold&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&subject.identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709")! 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`, mesmo quando há um único resultado:

### Response (200)

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/CarePlan/3f21a0d5-9c74-4b18-a6e2-51d8c93f7ab0",
      "resource": {
        "instantiatesCanonical": [
          "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
        ],
        "intent": "order",
        "resourceType": "CarePlan",
        "status": "active",
        "subject": {
          "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
          },
          "type": "Patient",
          "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
        },
        "activity": [
          {
            "detail": {
              "description": "Medicina de Família e Comunidade",
              "kind": "Appointment",
              "scheduledPeriod": {
                "end": "2026-05-11",
                "start": "2026-05-04"
              },
              "status": "not-started"
            }
          },
          {
            "progress": [
              {
                "text": "scheduled"
              }
            ],
            "reference": {
              "identifier": {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--scheduling-v2",
                "value": "702914",
                "use": "usual"
              },
              "type": "Appointment"
            }
          },
          {
            "progress": [
              {
                "text": "in-progress"
              }
            ],
            "reference": {
              "identifier": {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/cogsworth-api--to-do",
                "value": "88214",
                "use": "usual"
              },
              "type": "Task"
            }
          },
          {
            "progress": [
              {
                "text": "requested"
              }
            ],
            "reference": {
              "identifier": {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-questionnaire",
                "value": "31905",
                "use": "usual"
              },
              "type": "Task"
            }
          },
          {
            "progress": [
              {
                "text": "completed"
              }
            ],
            "reference": {
              "identifier": {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--scheduled-message",
                "value": "55407",
                "use": "usual"
              },
              "type": "CommunicationRequest"
            }
          }
        ],
        "category": [
          {
            "text": "care_line"
          }
        ],
        "created": "2026-04-16",
        "description": "Acompanhamento longitudinal de pacientes com diabetes tipo 2.",
        "id": "3f21a0d5-9c74-4b18-a6e2-51d8c93f7ab0",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-care-line",
            "value": "184532",
            "use": "usual"
          },
          {
            "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
            "value": "349223",
            "use": "usual"
          }
        ],
        "period": {
          "start": "2026-04-16"
        },
        "title": "Diabetes tipo 2"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

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

### Response (200)

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

### Parâmetros de busca suportados

| Nome                     | Tipo                                                       | Descrição                                                                  | Expressão                        |
| ------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------- |
| `identifier`             | [token](https://hl7.org/fhir/R4/search.html#token)         | Identificador da diretriz aplicada, em `system\|value`                     | `CarePlan.identifier`            |
| `subject.identifier`     | [token](https://hl7.org/fhir/R4/search.html#token)         | Paciente, pelo identificador dele                                          | `CarePlan.subject.identifier`    |
| `subject`                | [reference](https://hl7.org/fhir/R4/search.html#reference) | Paciente, pelo `id` Nilo FHIR                                              | `CarePlan.subject`               |
| `instantiates-canonical` | [reference](https://hl7.org/fhir/R4/search.html#reference) | Diretriz, pela URL do `PlanDefinition`                                     | `CarePlan.instantiatesCanonical` |
| `status`                 | [token](https://hl7.org/fhir/R4/search.html#token)         | Situação da diretriz aplicada. Aceita vários valores separados por vírgula | `CarePlan.status`                |
| `date`                   | [date](https://hl7.org/fhir/R4/search.html#date)           | Período de aplicação, com os prefixos `eq`, `ge`, `le`                     | `CarePlan.period`                |
| `_lastUpdated`           | [date](https://hl7.org/fhir/R4/search.html#date)           | Data da última gravação no store, com os mesmos prefixos                   | —                                |

O par `subject.identifier` + `instantiates-canonical` é o que identifica a diretriz aplicada a
um paciente — é a mesma busca que a própria plataforma usa para reconhecer uma diretriz
aplicada já existente:

```bash
# a diretriz aplicada a um paciente, em qualquer estado não terminal
curl --request GET \
  --url 'https://landing-zone-api.nilo.services/fhir/resources/CarePlan?subject.identifier=https://www.acmesaude.com.br/integracao/paciente/|507823709&instantiates-canonical=https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7&status=active,on-hold,draft,entered-in-error' \
  --header 'x-api-key: SUA_API_KEY'
```

> **Warning**
>
> Qual identificador do paciente o `subject` carrega **depende da sua implantação**. Na
> configuração que usa identificadores externos nas referências, é o identificador do seu
> sistema — e o filtro acima funciona como está. Sem ela, o `subject` traz o identificador Nilo
> do paciente (`…/NamingSystem/hippocrates-api--patient`), e é esse `system` que você tem de
> usar no filtro. Confira numa resposta de leitura qual dos dois está lá antes de montar a
> busca em volume.

> **Note**
>
> Vários parâmetros canônicos da `CarePlan` existem e **não encontram nada** aqui, porque a Nilo
> não preenche o campo correspondente: `care-team`, `condition`, `goal`, `encounter`,
> `based-on`, `replaces`, `part-of`, `performer`, `activity-code` e `activity-reference`.
>
> `intent` é um caso diferente: ele funciona, e por isso é inútil — o valor é constante, então
> `intent=order` traz todas as diretrizes aplicadas.
>
> `category` é um caso à parte: o tipo da diretriz vem apenas como texto em `category[0].text`,
> sem `coding`. Uma busca por token no `category` não encontra a diretriz aplicada por
> `care_line` nem por `protocol`.

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/CarePlan/\{id}](https://landing-zone-api.nilo.services/fhir/resources/CarePlan/\{id})

**`Plano encontrado`**

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

**`Plano encontrado`**

```python Plano encontrado
import requests

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

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

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

print(response.json())
```

**`Plano encontrado`**

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

**`Plano encontrado`**

```go Plano encontrado
package main

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

func main() {

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

}
```

**`Plano encontrado`**

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

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

**`Plano encontrado`**

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

**`Plano encontrado`**

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

$client = new \GuzzleHttp\Client();

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

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

**`Plano encontrado`**

```csharp Plano encontrado
using RestSharp;

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

**`Plano encontrado`**

```swift Plano encontrado
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/CarePlan/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> **Warning**
>
> Diferente da busca, esta leitura não devolve um `Bundle` — mas também **não devolve o recurso
> nu**. A resposta é um envelope com `fullUrl`, `search` e `resource`, e a diretriz aplicada está
> em `resource`. Ler `status` ou `activity` na raiz da resposta não encontra nada.

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/CarePlan/3f21a0d5-9c74-4b18-a6e2-51d8c93f7ab0",
  "resource": {
    "instantiatesCanonical": [
      "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
    ],
    "intent": "order",
    "resourceType": "CarePlan",
    "status": "active",
    "subject": {
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/paciente/",
        "value": "507823709",
        "use": "usual"
      },
      "type": "Patient",
      "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
    },
    "activity": [
      {
        "progress": [
          {
            "text": "in-progress"
          }
        ],
        "reference": {
          "identifier": {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/cogsworth-api--to-do",
            "value": "88214",
            "use": "usual"
          },
          "type": "Task"
        }
      }
    ],
    "category": [
      {
        "text": "care_line"
      }
    ],
    "created": "2026-04-16",
    "description": "Acompanhamento longitudinal de pacientes com diabetes tipo 2.",
    "id": "3f21a0d5-9c74-4b18-a6e2-51d8c93f7ab0",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-care-line",
        "value": "184532",
        "use": "usual"
      },
      {
        "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
        "value": "349223",
        "use": "usual"
      }
    ],
    "meta": {
      "lastUpdated": "2026-04-16T20:05:03.118000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "period": {
      "start": "2026-04-16"
    },
    "title": "Diabetes tipo 2"
  },
  "search": {
    "mode": "match"
  }
}
```

A leitura por ID responde `404` quando o `id` não existe.

### Quando a alocação falha

A alocação em massa de uma diretriz pode falhar para um paciente específico — por exemplo,
quando a equipe dele não cobre as especialidades exigidas. Nesse caso a diretriz aplicada passa a
`entered-in-error` e o motivo da falha vem em `note`:

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/CarePlan/7b04e9c1-2d63-4f57-9a08-c1e5b7304d29",
  "resource": {
    "instantiatesCanonical": [
      "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
    ],
    "intent": "order",
    "resourceType": "CarePlan",
    "status": "entered-in-error",
    "subject": {
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/paciente/",
        "value": "507823709",
        "use": "usual"
      },
      "type": "Patient",
      "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
    },
    "id": "7b04e9c1-2d63-4f57-9a08-c1e5b7304d29",
    "identifier": [
      {
        "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
        "value": "349224",
        "use": "usual"
      }
    ],
    "note": [
      {
        "text": "Não há profissional com a especialidade exigida na equipe de cuidado do paciente."
      }
    ]
  },
  "search": {
    "mode": "match"
  }
}
```

> **Note**
>
> É o único caso em que `note` aparece numa diretriz aplicada. Uma diretriz aplicada com `note`
> preenchido é sempre uma diretriz aplicada que falhou.

## Valores aceitos

### `status`

Na escrita, `draft`, `active`, `on-hold`, `completed`, `revoked` e `entered-in-error` — com as
restrições de transição descritas acima. `unknown` só aparece na leitura, numa diretriz
aplicada sem situação registrada na plataforma.

### `intent`

O FHIR R4 exige o campo, e nada na integração o lê: ele não escolhe modo de aplicação nem
nível de autoridade. É preenchimento obrigatório sem efeito. Envie `order` — é o valor que
todas as leituras geradas pela plataforma trazem, e o que o resto da documentação assume.

### `category`

Só resposta, e sem `coding`: o tipo da diretriz vem em `category[0].text` como `care_line` ou
`protocol`.

## Efeitos colaterais

> **Warning**
>
> **`status: active` cria a diretriz aplicada na plataforma durante a requisição.** É a única
> escrita desta página que altera o cadastro do paciente de forma imediata — e o que ela dispara
> em seguida (geração de tarefas, agendamentos, questionários e mensagens) acontece de forma
> assíncrona, fora do controle da chamada.

> **Warning**
>
> **`revoked` e `completed` tiram o paciente do acompanhamento e são irreversíveis.** A diretriz
> aplicada deixa de estar em execução e não aceita mais nenhuma atualização. O que acontece com
> as tarefas e mensagens ainda não executadas é decidido pela plataforma, fora do alcance desta
> chamada — não conte com elas depois de encerrar a diretriz aplicada.

> **Warning**
>
> **Um `identifier` novo num paciente já alocado não cria diretriz aplicada.** A chamada responde
> `200` com a diretriz aplicada existente e a sua chave anexada a ele. Veja a tabela em [Como a API reconhece o plano](#como-a-api-reconhece-o-plano).

> **Note**
>
> Este endpoint não remove diretrizes aplicadas: a escrita nunca responde `204`. O que existe é o
> cancelamento, por `revoked` — e ele preserva o registro no histórico do paciente.

## Erros

Recusa é `400`, e o corpo é um `OperationOutcome`: `issue[].expression` aponta o campo culpado
e `issue[].details.text` explica o motivo. O outro código que este endpoint devolve é `429`.

| `code`      | `expression`                     | Mensagem                                                         | Quando                                                                                                                     |
| ----------- | -------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `structure` | `CarePlan.?`                     | `patient_without_care_team`                                      | O paciente não tem equipe de cuidado                                                                                       |
| `structure` | `CarePlan.?`                     | `todo_without_responsible`                                       | A equipe não cobre uma especialidade que a diretriz exige                                                                  |
| `structure` | `CarePlan.subject`               | `Patient with identifier … does not exist or is not active`      | O identificador do paciente não resolve                                                                                    |
| `structure` | `CarePlan.subject`               | `Multiple Patient with identifier … found`                       | O identificador casa com mais de um paciente                                                                               |
| `structure` | `CarePlan.subject`               | `Only Patient type is supported.`                                | `subject.type` diferente de `Patient`                                                                                      |
| `structure` | `CarePlan.subject`               | `Patient with nilo identifier does not exist`                    | O paciente existe no store mas não tem identificador Nilo                                                                  |
| `structure` | `CarePlan.instantiatesCanonical` | `instantiatesCanonical is required.`                             | Campo ausente                                                                                                              |
| `structure` | `CarePlan.instantiatesCanonical` | `PlanDefinition referenced by … does not exist or is not active` | A URL da diretriz não resolve                                                                                              |
| `structure` | `CarePlan.instantiatesCanonical` | `PlanDefinition with id … does not point to an active care line` | A diretriz existe, mas está fora da vigência                                                                               |
| `structure` | `CarePlan.instantiatesCanonical` | `PlanDefinition with id … does not have an allocation config`    | Só com `draft`: a diretriz não tem configuração de fila                                                                    |
| `structure` | `CarePlan.status`                | `CarePlan can only be created with status draft or active`       | Criação com qualquer outro `status`                                                                                        |
| `structure` | `CarePlan.status`                | `CarePlan can't be updated to status …`                          | Diretriz aplicada existente voltando para `draft` ou `active`                                                              |
| `structure` | `CarePlan.status`                | `CarePlan with status … can't be updated.`                       | Diretriz aplicada já `revoked` ou `completed`                                                                              |
| `structure` | `CarePlan.author`                | `Only Practitioner type is supported.`                           | `author.type` diferente de `Practitioner`                                                                                  |
| `structure` | `CarePlan.author`                | `Practitioner with identifier … does not exist or is not active` | O `author` enviado não resolve                                                                                             |
| `structure` | `CarePlan.None`                  | `CarePlan with nilo identifier does not exist`                   | A diretriz aplicada alcançada não tem identificador Nilo — o caso comum é atualizar uma diretriz aplicada ainda em `draft` |
| `structure` | `CarePlan.None`                  | `PlanDefinition with nilo identifier does not exist`             | A diretriz existe no store, mas sem identificador Nilo                                                                     |
| `structure` | `CarePlan.author`                | `Practitioner with nilo identifier does not exist`               | O profissional de `author` existe no store, mas sem identificador Nilo                                                     |
| `exception` | —                                | `IntegrityError: has more than one Care Plan …`                  | Mais de uma diretriz aplicada não terminal para o par paciente + diretriz                                                  |

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

### Response (200)

```json
{
  "instantiatesCanonical": [
    "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/aba72582-f9fb-49ea-b316-73b8dba2a4d7"
  ],
  "intent": "order",
  "resourceType": "CarePlan",
  "status": "active",
  "subject": {
    "identifier": {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient",
      "value": "1013441",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "category": [
    {
      "text": "care_line"
    }
  ],
  "created": "2026-04-16",
  "description": "Acompanhamento longitudinal de pacientes com diabetes tipo 2.",
  "id": "3f21a0d5-9c74-4b18-a6e2-51d8c93f7ab0",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/plano-de-cuidado/",
      "value": "349223",
      "use": "usual"
    },
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-care-line",
      "value": "184532",
      "use": "usual"
    }
  ],
  "meta": {
    "lastUpdated": "2026-04-16T20:05:03.118000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "period": {
    "start": "2026-04-16"
  },
  "title": "Diabetes tipo 2"
}
```

> **Warning**
>
> Cinco linhas da tabela trazem `expression` que **não é FHIRPath válido**: as duas de
> `CarePlan.?`, que vêm da plataforma, e as três de `CarePlan.None`. Some-se a elas a linha de
> `exception`, que vem sem `expression` nenhum. Um integrador que usa o `expression` para
> destacar o campo culpado precisa tratar esses casos à parte.

### Limite de escrita

A aplicação imediata (`status: active`) pode ser limitada por janela de tempo, para todo o seu
ambiente. Atingido o limite, a resposta é `429` com o `code` `throttled` e o tempo de espera
na mensagem — aguarde e repita. As demais escritas deste recurso não entram nessa conta.

O limite vigente é definido na implantação, e pode estar desligado. Se você vai fazer uma
carga em volume, confirme com o Suporte qual é o teto do seu ambiente antes de dimensionar.