> 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

> Cadastrar e consultar as diretrizes de cuidado — linhas de cuidado e protocolos — no padrão FHIR PlanDefinition.

Uma **diretriz** é o desenho do cuidado: a sequência de consultas, tarefas, questionários e
mensagens que a equipe segue para um tipo de paciente. Ela é o molde; aplicá-la a **um**
paciente produz uma [diretriz aplicada](/guia/recursos/careplan).

No FHIR a diretriz é um
[`PlanDefinition`](https://hl7.org/fhir/R4/plandefinition.html). Esta página cobre o cadastro
e a consulta das diretrizes; a aplicação a um paciente está na página da diretriz aplicada.

> **Warning**
>
> **Esta API grava o cabeçalho da diretriz, não o conteúdo dela.** Nome, descrição e tipo são
> graváveis. As consultas previstas, as tarefas, os questionários e as mensagens programadas que
> a diretriz gera são montados pela equipe no Nilo Care — e uma diretriz criada por aqui **nasce
> vazia**, sem gerar nada quando aplicada a um paciente.
>
> Na prática, o uso mais comum deste recurso é **de leitura**: descobrir a URL da diretriz para
> aplicá-la.

## Linha de cuidado e protocolo

A plataforma organiza as diretrizes em dois tipos:

| Tipo                 | Código              | Como a equipe o usa                     | Exemplo                       |
| -------------------- | ------------------- | --------------------------------------- | ----------------------------- |
| **Linha de cuidado** | `order-set`         | Acompanhamento contínuo de uma condição | Diabetes, hipertensão         |
| **Protocolo**        | `clinical-protocol` | Um roteiro com começo, meio e fim       | Acompanhamento pós-operatório |

> **Note**
>
> O tipo é uma **convenção de uso**, não uma regra que a plataforma aplique: a duração da
> diretriz é um campo à parte, e nada impede uma linha de cuidado com término definido nem um
> protocolo sem. A duração, aliás, **não é gravável nem legível por esta API** — é configurada no
> Nilo Care.

## Campos

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

| Campo             | Obrigatório | O que significa                                                                                  | No Nilo Care                                                    |
| ----------------- | ----------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `resourceType`    | **sim**     | Constante `PlanDefinition`                                                                       | —                                                               |
| `identifier`      | **sim**     | Suas chaves da diretriz. É por elas que a API decide entre criar e atualizar                     | —                                                               |
| `status`          | **sim**     | Exigido pelo FHIR e **descartado na escrita**. Envie `active`. Na leitura, `active` ou `retired` | —                                                               |
| `name`            | **sim**     | Nome da diretriz, com no máximo 100 caracteres                                                   | **Nome**, no cadastro; **Diretriz**, ao aplicá-la a um paciente |
| `description`     | não         | Descrição da diretriz                                                                            | **Descrição**                                                   |
| `type`            | não         | `order-set` ou `clinical-protocol`, num `coding` do sistema de tipo do HL7                       | **Tipo**                                                        |
| `url`             | não         | Uma URL canônica sua, para referenciar a diretriz sem depender do `id`                           | —                                                               |
| `effectivePeriod` | não         | Só resposta: a vigência da diretriz                                                              | —                                                               |
| `id` · `meta`     | não         | Só resposta: identificador Nilo FHIR da diretriz e metadados da gravação                         | —                                                               |

### `status` e `effectivePeriod` andam juntos

> **Note**
>
> O `status` é derivado da vigência: `active` enquanto a data de hoje está **dentro** do
> `effectivePeriod`, `retired` fora dele — antes do início e depois do fim. Uma diretriz sem
> período nenhum é sempre `active`.
>
> Os dois são definidos na plataforma. Enviar `status` ou `effectivePeriod` não tem efeito: o
> `status` é obrigatório pelo FHIR, então mande `active` e ignore o que ele significa na escrita.

> **Warning**
>
> **Só diretriz `active` pode ser aplicada a um paciente.** Uma `retired` continua aparecendo na
> busca — e uma diretriz cujo início ainda não chegou também é `retired` —, mas uma [diretriz aplicada](/guia/recursos/careplan) que a referencie é recusada com `does not exist or is not
> active`. Filtre por `status=active` antes de aplicar.

### Campos que a Nilo não usa

O `PlanDefinition` canônico traz muito mais do que esta integração lê: `version`, `title`,
`subtitle`, `experimental`, `subject`, `date`, `publisher`, `contact`, `useContext`,
`jurisdiction`, `purpose`, `usage`, `copyright`, `approvalDate`, `lastReviewDate`, `topic`,
`author`, `editor`, `reviewer`, `endorser`, `relatedArtifact`, `library`, `goal` e — o mais
importante — **`action`**. Nenhum deles é lido.

> **Warning**
>
> **`action` é o campo em que o FHIR descreve o conteúdo de uma diretriz, e ele não é
> suportado.** Não há como enviar as consultas, tarefas ou questionários da diretriz por esta
> API, nem lê-los. O que a diretriz gera só se vê depois de aplicada, em `CarePlan.activity[]` —
> veja [Diretriz aplicada](/guia/recursos/careplan).
>
> Repare também em **`title`**: o FHIR distingue `name` (identificador legível) de `title` (nome
> de exibição), e aqui só o `name` é lido. É ele que a equipe vê.
>
> E a **duração** da diretriz, que o Nilo Care pede no cadastro, não tem campo aqui: não é
> gravável nem legível por esta API.

> **Note**
>
> A referência lista só os campos suportados, e é assim que ela deve ser lida: **o que mandar na
> escrita**. A API em si **não recusa** quem manda os outros — eles ficam guardados no recurso e
> voltam nas leituras seguintes, sem nunca terem significado nada para a plataforma. Omita-os.

## Encontrar a diretriz para aplicar

Este é o uso principal do recurso: `CarePlan.instantiatesCanonical` precisa de uma URL, e é
aqui que você a obtém.

### 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()
```

### Response (200)

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/5d81f3b6-04e7-4a29-9c50-b6127ea38d41",
      "resource": {
        "resourceType": "PlanDefinition",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--care-line",
            "value": "412",
            "use": "usual"
          },
          {
            "system": "https://www.acmesaude.com.br/integracao/diretriz/",
            "value": "DM2",
            "use": "usual"
          }
        ],
        "name": "Acompanhamento de diabetes tipo 2",
        "status": "active",
        "id": "5d81f3b6-04e7-4a29-9c50-b6127ea38d41",
        "meta": {
          "lastUpdated": "2026-03-02T09:41:55.318000Z",
          "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
        },
        "description": "Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
              "code": "order-set",
              "display": "Order Set"
            }
          ]
        },
        "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2",
        "effectivePeriod": {
          "start": "2025-01-01T00:00:00+00:00"
        }
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/b7420ce9-1d68-43a5-8f01-e6329ba5d7c2",
      "resource": {
        "resourceType": "PlanDefinition",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--care-line",
            "value": "388",
            "use": "usual"
          }
        ],
        "name": "Pós-operatório de artroplastia",
        "status": "retired",
        "id": "b7420ce9-1d68-43a5-8f01-e6329ba5d7c2",
        "meta": {
          "lastUpdated": "2026-01-15T13:02:44.907000Z",
          "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM4MA"
        },
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
              "code": "clinical-protocol",
              "display": "Clinical Protocol"
            }
          ]
        },
        "effectivePeriod": {
          "end": "2026-01-15T00:00:00+00:00",
          "start": "2024-02-01T00:00:00+00:00"
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

Há **duas formas** de montar o `instantiatesCanonical`, e as duas funcionam:

| Forma                | O que enviar                                | Quando usar                                                            |
| -------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| Pelo `id` do recurso | `{host}/fhir/resources/PlanDefinition/{id}` | Sempre funciona, mas o `id` é da plataforma e muda entre ambientes     |
| Pela `url` canônica  | o valor exato do campo `url`                | Quando você definiu uma `url` sua — a mesma vale em todos os ambientes |

> **Note**
>
> A resolução 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 `active`.

> **Warning**
>
> A forma pelo `id` embute o **host do ambiente**, e o `id` é diferente em cada um. Uma
> integração que promove configuração entre homologação e produção tem de reescrever essas URLs.
> Definir uma `url` própria em cada diretriz resolve isso de vez: o mesmo valor funciona nos dois
> ambientes.

## Cadastrar ou atualizar

### Request

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

**`Cadastrar uma linha de cuidado`**

```curl Cadastrar uma linha de cuidado
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    }
  ],
  "name": "Acompanhamento de diabetes tipo 2",
  "status": "active",
  "description": "Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "order-set"
      }
    ]
  },
  "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2"
}'
```

**`Cadastrar uma linha de cuidado`**

```python Cadastrar uma linha de cuidado
import requests

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

payload = {
    "resourceType": "PlanDefinition",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/diretriz/",
            "value": "DM2",
            "use": "usual"
        }
    ],
    "name": "Acompanhamento de diabetes tipo 2",
    "status": "active",
    "description": "Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.",
    "type": { "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
                "code": "order-set"
            }
        ] },
    "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cadastrar uma linha de cuidado`**

```javascript Cadastrar uma linha de cuidado
const url = 'https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"PlanDefinition","identifier":[{"system":"https://www.acmesaude.com.br/integracao/diretriz/","value":"DM2","use":"usual"}],"name":"Acompanhamento de diabetes tipo 2","status":"active","description":"Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.","type":{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/plan-definition-type","code":"order-set"}]},"url":"https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2"}'
};

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

**`Cadastrar uma linha de cuidado`**

```go Cadastrar uma linha de cuidado
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2\",\n  \"status\": \"active\",\n  \"description\": \"Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"order-set\"\n      }\n    ]\n  },\n  \"url\": \"https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Cadastrar uma linha de cuidado`**

```ruby Cadastrar uma linha de cuidado
require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2\",\n  \"status\": \"active\",\n  \"description\": \"Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"order-set\"\n      }\n    ]\n  },\n  \"url\": \"https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2\"\n}"

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

**`Cadastrar uma linha de cuidado`**

```java Cadastrar uma linha de cuidado
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/PlanDefinition")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2\",\n  \"status\": \"active\",\n  \"description\": \"Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"order-set\"\n      }\n    ]\n  },\n  \"url\": \"https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2\"\n}")
  .asString();
```

**`Cadastrar uma linha de cuidado`**

```php Cadastrar uma linha de cuidado
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition', [
  'body' => '{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    }
  ],
  "name": "Acompanhamento de diabetes tipo 2",
  "status": "active",
  "description": "Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "order-set"
      }
    ]
  },
  "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cadastrar uma linha de cuidado`**

```csharp Cadastrar uma linha de cuidado
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2\",\n  \"status\": \"active\",\n  \"description\": \"Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"order-set\"\n      }\n    ]\n  },\n  \"url\": \"https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cadastrar uma linha de cuidado`**

```swift Cadastrar uma linha de cuidado
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "PlanDefinition",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    ]
  ],
  "name": "Acompanhamento de diabetes tipo 2",
  "status": "active",
  "description": "Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.",
  "type": ["coding": [
      [
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "order-set"
      ]
    ]],
  "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2"
] as [String : Any]

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

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

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

dataTask.resume()
```

A resposta é o recurso gravado, sem envelope:

### Response (200)

```json
{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--care-line",
      "value": "412",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    }
  ],
  "name": "Acompanhamento de diabetes tipo 2",
  "status": "active",
  "id": "5d81f3b6-04e7-4a29-9c50-b6127ea38d41",
  "meta": {
    "lastUpdated": "2026-03-02T09:41:55.318000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "description": "Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "order-set",
        "display": "Order Set"
      }
    ]
  },
  "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2",
  "effectivePeriod": {
    "start": "2025-01-01T00:00:00+00:00"
  }
}
```

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

O mesmo `POST` cria e atualiza. Reenviando um `identifier` que já corresponde a uma diretriz,
ela é atualizada.

### Request

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

**`Cadastrar um protocolo`**

```curl Cadastrar um protocolo
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "POS-ARTRO",
      "use": "usual"
    }
  ],
  "name": "Pós-operatório de artroplastia",
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "clinical-protocol"
      }
    ]
  }
}'
```

**`Cadastrar um protocolo`**

```python Cadastrar um protocolo
import requests

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

payload = {
    "resourceType": "PlanDefinition",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/diretriz/",
            "value": "POS-ARTRO",
            "use": "usual"
        }
    ],
    "name": "Pós-operatório de artroplastia",
    "status": "active",
    "type": { "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
                "code": "clinical-protocol"
            }
        ] }
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cadastrar um protocolo`**

```javascript Cadastrar um protocolo
const url = 'https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"PlanDefinition","identifier":[{"system":"https://www.acmesaude.com.br/integracao/diretriz/","value":"POS-ARTRO","use":"usual"}],"name":"Pós-operatório de artroplastia","status":"active","type":{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/plan-definition-type","code":"clinical-protocol"}]}}'
};

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

**`Cadastrar um protocolo`**

```go Cadastrar um protocolo
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"POS-ARTRO\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Pós-operatório de artroplastia\",\n  \"status\": \"active\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"clinical-protocol\"\n      }\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))

}
```

**`Cadastrar um protocolo`**

```ruby Cadastrar um protocolo
require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"POS-ARTRO\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Pós-operatório de artroplastia\",\n  \"status\": \"active\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"clinical-protocol\"\n      }\n    ]\n  }\n}"

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

**`Cadastrar um protocolo`**

```java Cadastrar um protocolo
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/PlanDefinition")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"POS-ARTRO\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Pós-operatório de artroplastia\",\n  \"status\": \"active\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"clinical-protocol\"\n      }\n    ]\n  }\n}")
  .asString();
```

**`Cadastrar um protocolo`**

```php Cadastrar um protocolo
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition', [
  'body' => '{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "POS-ARTRO",
      "use": "usual"
    }
  ],
  "name": "Pós-operatório de artroplastia",
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "clinical-protocol"
      }
    ]
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cadastrar um protocolo`**

```csharp Cadastrar um protocolo
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"POS-ARTRO\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Pós-operatório de artroplastia\",\n  \"status\": \"active\",\n  \"type\": {\n    \"coding\": [\n      {\n        \"system\": \"http://terminology.hl7.org/CodeSystem/plan-definition-type\",\n        \"code\": \"clinical-protocol\"\n      }\n    ]\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cadastrar um protocolo`**

```swift Cadastrar um protocolo
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "PlanDefinition",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "POS-ARTRO",
      "use": "usual"
    ]
  ],
  "name": "Pós-operatório de artroplastia",
  "status": "active",
  "type": ["coding": [
      [
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "clinical-protocol"
      ]
    ]]
] as [String : Any]

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

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

### O tipo é preservado quando você o omite

> **Note**
>
> `type` é o único campo desta página com preservação por omissão:
>
> * numa diretriz **existente**, omitir `type` mantém o tipo que ela já tem;
> * numa diretriz **nova**, omitir `type` cria uma **linha de cuidado**.
>
> A API varre **todos** os `coding` e usa o primeiro cujo `system` seja o de tipo de diretriz do
> HL7, em qualquer posição da lista. Um `coding` em outro `system`, ou com um código fora dos dois
> aceitos, é ignorado — e cai na mesma regra da omissão, sem erro.

### Request

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

**`Renomear sem mudar o tipo`**

```curl Renomear sem mudar o tipo
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    }
  ],
  "name": "Acompanhamento de diabetes tipo 2 — adultos",
  "status": "active"
}'
```

**`Renomear sem mudar o tipo`**

```python Renomear sem mudar o tipo
import requests

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

payload = {
    "resourceType": "PlanDefinition",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/diretriz/",
            "value": "DM2",
            "use": "usual"
        }
    ],
    "name": "Acompanhamento de diabetes tipo 2 — adultos",
    "status": "active"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Renomear sem mudar o tipo`**

```javascript Renomear sem mudar o tipo
const url = 'https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"PlanDefinition","identifier":[{"system":"https://www.acmesaude.com.br/integracao/diretriz/","value":"DM2","use":"usual"}],"name":"Acompanhamento de diabetes tipo 2 — adultos","status":"active"}'
};

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

**`Renomear sem mudar o tipo`**

```go Renomear sem mudar o tipo
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2 — adultos\",\n  \"status\": \"active\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Renomear sem mudar o tipo`**

```ruby Renomear sem mudar o tipo
require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2 — adultos\",\n  \"status\": \"active\"\n}"

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

**`Renomear sem mudar o tipo`**

```java Renomear sem mudar o tipo
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/PlanDefinition")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2 — adultos\",\n  \"status\": \"active\"\n}")
  .asString();
```

**`Renomear sem mudar o tipo`**

```php Renomear sem mudar o tipo
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition', [
  'body' => '{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    }
  ],
  "name": "Acompanhamento de diabetes tipo 2 — adultos",
  "status": "active"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Renomear sem mudar o tipo`**

```csharp Renomear sem mudar o tipo
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"PlanDefinition\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/diretriz/\",\n      \"value\": \"DM2\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acompanhamento de diabetes tipo 2 — adultos\",\n  \"status\": \"active\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Renomear sem mudar o tipo`**

```swift Renomear sem mudar o tipo
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "PlanDefinition",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    ]
  ],
  "name": "Acompanhamento de diabetes tipo 2 — adultos",
  "status": "active"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition")! 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**
>
> `name` e `description`, ao contrário, **não** são preservados: uma atualização sem
> `description` apaga a descrição. O exemplo acima faz exatamente isso — repare que ele não traz
> `description`. Reenvie os dois sempre.

### A URL canônica

`url` é o campo mais útil deste recurso para quem integra. A plataforma **não o guarda** como
dado da diretriz, mas ele fica no recurso FHIR e é por ele que a diretriz pode ser encontrada:

```json
"url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2"
```

> **Warning**
>
> **A `url` tem de ser única.** Uma URL já usada por outra diretriz recusa a chamada com `409`, e
> o mesmo acontece quando a `url` e o `identifier` do payload apontam para diretrizes diferentes
> — o caso clássico de copiar um payload e trocar só a chave.
>
> São os dois únicos `409` deste recurso.

> **Warning**
>
> **Defina a `url` na mesma chamada em que cria a diretriz.** Acrescentá-la depois, sem mudar
> nome, descrição ou tipo, pode **não ter efeito**: a plataforma reconhece que nada mudou do lado
> dela e devolve o recurso como já estava, com `200` e sem gravar a URL. O mesmo vale para
> acrescentar um `identifier` seu ou qualquer outro campo que a plataforma não guarda.
>
> Confira a `url` na resposta. Se ela não voltou, reenvie junto com uma alteração real — de nome
> ou de descrição.

## Buscar

### 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 resposta é sempre um `Bundle` do tipo `searchset`, e busca sem resultados não é erro: volta
`200` com um `Bundle` cujo `entry` é uma lista vazia.

### Response (200)

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

### Parâmetros de busca suportados

| Nome           | Tipo                                                 | Descrição                                                                            | Expressão                   |
| -------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------- |
| `identifier`   | [token](https://hl7.org/fhir/R4/search.html#token)   | Identificador da diretriz, em `system\|value`                                        | `PlanDefinition.identifier` |
| `status`       | [token](https://hl7.org/fhir/R4/search.html#token)   | `active` ou `retired`                                                                | `PlanDefinition.status`     |
| `name`         | [string](https://hl7.org/fhir/R4/search.html#string) | Nome da diretriz. A busca casa pelo **início** do nome, não por qualquer trecho dele | `PlanDefinition.name`       |
| `url`          | [uri](https://hl7.org/fhir/R4/search.html#uri)       | A URL canônica **exata**                                                             | `PlanDefinition.url`        |
| `type`         | [token](https://hl7.org/fhir/R4/search.html#token)   | Tipo da diretriz, em `system\|code`                                                  | `PlanDefinition.type`       |
| `_lastUpdated` | [date](https://hl7.org/fhir/R4/search.html#date)     | Data da última gravação no store, com os prefixos `eq`, `ge`, `le`                   | —                           |

> **Note**
>
> Os demais parâmetros canônicos do `PlanDefinition` — `title`, `version`, `date`, `publisher`,
> `context`, `jurisdiction`, `topic`, `composed-of`, `depends-on`, `derived-from`, `predecessor`
> e `successor` — só encontram o que **você** tiver enviado: a Nilo não preenche esses campos,
> mas guarda o que vier no payload. Numa diretriz criada pela plataforma eles vêm vazios, e a
> busca não devolve nada.

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

> **Note**
>
> Uma diretriz antiga, que ninguém tenha tocado desde que a sua integração começou, pode não
> aparecer na lista. Se você espera uma diretriz e ela não vem, peça ao **Suporte**: a busca não
> é um inventário garantido.

## Ler por ID

### Request

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

**`Diretriz encontrada`**

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

**`Diretriz encontrada`**

```python Diretriz encontrada
import requests

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

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

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

print(response.json())
```

**`Diretriz encontrada`**

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

**`Diretriz encontrada`**

```go Diretriz encontrada
package main

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

func main() {

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

}
```

**`Diretriz encontrada`**

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

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

**`Diretriz encontrada`**

```java Diretriz encontrada
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/id")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Diretriz encontrada`**

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

$client = new \GuzzleHttp\Client();

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

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

**`Diretriz encontrada`**

```csharp Diretriz encontrada
using RestSharp;

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

**`Diretriz encontrada`**

```swift Diretriz encontrada
import Foundation

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

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

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/PlanDefinition/5d81f3b6-04e7-4a29-9c50-b6127ea38d41",
  "resource": {
    "resourceType": "PlanDefinition",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--care-line",
        "value": "412",
        "use": "usual"
      },
      {
        "system": "https://www.acmesaude.com.br/integracao/diretriz/",
        "value": "DM2",
        "use": "usual"
      }
    ],
    "name": "Acompanhamento de diabetes tipo 2",
    "status": "active",
    "id": "5d81f3b6-04e7-4a29-9c50-b6127ea38d41",
    "meta": {
      "lastUpdated": "2026-03-02T09:41:55.318000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "type": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
          "code": "order-set",
          "display": "Order Set"
        }
      ]
    },
    "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2",
    "effectivePeriod": {
      "start": "2025-01-01T00:00:00+00:00"
    }
  },
  "search": {
    "mode": "match"
  }
}
```

## Valores aceitos

### `type.coding[0].code`

Dois: `order-set` (linha de cuidado) e `clinical-protocol` (protocolo). O `system` tem de ser
`http://terminology.hl7.org/CodeSystem/plan-definition-type`.

Os demais códigos do vocabulário HL7 — `eca-rule` e `workflow-definition` — não têm destino na
plataforma e são **ignorados em silêncio**, caindo na regra da omissão.

### `status`

Dois na leitura: `active` e `retired`. Nenhum deles é gravável.

## Efeitos colaterais

> **Note**
>
> Criar ou renomear uma diretriz **não afeta os pacientes que já estão nela**. As diretrizes
> aplicadas existentes continuam como estão; o que muda é o nome exibido.

> **Warning**
>
> **Mudar o `type` de uma diretriz com pacientes é uma decisão de negócio, não de integração.**
> Linha de cuidado e protocolo têm regras de duração diferentes. Se a sua integração sincroniza
> o tipo a partir de um sistema seu, confira antes que a mudança é intencional.

> **Warning**
>
> **Uma diretriz excluída no Nilo Care some daqui.** Ela não vira `retired`: o recurso deixa de
> existir, a leitura por `id` passa a responder `404` e ela some da busca — sem aviso. Se você
> guarda o conteúdo de uma diretriz, guarde o conteúdo, não o `id`.

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

## Erros

Recusa é `400`, e o corpo é um `OperationOutcome`: `issue[].details.text` explica o motivo e,
quando a recusa é de um campo conferido por esta API, `issue[].expression` aponta qual. As
duas exceções são os `409` da `url`.

| Status | `code`          | `expression`                | Mensagem                                                                                                                           | Quando                                                        |
| ------ | --------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `400`  | `required`      | `PlanDefinition.identifier` | `Field is required`                                                                                                                | O payload não tem `identifier`                                |
| `400`  | `business-rule` | `PlanDefinition.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`  | `structure`     | —                           | `Resource has identifier from a Nilo environment that is not the current environment.`                                             | O payload traz um identificador Nilo gerado em outro ambiente |
| `400`  | `structure`     | o campo recusado            | mensagem da validação FHIR                                                                                                         | O payload não é um `PlanDefinition` válido                    |
| `400`  | `exception`     | —                           | `HTTPBadRequest: …`                                                                                                                | O `name` está ausente, ou passa de 100 caracteres             |
| `409`  | `conflict`      | `PlanDefinition.url`        | `A PlanDefinition with the URL '…' already exists.`                                                                                | A `url` já pertence a outra diretriz                          |
| `409`  | `conflict`      | `PlanDefinition.url`        | `The URL references PlanDefinition '…' while the identifiers reference PlanDefinition '…'. Both must reference the same resource.` | A `url` e o `identifier` apontam para diretrizes diferentes   |

### Response (200)

```json
{
  "resourceType": "PlanDefinition",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--care-line",
      "value": "412",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/diretriz/",
      "value": "DM2",
      "use": "usual"
    }
  ],
  "name": "Acompanhamento de diabetes tipo 2",
  "status": "active",
  "id": "5d81f3b6-04e7-4a29-9c50-b6127ea38d41",
  "meta": {
    "lastUpdated": "2026-03-02T09:41:55.318000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "description": "Linha de cuidado para pacientes com diabetes tipo 2 em acompanhamento contínuo.",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/plan-definition-type",
        "code": "order-set",
        "display": "Order Set"
      }
    ]
  },
  "url": "https://www.acmesaude.com.br/diretrizes/diabetes-tipo-2",
  "effectivePeriod": {
    "start": "2025-01-01T00:00:00+00:00"
  }
}
```

> **Warning**
>
> A linha `exception` não é uma validação desta API — é a recusa da própria plataforma,
> repassada como está. Ela sai **sem `expression`** e com uma mensagem de erro de linguagem, que
> inclui o endereço interno chamado. **Nada disso é contrato:** não interprete o texto e não o
> exiba para o usuário final.

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