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

# Diretrizes

> Por que uma diretriz é recusada, por que ela é aceita e não aparece, e como reinscrever um paciente.

A diretriz aplicada é o recurso que gera mais chamados de integração, por um motivo estrutural:
é o único cujo processamento **não termina na resposta**. A escrita é aceita, e a atribuição da
diretriz ao paciente acontece depois, num processamento em lote que tem pré-requisitos
próprios. Quase todo caso desta página é uma das duas faces disso — ou a recusa na escrita, ou
o silêncio depois dela.

Os fundamentos estão em [Diretriz aplicada](/guia/recursos/careplan) e em
[Diretriz](/guia/recursos/plandefinition).

## `CarePlan with status revoked can't be updated`

**Causa.** O `identifier.value` enviado já existe como uma diretriz aplicada **cancelada**. Uma
diretriz aplicada cancelada é imutável por desenho: ela guarda o período em que o paciente
esteve naquela diretriz, e permitir sua reescrita apagaria esse histórico. Não existe
reativação.

**O que fazer.** Para reinscrever o paciente na mesma diretriz, envie um `identifier.value`
**inédito** naquele `system`. É o ponto que mais gera reincidência: reemitir um identificador
não basta se o valor reemitido já foi usado alguma vez.

Antes de enviar, confirme com uma busca:

```
GET /fhir/resources/CarePlan?identifier=<system>|<value>
```

Se voltar um recurso em `status: revoked`, gere outro `value`.

> **Warning**
>
> Trate cada inscrição na diretriz como um evento novo, com identificador próprio — e não como uma
> atualização do vínculo do paciente com aquela diretriz. Se o seu sistema de origem deriva o
> identificador do par paciente + diretriz, ele vai colidir na segunda inscrição, sempre.

## `CarePlan can't be updated to status draft`

**Causa.** Envio duplicado. Duas requisições iguais chegaram em sequência rápida: a primeira
criou a diretriz aplicada, e a segunda tentou gravá-la de novo como `draft` — o que seria uma
regressão de status, e é bloqueado.

**O que fazer.** Nada, na maioria dos casos: **a primeira das duas foi processada com sucesso** e
o paciente está na diretriz. Confirme com um `GET` pelo identificador antes de tratar como erro.
Do lado da origem, elimine o reenvio duplicado — ele não é necessário e produz esse erro por
definição.

## `Only Practitioner/Patient type is supported`, e erros de tipo em `subject` ou `author`

**Causa.** Formato dos campos de referência. Três coisas costumam vir erradas ao mesmo tempo:

| Campo                   | Formato correto                                                        |
| ----------------------- | ---------------------------------------------------------------------- |
| `subject`               | Objeto único, com `identifier` **e** `type` explícito (`Patient`)      |
| `author`                | Objeto único, com `identifier` **e** `type` explícito (`Practitioner`) |
| `instantiatesCanonical` | **Lista**, obrigatória — não uma string                                |

**O que fazer.** Corrija os três de uma vez. Enviar `subject` ou `author` como lista, ou sem o
`type`, produz mensagens diferentes para a mesma origem — e corrigir só uma leva à seguinte.

## `does not point to an active care line`

**Causa.** A diretriz referenciada não está vigente. Uma diretriz encerrada continua existindo
para preservar o histórico, mas não aceita novas inscrições.

**O que fazer.** Use uma diretriz ativa. A vigência é definida na plataforma, não pela
integração: confirme com o time de suporte qual diretriz está vigente antes de referenciá-la.

## Paciente não encontrado em `CarePlan.subject`

**Causa.** A diretriz aplicada foi enviada antes do paciente existir na Nilo. É o erro mais
volumoso desse recurso quando uma carga inicial é feita com os dois em requisições separadas.

**O que fazer.** Garanta a ordem: paciente primeiro, diretriz aplicada depois. Numa carga
inicial, envie os dois no mesmo lote transacional com referência interna — veja
[Ordem de envio e processamento](/guia/solucao-de-problemas/ordem-de-envio).

## Aceita com `200`, mas o paciente não aparece na diretriz

Este é o caso que mais parece bug e mais raramente é. Há três causas, e vale checar nesta ordem:

### 1. O processamento em lote ainda não rodou

A atribuição da diretriz ao paciente não é imediata: ela roda em lote, uma vez por dia, fora do
horário comercial. Entre a escrita e a atribuição, o paciente está na fila e não aparece na tela.

**O que fazer.** Aguardar o próximo ciclo. Reenviar não antecipa nada — e, se a diretriz
aplicada já estiver na fila, o reenvio pode voltar com erro de duplicidade, o que dá a
impressão errada de que o primeiro envio falhou.

### 2. O paciente não tem equipe de cuidado

A atribuição exige que o paciente tenha uma equipe de cuidado com o profissional que aquela
diretriz requer. Sem isso, a diretriz aplicada fica aceita, mas não chega a ser aplicada — e
nada na resposta da escrita indica esse pré-requisito, porque no momento da escrita ele ainda
podia ser satisfeito.

**O que fazer.** Envie a equipe de cuidado do paciente antes, ou junto, no mesmo lote. Veja
[Equipe de cuidado e profissionais](/guia/solucao-de-problemas/equipe-e-profissionais). É a causa
mais recorrente de "diretriz sumida", e vale checar sempre.

### 3. Existe um plano de cuidado cancelado com período no futuro

Uma diretriz aplicada cancelada cujo período começa numa data futura é interpretada como "ainda não
é hora de colocar o paciente nessa diretriz", e bloqueia a nova atribuição.

**O que fazer.** Esse caso não se resolve pelo payload — abra um chamado informando o paciente e
a diretriz. Do lado da origem, evite emitir períodos com data futura em cancelamentos.

## O paciente saiu da diretriz e eu não recebi o evento

**Causa.** Saída de diretriz não é um evento separado — ela chega como uma **atualização da
mesma diretriz aplicada**, com `status: revoked` quando o vínculo foi cancelado ou suspenso, e
`completed` quando ele foi concluído.

**O que fazer.** Assine `CarePlan` e trate a mudança de status. Uma assinatura em `CarePlan`
cobre entrada e saída: veja [Webhooks](/guia/solucao-de-problemas/webhooks).