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

# Mensagem programada

> Consultar as mensagens que a plataforma vai enviar a um paciente, no padrão FHIR CommunicationRequest.

Uma **mensagem programada** é um envio agendado para um paciente: o lembrete de consulta, a
mensagem de acompanhamento que a diretriz manda disparar em 30 dias.

No FHIR o recurso é a
[`CommunicationRequest`](https://hl7.org/fhir/R4/communicationrequest.html) — e ele carrega
**duas coisas diferentes**, distinguidas pelo `system` do identificador:

| O que é                                  | `system` do identificador Nilo                   | Escrita             |
| ---------------------------------------- | ------------------------------------------------ | ------------------- |
| **Mensagem programada** para um paciente | `…/NamingSystem/jaiminho-api--scheduled-message` | não há              |
| **Matrícula do paciente numa campanha**  | `…/NamingSystem/jaiminho-api--patient-campaign`  | **sim** — é a única |

> **Warning**
>
> **As duas formas não trazem os mesmos campos.** A mensagem programada é rica: tem `priority`,
> `category`, `occurrencePeriod`, `payload` e `note`. A matrícula em campanha traz **apenas**
> `status`, `basedOn`, `subject`, `recipient` e `authoredOn`.
>
> Confira o `system` do identificador antes de ler qualquer outro campo.

## Campos

| Campo                      | Presente em | O que significa                                                |
| -------------------------- | ----------- | -------------------------------------------------------------- |
| `resourceType`             | ambos       | Constante `CommunicationRequest`                               |
| `identifier`               | ambos       | Identificador Nilo — e o que distingue as duas formas          |
| `status`                   | ambos       | Veja a tabela abaixo                                           |
| `subject`                  | ambos       | O paciente                                                     |
| `recipient[0]`             | ambos       | Repete o `subject`                                             |
| `authoredOn`               | ambos       | Quando foi programada ou matriculada                           |
| `basedOn[0]`               | ambos       | A diretriz aplicada, na mensagem; a **campanha**, na matrícula |
| `priority`                 | só mensagem | `asap` quando **atrasada**, `routine` no resto                 |
| `occurrencePeriod.start`   | só mensagem | Quando ela **deve** ser enviada                                |
| `occurrencePeriod.end`     | só mensagem | Quando foi concluída ou cancelada                              |
| `replaces[0]`              | só mensagem | A mensagem programada que esta substitui                       |
| `payload[0].contentString` | só mensagem | O texto da mensagem                                            |
| `category[0]`              | só mensagem | Um código **interno** — veja o aviso                           |
| `note[0]`                  | só mensagem | Um texto de diagnóstico em formato interno                     |
| `id` · `meta`              | ambos       | Identificador Nilo FHIR do recurso e metadados da gravação     |

### `status`

| `status`           | Na mensagem programada              | Na matrícula em campanha          |
| ------------------ | ----------------------------------- | --------------------------------- |
| `active`           | Programada — **inclusive atrasada** | Paciente na campanha              |
| `completed`        | Já enviada                          | Campanha concluída com sucesso    |
| `revoked`          | Cancelada                           | Paciente saiu, ou pediu para sair |
| `entered-in-error` | —                                   | Matrícula registrada por engano   |
| `unknown`          | Qualquer outro estado               | —                                 |

> **Warning**
>
> **`priority` não é uma prioridade: é um sinal de atraso.** Ele vale `asap` quando o envio já
> passou da data e ainda não aconteceu, e `routine` em todo o resto. Ninguém escolhe esse valor.

> **Warning**
>
> **E ele fica para trás.** O valor gravado é o do último instante em que a mensagem foi
> sincronizada — e a passagem de "programada" para "atrasada" não altera nada no registro, então
> não dispara sincronização. Uma mensagem que venceu depois do último sync continua `routine`.
>
> Para saber se uma mensagem está atrasada, compare `occurrencePeriod.start` com a data de hoje do
> seu lado. Não confie no `priority`.

> **Note**
>
> `subject` e `recipient[0]` trazem **o mesmo paciente**. O FHIR distingue de quem é o assunto e
> para quem vai a mensagem; aqui os dois campos são a mesma pessoa, sempre.

### `occurrencePeriod` não é um intervalo

> **Warning**
>
> `occurrencePeriod.start` é a data **programada** de envio, e `occurrencePeriod.end` é o instante
> em que a mensagem foi concluída ou cancelada. Numa mensagem ainda programada, o `end` **não
> vem**.
>
> Não são as duas pontas de uma janela de envio: são "quando devia" e "quando acabou".

### Dois campos que vazam formato interno

> **Warning**
>
> **`category[0].coding[0].code` traz um identificador interno da plataforma**, não um código de
> vocabulário. **Não é contrato**: o valor pode mudar sem aviso, e não deve ser interpretado nem
> usado como filtro estável — o parâmetro de busca `category`, na prática, só serve para quem já
> conhece o valor que veio numa resposta.

> **Note**
>
> **`note[0].text` é a única informação de motivo que existe neste recurso.** Ele vem no formato
> `status-detail:<motivo>`, e o motivo é um de oito valores fechados: espera de encerramento da
> conversa, nova tentativa em curso, limite de tentativas excedido, expirada, criada no passado,
> paciente inativo, conversa desabilitada, e atraso máximo excedido.
>
> O **formato** não é contrato — pode mudar sem aviso —, mas conhecer a lista ajuda a entender por
> que uma mensagem não saiu. Use para exibição e diagnóstico, não para lógica.

### Campos que a Nilo não usa

A `CommunicationRequest` canônica traz muito mais: `basedOn` de outros tipos, `groupIdentifier`,
`statusReason`, `medium`, `about`, `encounter`, `requester`, `sender`, `reasonCode`,
`reasonReference` e `doNotPerform`. Nenhum deles é lido.

> **Warning**
>
> Repare em **`medium`**: não há campo que diga **por onde** a mensagem vai — se por conversa, se
> por outro canal. E em **`sender`**: não há como saber quem a programou.

## Buscar

### Request

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

**`Busca com resultados`**

```curl Busca com resultados
curl -G https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest \
     -H "x-api-key: <apiKey>" \
     -d _count=50 \
     -d _lastUpdated=eq2013-01-14 \
     -d authored=ge2026-06-01 \
     --data-urlencode identifier=https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--scheduled-message|440871 \
     -d occurrence=ge2026-06-01 \
     --data-urlencode patient=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4 \
     --data-urlencode patient:identifier=https://www.acmesaude.com.br/integracao/paciente/|507823709 \
     -d priority=asap \
     --data-urlencode recipient=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4 \
     --data-urlencode replaces=CommunicationRequest/c81f5b40-3a29-4e76-90d5-1b47ea62c803 \
     -d status=active \
     --data-urlencode subject=Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4
```

**`Busca com resultados`**

```python Busca com resultados
import requests

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

querystring = {"_count":"50","_lastUpdated":"[\"eq2013-01-14\"]","authored":"ge2026-06-01","identifier":"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--scheduled-message|440871","occurrence":"ge2026-06-01","patient":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4","patient:identifier":"https://www.acmesaude.com.br/integracao/paciente/|507823709","priority":"asap","recipient":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4","replaces":"CommunicationRequest/c81f5b40-3a29-4e76-90d5-1b47ea62c803","status":"active","subject":"Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"}

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/CommunicationRequest?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&authored=ge2026-06-01&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fjaiminho-api--scheduled-message%7C440871&occurrence=ge2026-06-01&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&priority=asap&recipient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&replaces=CommunicationRequest%2Fc81f5b40-3a29-4e76-90d5-1b47ea62c803&status=active&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4';
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/CommunicationRequest?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&authored=ge2026-06-01&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fjaiminho-api--scheduled-message%7C440871&occurrence=ge2026-06-01&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&priority=asap&recipient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&replaces=CommunicationRequest%2Fc81f5b40-3a29-4e76-90d5-1b47ea62c803&status=active&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4"

	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/CommunicationRequest?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&authored=ge2026-06-01&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fjaiminho-api--scheduled-message%7C440871&occurrence=ge2026-06-01&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&priority=asap&recipient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&replaces=CommunicationRequest%2Fc81f5b40-3a29-4e76-90d5-1b47ea62c803&status=active&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4")

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/CommunicationRequest?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&authored=ge2026-06-01&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fjaiminho-api--scheduled-message%7C440871&occurrence=ge2026-06-01&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&priority=asap&recipient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&replaces=CommunicationRequest%2Fc81f5b40-3a29-4e76-90d5-1b47ea62c803&status=active&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4")
  .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/CommunicationRequest?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&authored=ge2026-06-01&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fjaiminho-api--scheduled-message%7C440871&occurrence=ge2026-06-01&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&priority=asap&recipient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&replaces=CommunicationRequest%2Fc81f5b40-3a29-4e76-90d5-1b47ea62c803&status=active&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4', [
  '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/CommunicationRequest?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&authored=ge2026-06-01&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fjaiminho-api--scheduled-message%7C440871&occurrence=ge2026-06-01&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&priority=asap&recipient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&replaces=CommunicationRequest%2Fc81f5b40-3a29-4e76-90d5-1b47ea62c803&status=active&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4");
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/CommunicationRequest?_count=50&_lastUpdated=%5B%22eq2013-01-14%22%5D&authored=ge2026-06-01&identifier=https%3A%2F%2Flanding-zone-api.nilo.services%2Ffhir%2Fresources%2FNamingSystem%2Fjaiminho-api--scheduled-message%7C440871&occurrence=ge2026-06-01&patient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&patient%3Aidentifier=https%3A%2F%2Fwww.acmesaude.com.br%2Fintegracao%2Fpaciente%2F%7C507823709&priority=asap&recipient=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4&replaces=CommunicationRequest%2Fc81f5b40-3a29-4e76-90d5-1b47ea62c803&status=active&subject=Patient%2Fba200cfa-dae0-46cf-81a0-008e3f7414b4")! 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`:

### Response (200)

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest/c81f5b40-3a29-4e76-90d5-1b47ea62c803",
      "resource": {
        "resourceType": "CommunicationRequest",
        "identifier": [
          {
            "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--scheduled-message",
            "value": "440871",
            "use": "usual"
          }
        ],
        "status": "active",
        "id": "c81f5b40-3a29-4e76-90d5-1b47ea62c803",
        "meta": {
          "lastUpdated": "2026-06-26T03:00:12.447000Z",
          "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
        },
        "priority": "asap",
        "subject": {
          "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
          },
          "type": "Patient",
          "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
        },
        "recipient": [
          {
            "identifier": {
              "system": "https://www.acmesaude.com.br/integracao/paciente/",
              "value": "507823709",
              "use": "usual"
            },
            "type": "Patient",
            "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
          }
        ],
        "category": [
          {
            "coding": [
              {
                "code": "jaiminho_api.ScheduledMessage",
                "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/communication-category"
              }
            ]
          }
        ],
        "basedOn": [
          {
            "identifier": {
              "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/hippocrates-api--patient-care-line",
              "value": "77120",
              "use": "usual"
            },
            "type": "CarePlan"
          }
        ],
        "payload": [
          {
            "contentString": "Lembrete: sua consulta de acompanhamento está marcada para a próxima semana."
          }
        ],
        "authoredOn": "2026-06-20T08:00:00+00:00",
        "occurrencePeriod": {
          "start": "2026-06-25T09:00:00+00:00"
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": []
}
```

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

### Response (200)

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

### Parâmetros de busca suportados

| Nome                                        | Tipo                                                       | Descrição                                                                  | Expressão                                 |
| ------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------- |
| `identifier`                                | [token](https://hl7.org/fhir/R4/search.html#token)         | Identificador da mensagem, em `system\|value`                              | `CommunicationRequest.identifier`         |
| `patient` · `subject`                       | [reference](https://hl7.org/fhir/R4/search.html#reference) | Paciente, pelo `id` Nilo FHIR dele                                         | `CommunicationRequest.subject`            |
| `patient:identifier` · `subject:identifier` | [reference](https://hl7.org/fhir/R4/search.html#reference) | Paciente, pelo identificador dele                                          | `CommunicationRequest.subject.identifier` |
| `recipient`                                 | [reference](https://hl7.org/fhir/R4/search.html#reference) | O mesmo paciente, pelo outro campo                                         | `CommunicationRequest.recipient`          |
| `status`                                    | [token](https://hl7.org/fhir/R4/search.html#token)         | Situação da mensagem                                                       | `CommunicationRequest.status`             |
| `priority`                                  | [token](https://hl7.org/fhir/R4/search.html#token)         | `asap` traz as que **estavam** atrasadas na última gravação — veja o aviso | `CommunicationRequest.priority`           |
| `occurrence`                                | [date](https://hl7.org/fhir/R4/search.html#date)           | Data programada de envio, com os prefixos `eq`, `ge`, `le`                 | `CommunicationRequest.occurrence`         |
| `authored`                                  | [date](https://hl7.org/fhir/R4/search.html#date)           | Data em que foi programada, com os mesmos prefixos                         | `CommunicationRequest.authoredOn`         |
| `category`                                  | [token](https://hl7.org/fhir/R4/search.html#token)         | Categoria, em `system\|code` — o código é interno                          | `CommunicationRequest.category`           |
| `replaces`                                  | [reference](https://hl7.org/fhir/R4/search.html#reference) | A mensagem que esta substitui, pelo `id` Nilo FHIR dela                    | `CommunicationRequest.replaces`           |
| `_lastUpdated`                              | [date](https://hl7.org/fhir/R4/search.html#date)           | Data da última gravação no store, com os mesmos prefixos                   | —                                         |

> **Note**
>
> Os demais parâmetros canônicos existem e **não encontram nada**, porque a plataforma não
> preenche o campo correspondente: `medium`, `encounter`, `requester`, `sender`, `group-identifier`
> e `based-on` — este último porque a referência à diretriz aplicada vem **sem** `reference`; use
> `based-on:identifier`.

> **Warning**
>
> Qual identificador as referências carregam **depende da sua implantação**. Na configuração que
> usa identificadores externos, o `subject` sai com o identificador do seu sistema; sem ela, vem o
> identificador Nilo do paciente. Confira numa resposta de leitura antes de montar a busca em
> volume.

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

## Ler por ID

### Request

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

**`Mensagem programada encontrada`**

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

**`Mensagem programada encontrada`**

```python Mensagem programada encontrada
import requests

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

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

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

print(response.json())
```

**`Mensagem programada encontrada`**

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

**`Mensagem programada encontrada`**

```go Mensagem programada encontrada
package main

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

func main() {

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

}
```

**`Mensagem programada encontrada`**

```ruby Mensagem programada encontrada
require 'uri'
require 'net/http'

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

**`Mensagem programada encontrada`**

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

**`Mensagem programada encontrada`**

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

$client = new \GuzzleHttp\Client();

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

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

**`Mensagem programada encontrada`**

```csharp Mensagem programada encontrada
using RestSharp;

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

**`Mensagem programada encontrada`**

```swift Mensagem programada encontrada
import Foundation

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

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

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

dataTask.resume()
```

> **Warning**
>
> Diferente da busca, esta leitura não devolve um `Bundle` — mas também **não devolve o recurso
> nu**. A resposta é um envelope com `fullUrl`, `search` e `resource`, e a mensagem está em
> `resource`.

### Response (200)

```json
{
  "fullUrl": "https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest/c81f5b40-3a29-4e76-90d5-1b47ea62c803",
  "resource": {
    "resourceType": "CommunicationRequest",
    "identifier": [
      {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--scheduled-message",
        "value": "440871",
        "use": "usual"
      }
    ],
    "status": "completed",
    "id": "c81f5b40-3a29-4e76-90d5-1b47ea62c803",
    "meta": {
      "lastUpdated": "2026-06-26T03:00:12.447000Z",
      "versionId": "MTc4NjAyMTQ1MjkwNTAwMDM2Nw"
    },
    "priority": "routine",
    "subject": {
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/paciente/",
        "value": "507823709",
        "use": "usual"
      },
      "type": "Patient",
      "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
    },
    "category": [
      {
        "coding": [
          {
            "code": "jaiminho_api.ScheduledMessage",
            "system": "https://landing-zone-api.nilo.services/fhir/resources/CodeSystem/communication-category"
          }
        ]
      }
    ],
    "payload": [
      {
        "contentString": "Lembrete: sua consulta de acompanhamento está marcada para a próxima semana."
      }
    ],
    "authoredOn": "2026-06-20T08:00:00+00:00",
    "occurrencePeriod": {
      "end": "2026-06-25T09:00:47+00:00",
      "start": "2026-06-25T09:00:00+00:00"
    }
  },
  "search": {
    "mode": "match"
  }
}
```

## Onde a mensagem programada aparece

> **Note**
>
> As mensagens geradas por uma diretriz também aparecem em `activity[]` da [diretriz aplicada](/guia/recursos/careplan) do paciente, junto com as tarefas e os questionários. A
> vantagem desta página é poder buscá-las diretamente, sem passar pela diretriz aplicada.
>
> O caminho de volta é o `basedOn`, que aponta para a diretriz aplicada — sem `reference`, então
> use `based-on:identifier` para buscar por ele. Numa **matrícula em campanha**, o mesmo `basedOn`
> aponta para a campanha, não para uma diretriz aplicada: confira o `system` do identificador antes de
> interpretá-lo.

> **Note**
>
> Uma mensagem **reprogramada** aponta em `replaces[0]` para a anterior. É a única forma de
> reconstruir a cadeia de reprogramações.

## Matricular um paciente numa campanha

O `POST` deste recurso faz **uma coisa só**: coloca um paciente numa **campanha** de mensagens
já configurada no seu ambiente. Ele não programa uma mensagem avulsa.

### Request

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

**`Matricular numa campanha`**

```curl Matricular numa campanha
curl -X POST https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "resourceType": "CommunicationRequest",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "basedOn": [
    {
      "identifier": {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign",
        "value": "318",
        "use": "usual"
      }
    }
  ]
}'
```

**`Matricular numa campanha`**

```python Matricular numa campanha
import requests

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

payload = {
    "resourceType": "CommunicationRequest",
    "subject": {
        "identifier": {
            "system": "https://www.acmesaude.com.br/integracao/paciente/",
            "value": "507823709",
            "use": "usual"
        },
        "type": "Patient"
    },
    "basedOn": [{ "identifier": {
                "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign",
                "value": "318",
                "use": "usual"
            } }]
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Matricular numa campanha`**

```javascript Matricular numa campanha
const url = 'https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"resourceType":"CommunicationRequest","subject":{"identifier":{"system":"https://www.acmesaude.com.br/integracao/paciente/","value":"507823709","use":"usual"},"type":"Patient"},"basedOn":[{"identifier":{"system":"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign","value":"318","use":"usual"}}]}'
};

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

**`Matricular numa campanha`**

```go Matricular numa campanha
package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"resourceType\": \"CommunicationRequest\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"basedOn\": [\n    {\n      \"identifier\": {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign\",\n        \"value\": \"318\",\n        \"use\": \"usual\"\n      }\n    }\n  ]\n}")

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

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

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

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

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

}
```

**`Matricular numa campanha`**

```ruby Matricular numa campanha
require 'uri'
require 'net/http'

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

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\": \"CommunicationRequest\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"basedOn\": [\n    {\n      \"identifier\": {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign\",\n        \"value\": \"318\",\n        \"use\": \"usual\"\n      }\n    }\n  ]\n}"

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

**`Matricular numa campanha`**

```java Matricular numa campanha
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/CommunicationRequest")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"resourceType\": \"CommunicationRequest\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"basedOn\": [\n    {\n      \"identifier\": {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign\",\n        \"value\": \"318\",\n        \"use\": \"usual\"\n      }\n    }\n  ]\n}")
  .asString();
```

**`Matricular numa campanha`**

```php Matricular numa campanha
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest', [
  'body' => '{
  "resourceType": "CommunicationRequest",
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient"
  },
  "basedOn": [
    {
      "identifier": {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign",
        "value": "318",
        "use": "usual"
      }
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

**`Matricular numa campanha`**

```csharp Matricular numa campanha
using RestSharp;

var client = new RestClient("https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"resourceType\": \"CommunicationRequest\",\n  \"subject\": {\n    \"identifier\": {\n      \"system\": \"https://www.acmesaude.com.br/integracao/paciente/\",\n      \"value\": \"507823709\",\n      \"use\": \"usual\"\n    },\n    \"type\": \"Patient\"\n  },\n  \"basedOn\": [\n    {\n      \"identifier\": {\n        \"system\": \"https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign\",\n        \"value\": \"318\",\n        \"use\": \"usual\"\n      }\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Matricular numa campanha`**

```swift Matricular numa campanha
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "resourceType": "CommunicationRequest",
  "subject": [
    "identifier": [
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    ],
    "type": "Patient"
  ],
  "basedOn": [["identifier": [
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign",
        "value": "318",
        "use": "usual"
      ]]]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://landing-zone-api.nilo.services/fhir/resources/CommunicationRequest")! 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": "CommunicationRequest",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--patient-campaign",
      "value": "88301",
      "use": "usual"
    }
  ],
  "status": "active",
  "id": "5a2c7e08-4b91-4d36-a870-f1e4062c9b53",
  "meta": {
    "lastUpdated": "2026-07-08T10:02:19.640000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDQwNQ"
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "recipient": [
    {
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/paciente/",
        "value": "507823709",
        "use": "usual"
      },
      "type": "Patient",
      "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
    }
  ],
  "basedOn": [
    {
      "identifier": {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign",
        "value": "318",
        "use": "usual"
      }
    }
  ],
  "authoredOn": "2026-07-08T10:02:19+00:00"
}
```

São quatro exigências, e todas recusam a chamada quando não são atendidas:

| Campo                   | Regra                                                               |
| ----------------------- | ------------------------------------------------------------------- |
| `status`                | Tem de ser **exatamente** `active`                                  |
| `subject.identifier`    | Obrigatório — o paciente, pela sua chave ou pelo identificador Nilo |
| `basedOn`               | Obrigatório, com **exatamente uma** campanha                        |
| `basedOn[0].identifier` | No `system` da campanha, e a campanha tem de existir                |

> **Warning**
>
> **A campanha não é criada por aqui.** Ela é configurada no seu ambiente, e o que esta API faz é
> matricular pacientes nela. Se a campanha não existir, a chamada é recusada com
> `Campaign not found` — fale com o **Suporte** para saber quais campanhas existem e quais são os
> identificadores delas.

> **Warning**
>
> **Um paciente não pode ser matriculado duas vezes na mesma campanha.** Se ele já estiver nela
> com a matrícula em andamento, a chamada é recusada com `Patient already on campaign`.
>
> E **não há como retirá-lo** por esta API: sair da campanha é ação da plataforma.

> **Note**
>
> `priority`, `occurrencePeriod`, `payload`, `category` e `note` **não são lidos** neste `POST`, e
> não voltam na resposta. A matrícula é um recurso mais pobre que a mensagem programada.

### Erros da matrícula

Recusa é `400`, e o corpo é um `OperationOutcome` com `code: structure` e o campo em
`issue[].expression`.

| `expression`                              | Mensagem                                                | Quando                                                          |
| ----------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
| `CommunicationRequest.status`             | `Campaigns can't be created with the status not active` | O `status` não é `active`                                       |
| `CommunicationRequest.subject.identifier` | `field required`                                        | Não há `subject`, ou ele veio sem `identifier`                  |
| `CommunicationRequest.subject.identifier` | `Patient not found`                                     | O identificador não resolve para um paciente do seu ambiente    |
| `CommunicationRequest.basedOn`            | `field required`                                        | O payload não tem `basedOn`                                     |
| `CommunicationRequest.basedOn`            | `Campaign not found`                                    | Nenhuma campanha no `system` esperado, ou a campanha não existe |
| `CommunicationRequest.basedOn`            | `Multiple campaigns are not allowed`                    | Mais de uma campanha em `basedOn`                               |
| `CommunicationRequest.subject`            | `Patient already on campaign`                           | O paciente já está nessa campanha                               |

### Response (200)

```json
{
  "resourceType": "CommunicationRequest",
  "identifier": [
    {
      "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--patient-campaign",
      "value": "88301",
      "use": "usual"
    }
  ],
  "status": "active",
  "id": "5a2c7e08-4b91-4d36-a870-f1e4062c9b53",
  "meta": {
    "lastUpdated": "2026-07-08T10:02:19.640000Z",
    "versionId": "MTc4NjAyMTQ1MjkwNTAwMDQwNQ"
  },
  "subject": {
    "identifier": {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709",
      "use": "usual"
    },
    "type": "Patient",
    "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
  },
  "recipient": [
    {
      "identifier": {
        "system": "https://www.acmesaude.com.br/integracao/paciente/",
        "value": "507823709",
        "use": "usual"
      },
      "type": "Patient",
      "reference": "Patient/ba200cfa-dae0-46cf-81a0-008e3f7414b4"
    }
  ],
  "basedOn": [
    {
      "identifier": {
        "system": "https://landing-zone-api.nilo.services/fhir/resources/NamingSystem/jaiminho-api--campaign",
        "value": "318",
        "use": "usual"
      }
    }
  ],
  "authoredOn": "2026-07-08T10:02:19+00:00"
}
```

### `429`

Este recurso **pode ter** limite de escrita, conforme a configuração do ambiente. Havendo
limite e estourando-o, a chamada responde `429` com `code: throttled`, e a mensagem informa
quantos segundos esperar.

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

* **programar** uma mensagem avulsa, cancelá-la ou reprogramá-la — só a matrícula em campanha é
  gravável;
* **retirar** um paciente de uma campanha;
* **listar as campanhas** existentes: elas não são publicadas como recurso;
* **por onde** a mensagem vai ser enviada;
* **quem** a programou;
* o elo com a **mensagem efetivamente enviada** — o
  [`Communication`](/guia/recursos/communication) correspondente não é referenciado.