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

# Cobertura de saúde

> Cadastrar, atualizar e buscar coberturas de saúde no padrão FHIR Coverage.

O [`Coverage`](https://hl7.org/fhir/R4/coverage.html) representa o vínculo do paciente com
um plano de saúde, convênio ou benefício — quem custeia o atendimento, com que carteirinha
e por quanto tempo. Um paciente pode ter várias coberturas ao mesmo tempo, e a ordem entre
elas diz qual usar primeiro.

A cobertura não vive sozinha: ela sempre aponta para um `Patient` já cadastrado, e o plano
que ela nomeia é um `InsurancePlan` do catálogo do seu care provider. Nenhum dos dois é
criado pela escrita da cobertura.

## Campos

A coluna **No NiloCare** traz o rótulo com que o dado aparece para a equipe de cuidado. São
rótulos, não caminhos de navegação: a tela pode ser reorganizada, o rótulo é o que permite
conferir se o dado chegou onde você esperava.

| Campo                        | Obrigatório             | O que significa                                                                  | No NiloCare                                          |
| ---------------------------- | ----------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `identifier`                 | **sim**, ao menos um    | Chaves da cobertura. É por aqui que a API decide entre criar e atualizar         | —                                                    |
| `beneficiary`                | **sim**                 | Paciente coberto. Aponta para um `Patient` que já existe                         | (a cobertura fica na ficha dele)                     |
| `relationship`               | **sim**                 | Relação do beneficiário com o titular da carteirinha, em `coding[0].code`        | **Relação com titular**                              |
| `status`                     | **sim**                 | Situação da cobertura                                                            | **Situação**                                         |
| `payor`                      | **sim**, com ressalva 1 | Entidade pagadora. Exigido pelo FHIR, mas o conteúdo é descartado                | —                                                    |
| `subscriberId`               | **sim**, com ressalva 2 | Carteirinha do **titular**. Num beneficiário titular, é a carteirinha dele mesmo | **Nº da carteirinha** / **Nº da cart. do titular**   |
| `dependent`                  | **sim**, com ressalva 2 | Carteirinha do beneficiário quando ele é **dependente**                          | **Nº da carteirinha**                                |
| `class[0].value`             | **sim**, com ressalva 2 | Id do plano no catálogo do seu care provider                                     | **Plano de saúde**                                   |
| `class[0].name`              | não                     | Nome do plano. Informativo — não localiza o plano                                | **Plano de saúde**                                   |
| `policyHolder.display`       | não                     | Estipulante: quem contratou a apólice. Texto livre                               | **Estipulante**                                      |
| `period.start`               | não                     | Início de vigência                                                               | **Início de vigência**                               |
| `period.end`                 | não                     | Fim de vigência                                                                  | **Fim de vigência**                                  |
| `order`                      | não                     | Prioridade entre as coberturas do paciente, começando em `1`                     | ordem dos cartões **Cobertura de saúde 1**, **2**, … |
| `extension` `insurance-plan` | não                     | Plano por identificador, alternativa ao `class`                                  | **Plano de saúde**                                   |

1 `payor` é obrigatório na especificação FHIR R4 e um payload sem ele é recusado,
mas o valor enviado não é gravado: a leitura devolve sempre `Operadora`.\

2 Nenhum destes três é obrigatório isoladamente, mas a cobertura precisa de **um
plano ou uma carteirinha** — os dois vazios recusam a escrita. Qual dos dois campos de
carteirinha usar depende do `relationship`; veja
[Titular e dependente](#titular-e-dependente).

A URL completa da extensão está em [Extensões](/guia/conceitos/extensoes) — nesta página ela
aparece só pelo nome final.

> **Note**
>
> `Relação com titular` aparece como opcional no formulário do NiloCare, mas `relationship` é
> **obrigatório** na API: sem ele a escrita é recusada. Se a sua carga não distingue titular de
> dependente, envie `self`.

### Campos do `Coverage` que a Nilo não usa

O `Coverage` canônico tem campos que esta integração não lê nem grava: `type`, `subscriber`,
`network`, `contract`, `costToBeneficiary` e `subrogation`. Eles ficam fora da referência de
propósito. Enviá-los não é erro — o valor é gravado no recurso FHIR e volta nas leituras
seguintes —, mas nada no NiloCare passa a exibi-los.

## Cadastrar ou atualizar

Não há endpoint separado para criar e atualizar. O mesmo `POST` faz os dois, e quem decide é o
`identifier`: se já existir uma cobertura com aquele par `system` + `value`, ela é atualizada;
se não existir, é criada.

### Request

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

**`Cobertura de titular`**

```curl Cobertura de titular
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Coverage \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "order": 1,
  "period": {
    "end": "2023-05-23",
    "start": "2022-05-23"
  },
  "policyHolder": {
    "display": "Acme Indústria S.A."
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}'
```

**`Cobertura de titular`**

```python Cobertura de titular
import requests

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

payload = {
    "beneficiary": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    },
    "payor": [{ "display": "Operadora" }],
    "resourceType": "Coverage",
    "status": "active",
    "class": [
        {
            "type": { "text": "plan" },
            "value": "42",
            "name": "Unimed com coparticipação SP/SP"
        }
    ],
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/cobertura/",
            "value": "COB-88231",
            "use": "official"
        }
    ],
    "order": 1,
    "period": {
        "end": "2023-05-23",
        "start": "2022-05-23"
    },
    "policyHolder": { "display": "Acme Indústria S.A." },
    "relationship": { "coding": [{ "code": "self" }] },
    "subscriberId": "1352743"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cobertura de titular`**

```javascript Cobertura de titular
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Coverage';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"beneficiary":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"},"payor":[{"display":"Operadora"}],"resourceType":"Coverage","status":"active","class":[{"type":{"text":"plan"},"value":"42","name":"Unimed com coparticipação SP/SP"}],"identifier":[{"system":"https://www.acmesaude.com.br/integracao/cobertura/","value":"COB-88231","use":"official"}],"order":1,"period":{"end":"2023-05-23","start":"2022-05-23"},"policyHolder":{"display":"Acme Indústria S.A."},"relationship":{"coding":[{"code":"self"}]},"subscriberId":"1352743"}'
};

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

**`Cobertura de titular`**

```go Cobertura de titular
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88231\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 1,\n  \"period\": {\n    \"end\": \"2023-05-23\",\n    \"start\": \"2022-05-23\"\n  },\n  \"policyHolder\": {\n    \"display\": \"Acme Indústria S.A.\"\n  },\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\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))

}
```

**`Cobertura de titular`**

```ruby Cobertura de titular
require 'uri'
require 'net/http'

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

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  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88231\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 1,\n  \"period\": {\n    \"end\": \"2023-05-23\",\n    \"start\": \"2022-05-23\"\n  },\n  \"policyHolder\": {\n    \"display\": \"Acme Indústria S.A.\"\n  },\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\n}"

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

**`Cobertura de titular`**

```java Cobertura de titular
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/Coverage")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88231\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 1,\n  \"period\": {\n    \"end\": \"2023-05-23\",\n    \"start\": \"2022-05-23\"\n  },\n  \"policyHolder\": {\n    \"display\": \"Acme Indústria S.A.\"\n  },\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\n}")
  .asString();
```

**`Cobertura de titular`**

```php Cobertura de titular
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Coverage', [
  'body' => '{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "order": 1,
  "period": {
    "end": "2023-05-23",
    "start": "2022-05-23"
  },
  "policyHolder": {
    "display": "Acme Indústria S.A."
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cobertura de titular`**

```csharp Cobertura de titular
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Coverage");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88231\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 1,\n  \"period\": {\n    \"end\": \"2023-05-23\",\n    \"start\": \"2022-05-23\"\n  },\n  \"policyHolder\": {\n    \"display\": \"Acme Indústria S.A.\"\n  },\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cobertura de titular`**

```swift Cobertura de titular
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "beneficiary": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ],
  "payor": [["display": "Operadora"]],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    [
      "type": ["text": "plan"],
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    ]
  ],
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    ]
  ],
  "order": 1,
  "period": [
    "end": "2023-05-23",
    "start": "2022-05-23"
  ],
  "policyHolder": ["display": "Acme Indústria S.A."],
  "relationship": ["coding": [["code": "self"]]],
  "subscriberId": "1352743"
] as [String : Any]

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

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

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

dataTask.resume()
```

A resposta devolve o recurso como ficou gravado:

### Response (200)

```json
{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "id": "7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--coverage",
      "value": "918233",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "meta": {
    "lastUpdated": "2026-08-06T13:04:12.905000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "order": 1,
  "period": {
    "end": "2023-05-23",
    "start": "2022-05-23"
  },
  "policyHolder": {
    "display": "Acme Indústria S.A."
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}
```

Guarde o `id`: é por ele que se faz a leitura direta da cobertura. A resposta traz também o
identificador Nilo da cobertura (`…/NamingSystem/hippocrates-api--coverage`) ao lado do seu —
os dois servem para buscar, e o seu continua sendo o único que você precisa guardar.

> **Warning**
>
> A atualização de cobertura **substitui**, não complementa. Diferente do `Patient`, um campo
> omitido **não** preserva o valor atual — a API grava a cobertura com o que o payload traz, e
> o que ficou de fora é enviado vazio. Para mudar só a vigência, reenvie o payload inteiro com
> a vigência nova, não apenas o `period`.

> **Note**
>
> Ao menos um `identifier` é obrigatório. Não havendo casamento por identificador, a API ainda
> tenta encontrar a cobertura pela **chave de negócio** antes de criar uma nova — veja
> [Como a API evita duplicatas](#como-a-api-evita-duplicatas).

### Titular e dependente

`subscriberId` e `dependent` **trocam de sentido** conforme o `relationship`. É a fonte de
erro mais comum neste recurso.

| `relationship` | `subscriberId`              | `dependent`                      |
| -------------- | --------------------------- | -------------------------------- |
| `self`         | carteirinha do beneficiário | não use — a leitura devolve nulo |
| qualquer outro | carteirinha do **titular**  | carteirinha do beneficiário      |

Ou seja: a carteirinha do paciente que você está cadastrando vai em `subscriberId` quando ele
é o titular e em `dependent` quando não é.

### Request

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

**`Cobertura de dependente`**

```curl Cobertura de dependente
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Coverage \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823710",
      "use": "usual"
    },
    "type": "Patient"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "dependent": "1352744",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88232",
      "use": "official"
    }
  ],
  "order": 2,
  "relationship": {
    "coding": [
      {
        "code": "child"
      }
    ]
  },
  "subscriberId": "1352743"
}'
```

**`Cobertura de dependente`**

```python Cobertura de dependente
import requests

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

payload = {
    "beneficiary": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823710",
            "use": "usual"
        },
        "type": "Patient"
    },
    "payor": [{ "display": "Operadora" }],
    "resourceType": "Coverage",
    "status": "active",
    "class": [
        {
            "type": { "text": "plan" },
            "value": "42",
            "name": "Unimed com coparticipação SP/SP"
        }
    ],
    "dependent": "1352744",
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/cobertura/",
            "value": "COB-88232",
            "use": "official"
        }
    ],
    "order": 2,
    "relationship": { "coding": [{ "code": "child" }] },
    "subscriberId": "1352743"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Cobertura de dependente`**

```javascript Cobertura de dependente
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Coverage';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"beneficiary":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823710","use":"usual"},"type":"Patient"},"payor":[{"display":"Operadora"}],"resourceType":"Coverage","status":"active","class":[{"type":{"text":"plan"},"value":"42","name":"Unimed com coparticipação SP/SP"}],"dependent":"1352744","identifier":[{"system":"https://www.acmesaude.com.br/integracao/cobertura/","value":"COB-88232","use":"official"}],"order":2,"relationship":{"coding":[{"code":"child"}]},"subscriberId":"1352743"}'
};

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

**`Cobertura de dependente`**

```go Cobertura de dependente
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823710\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"dependent\": \"1352744\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88232\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 2,\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"child\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\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))

}
```

**`Cobertura de dependente`**

```ruby Cobertura de dependente
require 'uri'
require 'net/http'

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

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  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823710\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"dependent\": \"1352744\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88232\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 2,\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"child\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\n}"

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

**`Cobertura de dependente`**

```java Cobertura de dependente
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/Coverage")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823710\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"dependent\": \"1352744\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88232\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 2,\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"child\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\n}")
  .asString();
```

**`Cobertura de dependente`**

```php Cobertura de dependente
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Coverage', [
  'body' => '{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823710",
      "use": "usual"
    },
    "type": "Patient"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "dependent": "1352744",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88232",
      "use": "official"
    }
  ],
  "order": 2,
  "relationship": {
    "coding": [
      {
        "code": "child"
      }
    ]
  },
  "subscriberId": "1352743"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cobertura de dependente`**

```csharp Cobertura de dependente
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Coverage");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823710\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"class\": [\n    {\n      \"type\": {\n        \"text\": \"plan\"\n      },\n      \"value\": \"42\",\n      \"name\": \"Unimed com coparticipação SP/SP\"\n    }\n  ],\n  \"dependent\": \"1352744\",\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88232\",\n      \"use\": \"official\"\n    }\n  ],\n  \"order\": 2,\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"child\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352743\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Cobertura de dependente`**

```swift Cobertura de dependente
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "beneficiary": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823710",
      "use": "usual"
    ],
    "type": "Patient"
  ],
  "payor": [["display": "Operadora"]],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    [
      "type": ["text": "plan"],
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    ]
  ],
  "dependent": "1352744",
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88232",
      "use": "official"
    ]
  ],
  "order": 2,
  "relationship": ["coding": [["code": "child"]]],
  "subscriberId": "1352743"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Coverage")! 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**
>
> Trocar os dois campos de lugar não gera erro: a escrita passa e a carteirinha fica gravada no
> campo errado. Confira o `relationship` antes de montar a carga.

### Plano de saúde

O plano vai no **primeiro** item de `class`, com o id do plano em `value`. O `name` é
informativo: quem localiza o plano é o `value`.

> **Warning**
>
> A API lê `class[0]` — o primeiro item da lista, sem olhar o `type`. Se o seu payload mandar
> outra classificação antes do plano, é o `value` dela que será tomado como id do plano. Envie o
> plano como primeiro item, ou envie só ele.

Para descobrir os ids disponíveis, liste os planos do seu ambiente e use o `value` do
identificador Nilo (`…/NamingSystem/care-api--insurance-v2`) — veja
[Plano de saúde](/guia/recursos/insuranceplan):

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

Quem não quer carregar o id Nilo do plano pode usar a extensão `insurance-plan`, que aceita
**qualquer** identificador de um `InsurancePlan` já cadastrado — inclusive o do seu próprio
sistema:

### Request

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

**`Plano pelo identificador do seu sistema`**

```curl Plano pelo identificador do seu sistema
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/Coverage \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823711",
      "use": "usual"
    },
    "type": "Patient"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan",
      "valueIdentifier": {
        "system": "https://www.acmesaude.com.br/integracao/plano/",
        "use": "usual",
        "value": "unimed-coparticipacao-sp"
      }
    }
  ],
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88233",
      "use": "official"
    }
  ],
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352745"
}'
```

**`Plano pelo identificador do seu sistema`**

```python Plano pelo identificador do seu sistema
import requests

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

payload = {
    "beneficiary": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823711",
            "use": "usual"
        },
        "type": "Patient"
    },
    "payor": [{ "display": "Operadora" }],
    "resourceType": "Coverage",
    "status": "active",
    "extension": [
        {
            "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan",
            "valueIdentifier": {
                "system": "https://www.acmesaude.com.br/integracao/plano/",
                "use": "usual",
                "value": "unimed-coparticipacao-sp"
            }
        }
    ],
    "identifier": [
        {
            "system": "https://www.acmesaude.com.br/integracao/cobertura/",
            "value": "COB-88233",
            "use": "official"
        }
    ],
    "relationship": { "coding": [{ "code": "self" }] },
    "subscriberId": "1352745"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Plano pelo identificador do seu sistema`**

```javascript Plano pelo identificador do seu sistema
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Coverage';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"beneficiary":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823711","use":"usual"},"type":"Patient"},"payor":[{"display":"Operadora"}],"resourceType":"Coverage","status":"active","extension":[{"url":"https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan","valueIdentifier":{"system":"https://www.acmesaude.com.br/integracao/plano/","use":"usual","value":"unimed-coparticipacao-sp"}}],"identifier":[{"system":"https://www.acmesaude.com.br/integracao/cobertura/","value":"COB-88233","use":"official"}],"relationship":{"coding":[{"code":"self"}]},"subscriberId":"1352745"}'
};

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

**`Plano pelo identificador do seu sistema`**

```go Plano pelo identificador do seu sistema
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823711\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"extension\": [\n    {\n      \"url\": \"https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan\",\n      \"valueIdentifier\": {\n        \"system\": \"https://www.acmesaude.com.br/integracao/plano/\",\n        \"use\": \"usual\",\n        \"value\": \"unimed-coparticipacao-sp\"\n      }\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88233\",\n      \"use\": \"official\"\n    }\n  ],\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352745\"\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))

}
```

**`Plano pelo identificador do seu sistema`**

```ruby Plano pelo identificador do seu sistema
require 'uri'
require 'net/http'

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

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  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823711\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"extension\": [\n    {\n      \"url\": \"https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan\",\n      \"valueIdentifier\": {\n        \"system\": \"https://www.acmesaude.com.br/integracao/plano/\",\n        \"use\": \"usual\",\n        \"value\": \"unimed-coparticipacao-sp\"\n      }\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88233\",\n      \"use\": \"official\"\n    }\n  ],\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352745\"\n}"

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

**`Plano pelo identificador do seu sistema`**

```java Plano pelo identificador do seu sistema
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/Coverage")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823711\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"extension\": [\n    {\n      \"url\": \"https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan\",\n      \"valueIdentifier\": {\n        \"system\": \"https://www.acmesaude.com.br/integracao/plano/\",\n        \"use\": \"usual\",\n        \"value\": \"unimed-coparticipacao-sp\"\n      }\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88233\",\n      \"use\": \"official\"\n    }\n  ],\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352745\"\n}")
  .asString();
```

**`Plano pelo identificador do seu sistema`**

```php Plano pelo identificador do seu sistema
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/Coverage', [
  'body' => '{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823711",
      "use": "usual"
    },
    "type": "Patient"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "extension": [
    {
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan",
      "valueIdentifier": {
        "system": "https://www.acmesaude.com.br/integracao/plano/",
        "use": "usual",
        "value": "unimed-coparticipacao-sp"
      }
    }
  ],
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88233",
      "use": "official"
    }
  ],
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352745"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Plano pelo identificador do seu sistema`**

```csharp Plano pelo identificador do seu sistema
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Coverage");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"beneficiary\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823711\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"payor\": [\n    {\n      \"display\": \"Operadora\"\n    }\n  ],\n  \"resourceType\": \"Coverage\",\n  \"status\": \"active\",\n  \"extension\": [\n    {\n      \"url\": \"https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan\",\n      \"valueIdentifier\": {\n        \"system\": \"https://www.acmesaude.com.br/integracao/plano/\",\n        \"use\": \"usual\",\n        \"value\": \"unimed-coparticipacao-sp\"\n      }\n    }\n  ],\n  \"identifier\": [\n    {\n      \"system\": \"https://www.acmesaude.com.br/integracao/cobertura/\",\n      \"value\": \"COB-88233\",\n      \"use\": \"official\"\n    }\n  ],\n  \"relationship\": {\n    \"coding\": [\n      {\n        \"code\": \"self\"\n      }\n    ]\n  },\n  \"subscriberId\": \"1352745\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Plano pelo identificador do seu sistema`**

```swift Plano pelo identificador do seu sistema
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "beneficiary": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823711",
      "use": "usual"
    ],
    "type": "Patient"
  ],
  "payor": [["display": "Operadora"]],
  "resourceType": "Coverage",
  "status": "active",
  "extension": [
    [
      "url": "https://landing-zone-api.nilo.services/fhir/resources/StructureDefinition/insurance-plan",
      "valueIdentifier": [
        "system": "https://www.acmesaude.com.br/integracao/plano/",
        "use": "usual",
        "value": "unimed-coparticipacao-sp"
      ]
    ]
  ],
  "identifier": [
    [
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88233",
      "use": "official"
    ]
  ],
  "relationship": ["coding": [["code": "self"]]],
  "subscriberId": "1352745"
] as [String : Any]

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

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

> **Note**
>
> Enviando as duas formas ao mesmo tempo, `class` vence e a extensão é ignorada. E a extensão
> não volta na leitura: a resposta traz o plano em `class[0]`. Reenviar um recurso exatamente
> como ele veio numa resposta funciona — mas pelo `class`, não pela extensão.

> **Warning**
>
> **`class[0].name` é uma fotografia, não o nome atual do plano.** Ele guarda o nome que o plano
> tinha quando esta cobertura foi gravada pela última vez. Se o plano for renomeado depois, a
> cobertura continua devolvendo o nome antigo até ser gravada de novo, por qualquer motivo.
>
> Quem localiza o plano é o `class[0].value`, e esse continua correto. Para o nome atual, leia o
> [plano de saúde](/guia/recursos/insuranceplan) — não o `name` da cobertura.

### Vigência

`period.start` e `period.end` são datas. Envie-as como data pura (`YYYY-MM-DD`): o NiloCare
guarda só a data, e uma data com hora é convertida para o fuso da Nilo antes de a data ser
extraída — o que pode deslocar o dia em um valor próximo da meia-noite.

### Ordem

`order` é a prioridade de uso entre as coberturas do paciente e começa em **1**: `order: 1` é
a primeira cobertura, a que aparece como **Cobertura de saúde 1** na ficha. `order: 0` é
recusado pela validação FHIR, que exige um inteiro positivo.

> **Note**
>
> Uma cobertura gravada sem `order` é lida como `order: 1`. Com mais de uma cobertura por
> paciente, mande o `order` de todas explicitamente — do contrário todas voltam como primeira.

## Buscar

### Request

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

**`Busca de coberturas com resultados`**

```curl Busca de coberturas com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/Coverage \
     -H "x-api-key: <apiKey>" \
     -d _lastUpdated=eq2013-01-14 \
     --data-urlencode beneficiary=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4 \
     -d class-type=plan \
     -d class-value=42 \
     -d dependent=1352744 \
     --data-urlencode identifier=https://www.acmesaude.com.br/integracao/cobertura/|COB-88231 \
     --data-urlencode patient=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4 \
     --data-urlencode patient:identifier=https://www.acmesaude.com.br/integracao/paciente/|507823709 \
     --data-urlencode policy-holder=Organization/6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60 \
     -d status=active
```

**`Busca de coberturas com resultados`**

```python Busca de coberturas com resultados
import requests

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

querystring = {"_lastUpdated":"[\"eq2013-01-14\"]","beneficiary":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4","class-type":"plan","class-value":"42","dependent":"1352744","identifier":"https://www.acmesaude.com.br/integracao/cobertura/|COB-88231","patient":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4","patient:identifier":"https://www.acmesaude.com.br/integracao/paciente/|507823709","policy-holder":"Organization/6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60","status":"active"}

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

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

print(response.json())
```

**`Busca de coberturas com resultados`**

```javascript Busca de coberturas com resultados
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Coverage?_lastUpdated=%5B%22eq2013-01-14%22%5D&beneficiary=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&class-type=plan&class-value=42&dependent=1352744&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fcobertura%2F%7CCOB-88231&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&policy-holder=Organization%2F6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60&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 de coberturas com resultados`**

```go Busca de coberturas com resultados
package main

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

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Coverage?_lastUpdated=%5B%22eq2013-01-14%22%5D&beneficiary=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&class-type=plan&class-value=42&dependent=1352744&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fcobertura%2F%7CCOB-88231&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&policy-holder=Organization%2F6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60&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 de coberturas com resultados`**

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

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Coverage?_lastUpdated=%5B%22eq2013-01-14%22%5D&beneficiary=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&class-type=plan&class-value=42&dependent=1352744&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fcobertura%2F%7CCOB-88231&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&policy-holder=Organization%2F6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60&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 de coberturas com resultados`**

```java Busca de coberturas 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/Coverage?_lastUpdated=%5B%22eq2013-01-14%22%5D&beneficiary=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&class-type=plan&class-value=42&dependent=1352744&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fcobertura%2F%7CCOB-88231&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&policy-holder=Organization%2F6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60&status=active")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Busca de coberturas com resultados`**

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://landing-zone-api.nilo.services/fhir/resources/Coverage?_lastUpdated=%5B%22eq2013-01-14%22%5D&beneficiary=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&class-type=plan&class-value=42&dependent=1352744&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fcobertura%2F%7CCOB-88231&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&policy-holder=Organization%2F6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60&status=active', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Busca de coberturas com resultados`**

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

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Coverage?_lastUpdated=%5B%22eq2013-01-14%22%5D&beneficiary=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&class-type=plan&class-value=42&dependent=1352744&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fcobertura%2F%7CCOB-88231&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&policy-holder=Organization%2F6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60&status=active");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

**`Busca de coberturas com resultados`**

```swift Busca de coberturas com resultados
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Coverage?_lastUpdated=%5B%22eq2013-01-14%22%5D&beneficiary=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&class-type=plan&class-value=42&dependent=1352744&identifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fcobertura%2F%7CCOB-88231&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&policy-holder=Organization%2F6e6a1b40-1e2a-4f1e-9f0e-2b1c3d4e5f60&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()
```

A resposta é sempre um `Bundle` do tipo `searchset`, mesmo quando há um único resultado:

### Response (200)

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
      "resource": {
        "beneficiary": {
          "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
          },
          "type": "Patient",
          "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
        },
        "payor": [
          {
            "display": "Operadora"
          }
        ],
        "resourceType": "Coverage",
        "status": "active",
        "class": [
          {
            "type": {
              "text": "plan"
            },
            "value": "42",
            "name": "Unimed com coparticipação SP/SP"
          }
        ],
        "id": "7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--coverage",
            "value": "918233",
            "use": "usual"
          },
          {
            "system": "https://www.acmesaude.com.br/integracao/cobertura/",
            "value": "COB-88231",
            "use": "official"
          }
        ],
        "order": 1,
        "period": {
          "start": "2022-05-23"
        },
        "relationship": {
          "coding": [
            {
              "code": "self"
            }
          ]
        },
        "subscriberId": "1352743"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

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

### Response (200)

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

### Parâmetros de busca suportados

| Nome                 | Tipo                                                       | Descrição                                                     | Expressão                         |
| -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------- |
| `identifier`         | [token](https://hl7.org/fhir/R4/search.html#token)         | Identificador da cobertura, em `system\|value`                | `Coverage.identifier`             |
| `patient:identifier` | [reference](https://hl7.org/fhir/R4/search.html#reference) | Paciente coberto, pelo identificador dele, em `system\|value` | `Coverage.beneficiary.identifier` |
| `patient`            | [reference](https://hl7.org/fhir/R4/search.html#reference) | Paciente coberto, pelo `id` Nilo FHIR                         | `Coverage.beneficiary`            |
| `beneficiary`        | [reference](https://hl7.org/fhir/R4/search.html#reference) | O mesmo campo que `patient`, e aceita o mesmo `:identifier`   | `Coverage.beneficiary`            |
| `status`             | [token](https://hl7.org/fhir/R4/search.html#token)         | Situação da cobertura                                         | `Coverage.status`                 |
| `dependent`          | [string](https://hl7.org/fhir/R4/search.html#string)       | Carteirinha de um beneficiário dependente                     | `Coverage.dependent`              |
| `class-value`        | [string](https://hl7.org/fhir/R4/search.html#string)       | Id do plano                                                   | `Coverage.class.value`            |
| `class-type`         | [token](https://hl7.org/fhir/R4/search.html#token)         | Tipo da classificação — a Nilo grava sempre `plan`            | `Coverage.class.type`             |
| `policy-holder`      | [reference](https://hl7.org/fhir/R4/search.html#reference) | Estipulante                                                   | `Coverage.policyHolder`           |

A busca do dia a dia é a lista de coberturas de um paciente. Com o modificador `:identifier`
ela usa a chave que você já tem no seu sistema, sem precisar guardar o `id` Nilo FHIR do
paciente:

```bash
curl --request GET \
  --url 'https://landing-zone-api.nilo.services/fhir/resources/Coverage?patient:identifier=https://www.acmesaude.com.br/integracao/paciente/|507823709' \
  --header 'x-api-key: SUA_API_KEY'
```

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

> **Note**
>
> Dois parâmetros canônicos do `Coverage` existem mas praticamente não encontram nada aqui.
> `policy-holder` casa por referência, e a Nilo grava o estipulante apenas como texto em
> `policyHolder.display`. E o FHIR R4 **não define** parâmetro para `subscriberId`: a
> carteirinha de um titular não é filtrável — só a de um dependente, por `dependent`.

## Ler por ID

### Request

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

**`Cobertura encontrada`**

```curl Cobertura encontrada
curl https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73 \
     -H "x-api-key: <apiKey>"
```

**`Cobertura encontrada`**

```python Cobertura encontrada
import requests

url = "https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73"

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

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

print(response.json())
```

**`Cobertura encontrada`**

```javascript Cobertura encontrada
const url = 'https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73';
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);
}
```

**`Cobertura encontrada`**

```go Cobertura encontrada
package main

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

func main() {

	url := "https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73"

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

}
```

**`Cobertura encontrada`**

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

url = URI("https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73")

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

**`Cobertura encontrada`**

```java Cobertura 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/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73")
  .header("x-api-key", "<apiKey>")
  .asString();
```

**`Cobertura encontrada`**

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Cobertura encontrada`**

```csharp Cobertura encontrada
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

**`Cobertura encontrada`**

```swift Cobertura encontrada
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/Coverage/7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73")! 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()
```

Diferente da busca, a leitura por ID devolve o recurso direto, sem envelope `Bundle`, e
responde `404` quando o `id` não existe.

### Response (200)

```json
{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "id": "7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--coverage",
      "value": "918233",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "meta": {
    "lastUpdated": "2026-08-06T13:04:12.905000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "order": 1,
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}
```

## Valores aceitos

`relationship.coding[0].code` usa o vocabulário
[`subscriber-relationship`](https://hl7.org/fhir/R4/valueset-subscriber-relationship.html) do
FHIR R4. Os sete códigos têm rótulo no NiloCare:

| Código    | No NiloCare             |
| --------- | ----------------------- |
| `self`    | Próprio                 |
| `child`   | Filho                   |
| `parent`  | Pais                    |
| `spouse`  | Cônjuge (Civil)         |
| `common`  | Cônjuge (União estável) |
| `injured` | Extensão a terceiros    |
| `other`   | Outro                   |

Só `self` tem efeito sobre o comportamento da API — é ele que decide qual campo carrega a
carteirinha do beneficiário. Os outros seis são equivalentes entre si nesse aspecto.

`status` usa os quatro códigos do FHIR R4:

| Código             | No NiloCare    |
| ------------------ | -------------- |
| `active`           | Ativo          |
| `draft`            | Em contratação |
| `cancelled`        | Cancelado      |
| `entered-in-error` | Inválido       |

> **Note**
>
> Numa cobertura criada pela interface e nunca escrita por esta API o `status` pode estar vazio
> do lado Nilo. Nesse caso a leitura o deriva da vigência: `cancelled` quando o fim de vigência
> já passou, `active` nos outros casos. A escrita nunca deriva — o `status` que você manda é o
> que fica gravado.

O catálogo de planos não é um vocabulário fixo: cada care provider tem os seus, cadastrados na
implantação. Liste-os com `GET /fhir/resources/InsurancePlan`, como mostrado em **Plano de
saúde**, acima.

## Como a API evita duplicatas

O caminho normal é o `identifier`, e ele é obrigatório. Mas quando nenhum dos identificadores
enviados encontra uma cobertura, a API tenta uma segunda vez pela **chave de negócio** — a
combinação de:

* carteirinha do beneficiário (`subscriberId` num titular, `dependent` num dependente);
* paciente (`beneficiary`);
* plano (`class[0].value` ou a extensão `insurance-plan`).

Havendo cobertura com os três iguais, ela é **atualizada** e passa a carregar também o seu
identificador. Do contrário, uma nova é criada.

> **Note**
>
> Isso é o que torna seguro integrar coberturas que já existiam no NiloCare antes da integração:
> a primeira escrita reconhece a cobertura pela carteirinha em vez de duplicá-la. A chave só
> funciona com os três valores presentes — faltando qualquer um, a API cria uma cobertura nova.

## Efeitos colaterais

A escrita de `Coverage` grava apenas a cobertura. Ela não cria nem altera o paciente, não
cadastra planos e não dispara mensagens.

> **Note**
>
> Este endpoint não remove coberturas: a escrita nunca responde `204`. A remoção acontece do
> lado Nilo e é propagada para o store FHIR pela sincronização, não por esta API.

## Erros

Recusa é sempre `400` com um `OperationOutcome`: `issue[].expression` aponta o campo culpado e
`issue[].details.text` explica o motivo.

O paciente do `beneficiary` precisa existir. Cadastre-o pelo
[`Patient`](/guia/recursos/patient) antes — a cobertura não o cria:

### Response (200)

```json
{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "id": "7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--coverage",
      "value": "918233",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "meta": {
    "lastUpdated": "2026-08-06T13:04:12.905000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "order": 1,
  "period": {
    "end": "2023-05-23",
    "start": "2022-05-23"
  },
  "policyHolder": {
    "display": "Acme Indústria S.A."
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}
```

`relationship` é obrigatório, e o código tem de estar em `coding[0].code`. Mandar o campo sem
`coding`, ou o `coding` sem `code`, dá o mesmo erro que omiti-lo:

### Response (200)

```json
{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "id": "7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--coverage",
      "value": "918233",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "meta": {
    "lastUpdated": "2026-08-06T13:04:12.905000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "order": 1,
  "period": {
    "end": "2023-05-23",
    "start": "2022-05-23"
  },
  "policyHolder": {
    "display": "Acme Indústria S.A."
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}
```

Toda escrita precisa de ao menos um `identifier`:

### Response (200)

```json
{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "id": "7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--coverage",
      "value": "918233",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "meta": {
    "lastUpdated": "2026-08-06T13:04:12.905000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "order": 1,
  "period": {
    "end": "2023-05-23",
    "start": "2022-05-23"
  },
  "policyHolder": {
    "display": "Acme Indústria S.A."
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}
```

E a cobertura precisa de um plano **ou** de uma carteirinha. Os dois vazios são recusados — a
mesma regra que o formulário do NiloCare aplica ao exigir *"o plano de saúde ou número da
carteirinha"*:

### Response (200)

```json
{
  "beneficiary": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "payor": [
    {
      "display": "Operadora"
    }
  ],
  "resourceType": "Coverage",
  "status": "active",
  "class": [
    {
      "type": {
        "text": "plan"
      },
      "value": "42",
      "name": "Unimed com coparticipação SP/SP"
    }
  ],
  "id": "7f2b91c4-3d0a-4e8b-9c11-5a6d8e2f0b73",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--coverage",
      "value": "918233",
      "use": "usual"
    },
    {
      "system": "https://www.acmesaude.com.br/integracao/cobertura/",
      "value": "COB-88231",
      "use": "official"
    }
  ],
  "meta": {
    "lastUpdated": "2026-08-06T13:04:12.905000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
  },
  "order": 1,
  "period": {
    "end": "2023-05-23",
    "start": "2022-05-23"
  },
  "policyHolder": {
    "display": "Acme Indústria S.A."
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "subscriberId": "1352743"
}
```

> **Note**
>
> Esse último erro chega da camada de validação sem ser reformulado, e por isso o
> `details.text` é técnico e o `code` é o genérico `exception`. Trate-o pela menção a
> `card_number` e `insurance_id` na mensagem, não pelo texto exato — ele pode mudar.

> **Note**
>
> `payor` e `status` são obrigatórios pela especificação FHIR R4, então um payload sem eles é
> recusado antes de chegar às regras acima, com um `OperationOutcome` de código `structure`
> apontando o campo que falta.

## O que a integração não cobre

O plano de saúde do paciente não fica no `Patient` — é sempre um `Coverage` à parte, ligado a
ele por `beneficiary`. E o catálogo de planos em si não é criado por esta API: os planos são
cadastrados na implantação, e o que a integração faz com eles é ler e, quando preciso,
corrigir o nome — veja [Plano de saúde](/guia/recursos/insuranceplan).