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

# Plano de saúde

> Consultar o catálogo de planos de saúde do seu ambiente e alterar o nome de um plano, no padrão FHIR InsurancePlan.

Um **plano de saúde** aqui é uma entrada no catálogo do seu ambiente: o convênio, o plano ou
o benefício que custeia o atendimento de um paciente. Cada
[cobertura](/guia/recursos/coverage) aponta para um deles, e é o nome cadastrado aqui que a
equipe vê no campo **Plano de saúde** da ficha do paciente.

No FHIR o recurso é o
[`InsurancePlan`](https://hl7.org/fhir/R4/insuranceplan.html). Na prática ele serve para duas
coisas: **descobrir o id do plano** que vai na cobertura, e **corrigir o nome** de um plano
que já existe.

> **Warning**
>
> **Planos novos não são criados por esta API.** O catálogo é montado na implantação do seu
> ambiente, junto com o time da Nilo. O `POST` desta página encontra um plano pelo `identifier`
> e altera o nome dele; um `identifier` que não corresponda a nenhum plano existente **não cria
> nada** — a chamada é recusada. Para incluir um plano no catálogo, fale com o **Suporte**.

## Campos

| Campo          | Obrigatório | O que significa                                                        | No Nilo Care                                 |
| -------------- | ----------- | ---------------------------------------------------------------------- | -------------------------------------------- |
| `resourceType` | **sim**     | Constante `InsurancePlan`                                              | —                                            |
| `identifier`   | **sim**     | Identificador do plano. É por ele que a API encontra o plano a alterar | —                                            |
| `name`         | **sim**     | Nome do plano, com no máximo **200 caracteres**                        | **Plano de saúde**, na cobertura do paciente |
| `status`       | não         | Só resposta: `active` num plano em uso, `retired` num plano desativado | —                                            |
| `id` · `meta`  | não         | Só resposta: identificador Nilo FHIR do plano e metadados da gravação  | —                                            |

> **Warning**
>
> **`status` não é gravável.** Ativar ou desativar um plano é decisão da plataforma, e enviar
> `status` no payload não muda nada — o valor que volta continua sendo o que a plataforma
> calcula. Não há como aposentar um plano por esta API.

> **Note**
>
> O `status` é **informativo, e não restringe nada**: um plano `retired` continua aparecendo na
> busca e continua sendo aceito em `Coverage.class[0].value`. Se a sua integração precisa oferecer
> só planos vigentes, filtre por `status=active` do seu lado — a plataforma não recusa o outro.

### Campos que a Nilo não usa

O `InsurancePlan` canônico traz muito mais do que esta integração lê: `type`, `alias`,
`period`, `ownedBy`, `administeredBy`, `coverageArea`, `contact`, `endpoint`, `network`,
`coverage` e `plan`. Nenhum deles é lido, e por isso nenhum aparece na referência do recurso.

> **Note**
>
> A referência lista só os campos suportados, e é assim que ela deve ser lida: **o que mandar na
> escrita**. A API em si **não recusa** quem manda os outros — eles ficam guardados no recurso e
> voltam nas leituras seguintes, sem nunca terem significado nada para a plataforma. Se o seu
> validador for estrito contra a referência, uma resposta assim vai parecer inválida; o remédio é
> não enviá-los.

## Descobrir o id de um plano

Este é o uso principal do recurso. A cobertura de um paciente identifica o plano por
`class[0].value`, e o valor esperado ali é o **`value` do identificador Nilo do plano** — o
que vem no `system` `…/NamingSystem/care-api--insurance-v2`.

### Request

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

**`Busca com resultados`**

```curl Busca com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     --data-urlencode identifier=https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2|2481 \
     -d name=Ambulatorial \
     -d status=active
```

**`Busca com resultados`**

```python Busca com resultados
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","identifier":"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2|2481","name":"Ambulatorial","status":"active"}

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/InsurancePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fcare-api--insurance-v2%7C2481&name=Ambulatorial&status=active';
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/InsurancePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fcare-api--insurance-v2%7C2481&name=Ambulatorial&status=active"

	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/InsurancePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fcare-api--insurance-v2%7C2481&name=Ambulatorial&status=active")

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/InsurancePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fcare-api--insurance-v2%7C2481&name=Ambulatorial&status=active")
  .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/InsurancePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fcare-api--insurance-v2%7C2481&name=Ambulatorial&status=active', [
  '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/InsurancePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fcare-api--insurance-v2%7C2481&name=Ambulatorial&status=active");
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/InsurancePlan?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fcare-api--insurance-v2%7C2481&name=Ambulatorial&status=active")! 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/InsurancePlan/61a4c8d2-9e35-47bb-a0f1-2c7d5e8b3f90",
      "resource": {
        "resourceType": "InsurancePlan",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
            "value": "2481",
            "use": "usual"
          }
        ],
        "name": "Acme Saúde Ambulatorial",
        "id": "61a4c8d2-9e35-47bb-a0f1-2c7d5e8b3f90",
        "status": "active"
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan/0d7f3e51-8c26-4a90-bb14-7e5a1c9d2408",
      "resource": {
        "resourceType": "InsurancePlan",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
            "value": "1907",
            "use": "usual"
          }
        ],
        "name": "Acme Saúde Básico (encerrado)",
        "id": "0d7f3e51-8c26-4a90-bb14-7e5a1c9d2408",
        "status": "retired"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

No exemplo acima, uma cobertura no plano *Acme Saúde Ambulatorial* levaria:

```json
"class": [
  {
    "type": { "text": "plan" },
    "value": "2481"
  }
]
```

> **Note**
>
> Quem não quer carregar o id Nilo do plano pode usar a extensão `insurance-plan` da cobertura,
> que aceita **qualquer** identificador de um plano já cadastrado — inclusive o do seu próprio
> sistema, se ele tiver sido gravado no plano. Veja
> [Cobertura](/guia/recursos/coverage) e [Extensões](/guia/conceitos/extensoes).

> **Note**
>
> Os planos cadastrados na implantação trazem **apenas** o identificador Nilo. Um plano só passa
> a ter a sua chave se você a tiver gravado nele por integração — e como esta API não cria
> planos, isso só vale para os que já existiam quando você mandou o `POST`.

## Buscar

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. Trate a ausência de resultados pela lista
vazia, não esperando um `404`.

### Response (200)

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

### Parâmetros de busca suportados

| Nome           | Tipo                                                 | Descrição                                                          | Expressão                  |
| -------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | -------------------------- |
| `identifier`   | [token](https://hl7.org/fhir/R4/search.html#token)   | Identificador do plano, em `system\|value`                         | `InsurancePlan.identifier` |
| `name`         | [string](https://hl7.org/fhir/R4/search.html#string) | Parte do nome do plano                                             | `InsurancePlan.name`       |
| `status`       | [token](https://hl7.org/fhir/R4/search.html#token)   | `active` ou `retired`                                              | `InsurancePlan.status`     |
| `_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 `InsurancePlan` existem e **não encontram nada** aqui,
> porque a Nilo não preenche o campo correspondente: `type`, `owned-by`, `administered-by`,
> `endpoint` e os de endereço. A exceção é o campo que **você mesmo** tenha enviado: ele fica no
> recurso e passa a ser encontrável — mais um motivo para omitir o que a plataforma não usa.

Os catálogos costumam ser pequenos, e a chamada mais comum é listar tudo:

```bash
curl --request GET \
  --url 'https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan' \
  --header 'x-api-key: SUA_API_KEY'
```

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

> **Note**
>
> Um plano antigo, que ninguém tenha tocado desde que a sua integração começou, pode não aparecer
> na lista — e, não aparecendo, também não pode ser renomeado, porque o `POST` não consegue
> encontrá-lo. Se você espera um plano e ele não vem, peça ao **Suporte**: a busca não é um
> inventário garantido do catálogo.

## Renomear um plano

### Request

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

**`Renomear um plano`**

```curl Renomear um plano
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "InsurancePlan",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
      "value": "2481",
      "use": "usual"
    }
  ],
  "name": "Acme Saúde Ambulatorial Plus"
}'
```

**`Renomear um plano`**

```python Renomear um plano
import requests

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

payload = {
    "resourceType": "InsurancePlan",
    "identifier": [
        {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
            "value": "2481",
            "use": "usual"
        }
    ],
    "name": "Acme Saúde Ambulatorial Plus"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Renomear um plano`**

```javascript Renomear um plano
const url = 'https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"InsurancePlan","identifier":[{"system":"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2","value":"2481","use":"usual"}],"name":"Acme Saúde Ambulatorial Plus"}'
};

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

**`Renomear um plano`**

```go Renomear um plano
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"InsurancePlan\",\n  \"identifier\": [\n    {\n      \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2\",\n      \"value\": \"2481\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acme Saúde Ambulatorial Plus\"\n}")

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

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

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

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

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

}
```

**`Renomear um plano`**

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

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

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\": \"InsurancePlan\",\n  \"identifier\": [\n    {\n      \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2\",\n      \"value\": \"2481\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acme Saúde Ambulatorial Plus\"\n}"

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

**`Renomear um plano`**

```java Renomear um 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/InsurancePlan")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"InsurancePlan\",\n  \"identifier\": [\n    {\n      \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2\",\n      \"value\": \"2481\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acme Saúde Ambulatorial Plus\"\n}")
  .asString();
```

**`Renomear um plano`**

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan', [
  'body' => '{
  "resourceType": "InsurancePlan",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
      "value": "2481",
      "use": "usual"
    }
  ],
  "name": "Acme Saúde Ambulatorial Plus"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Renomear um plano`**

```csharp Renomear um plano
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"InsurancePlan\",\n  \"identifier\": [\n    {\n      \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2\",\n      \"value\": \"2481\",\n      \"use\": \"usual\"\n    }\n  ],\n  \"name\": \"Acme Saúde Ambulatorial Plus\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Renomear um plano`**

```swift Renomear um plano
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "InsurancePlan",
  "identifier": [
    [
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
      "value": "2481",
      "use": "usual"
    ]
  ],
  "name": "Acme Saúde Ambulatorial Plus"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan")! 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": "InsurancePlan",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
      "value": "2481",
      "use": "usual"
    }
  ],
  "name": "Acme Saúde Ambulatorial Plus",
  "id": "61a4c8d2-9e35-47bb-a0f1-2c7d5e8b3f90",
  "meta": {
    "lastUpdated": "2026-08-24T12:04:18.911000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "status": "active"
}
```

O `name` é o único dado gravado. `status` e qualquer outro campo do payload são descartados.

> **Warning**
>
> **Renomear muda o nome em todas as coberturas que apontam para o plano.** O plano é um só,
> compartilhado por todos os pacientes que o usam — não há um nome por paciente. Um erro de
> digitação aqui aparece na ficha de todo mundo.

> **Note**
>
> O `identifier` que localiza o plano pode ser o identificador Nilo dele ou uma chave sua que
> já esteja gravada no plano. Mandando uma chave nova junto com o identificador Nilo, as duas
> passam a valer para aquele plano — é assim que você anexa a sua própria chave a um plano do
> catálogo.

## Ler por ID

### Request

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

**`Plano encontrado`**

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

**`Plano encontrado`**

```python Plano encontrado
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan/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/InsurancePlan/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/InsurancePlan/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/InsurancePlan/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/InsurancePlan/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/InsurancePlan/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/InsurancePlan/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/InsurancePlan/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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

dataTask.resume()
```

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

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/InsurancePlan/61a4c8d2-9e35-47bb-a0f1-2c7d5e8b3f90",
  "resource": {
    "resourceType": "InsurancePlan",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
        "value": "2481",
        "use": "usual"
      }
    ],
    "name": "Acme Saúde Ambulatorial",
    "id": "61a4c8d2-9e35-47bb-a0f1-2c7d5e8b3f90",
    "meta": {
      "lastUpdated": "2026-08-24T12:04:18.911000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "status": "active"
  },
  "search": {
    "mode": "match"
  }
}
```

## Valores aceitos

### `status`

Dois: `active` e `retired`. São só resposta — a plataforma os calcula, e nenhum dos dois pode
ser enviado para mudar a situação de um plano. Os outros valores do FHIR R4 (`draft`,
`unknown`) não são usados.

Nenhum dos dois bloqueia nada: um plano `retired` continua listado e continua servindo a uma
cobertura nova. O valor é um sinal de catálogo, não uma regra de negócio aplicada pela API.

## Efeitos colaterais

> **Note**
>
> Renomear um plano **não muda nenhuma cobertura**: as coberturas continuam apontando para o
> mesmo plano, e o Nilo Care passa a exibir o nome novo em todas elas. Nenhum paciente é afetado
> além do rótulo.

> **Warning**
>
> **Na API, porém, o nome novo não alcança as coberturas já gravadas.** A leitura de uma
> [cobertura](/guia/recursos/coverage) traz em `class[0].name` o nome que o plano tinha quando
> aquela cobertura foi gravada pela última vez, e renomear o plano não reescreve as coberturas.
> O `class[0].name` só acompanha o nome novo depois que a cobertura for gravada de novo, por
> qualquer motivo.
>
> Para o nome atual de um plano, leia o `InsurancePlan` — nunca o `class[0].name` de uma
> cobertura. O `class[0].value`, esse sim, continua correto e é o que liga os dois.

> **Note**
>
> Este endpoint nunca responde `204`: não há remoção de plano 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.

| `code`          | `expression`               | Mensagem                                                                                                     | Quando                                                                                                       |
| --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `required`      | `InsurancePlan.identifier` | `Field is required`                                                                                          | O payload não tem `identifier`                                                                               |
| `business-rule` | `InsurancePlan.identifier` | `Unable to use any of the provided identifiers to match an existing resource, which can lead to duplicates.` | Há `identifier`, mas nenhum utilizável — falta `system` ou falta `value`                                     |
| `structure`     | —                          | `Resource has identifier from a Nilo environment that is not the current environment.`                       | O payload traz um identificador Nilo gerado em outro ambiente                                                |
| `structure`     | o campo recusado           | mensagem da validação FHIR                                                                                   | O payload não é um `InsurancePlan` válido                                                                    |
| `exception`     | —                          | `HTTPServerError: [Server Error] 500 for …` ou `HTTPBadRequest: …`                                           | O `identifier` não corresponde a nenhum plano do catálogo, o `name` está ausente, ou passa de 200 caracteres |

### Response (200)

```json
{
  "resourceType": "InsurancePlan",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/care-api--insurance-v2",
      "value": "2481",
      "use": "usual"
    }
  ],
  "name": "Acme Saúde Ambulatorial Plus",
  "id": "61a4c8d2-9e35-47bb-a0f1-2c7d5e8b3f90",
  "meta": {
    "lastUpdated": "2026-08-24T12:04:18.911000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "status": "active"
}
```

> **Warning**
>
> A última linha não é uma validação desta API — é a recusa da própria plataforma, repassada
> como está. Ela sai com `code: exception`, **sem `expression`**, e com uma mensagem de erro de
> linguagem, que inclui o endereço interno chamado. **Nada disso é contrato:** não tente
> interpretar o texto, não o exiba para o usuário final e não o registre em log de longa duração.
> Trate `code: exception` como "payload recusado, motivo não classificado" e confira antes, com
> um `GET`, se o plano que você quer alterar existe.

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