> 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, grupos e status

> Plano de saúde não reconhecido, carteirinha que não aparece, grupos sobrescritos e inativação de paciente.

Cobertura de saúde e grupos de pacientes têm um problema em comum: os dois referenciam **ids
internos da plataforma**, que não são valores que você escolhe. Errar esse valor não costuma
derrubar a requisição de forma óbvia — o recurso é aceito e o dado não aparece na tela. Esta
página cobre isso, mais os casos de status e inativação de paciente.

Os fundamentos estão em [Cobertura de saúde](/guia/recursos/coverage),
[Plano de saúde](/guia/recursos/insuranceplan),
[Grupo de pacientes](/guia/recursos/group) e
[Paciente](/guia/recursos/patient).

## A carteirinha foi aceita e não aparece na tela do paciente

**Causa.** O `Coverage.class.value` não corresponde a nenhum plano de saúde cadastrado. Esse
campo espera o **identificador do plano na Nilo** — não um código do seu sistema, não a sigla do
plano, não o nome dele.

**O que fazer.** Descubra o identificador do plano com uma busca, e use exatamente esse valor:

```
GET /fhir/resources/InsurancePlan
```

> **Note**
>
> Os identificadores de plano de saúde **diferem entre homologação e produção**. Usar em
> homologação o valor de produção não funciona, e é a causa mais comum de "funciona em produção,
> não funciona no teste". Se o plano que você quer testar não existe em homologação, ele precisa
> ser cadastrado antes — abra um chamado pedindo o cadastro e o identificador correspondente.

## A importação da cobertura colide com uma carteirinha cadastrada pela interface

**Causa.** Uma carteirinha cadastrada pela interface da plataforma não carrega o seu
identificador. A busca por identificador não a encontra, a importação tenta criar outra, e as
duas colidem na chave de negócio da cobertura — paciente, plano e número da carteirinha.

**O que fazer.** Envie o número da carteirinha correto: quando o identificador não encontra nada,
a cobertura é reconhecida por paciente + plano + número, e o seu identificador é gravado no
registro existente. A partir daí ela passa a ser sua para atualizar. Se a colisão persistir, o
número enviado provavelmente difere do cadastrado — confira antes de reenviar.

## Como atualizar ou encerrar uma cobertura

**Causa de confusão.** Não existe `PUT`, e não existe exclusão de cobertura.

**O que fazer.** Três regras cobrem todos os casos:

* **Atualizar** — `POST` com o **mesmo** identificador. É upsert; nada é duplicado.
* **Encerrar** — `POST` com o mesmo identificador e `status: cancelled`. A cobertura não é
  apagada: ela fica no histórico como encerrada, que é o comportamento correto para um dado
  clínico-administrativo.
* **Trocar de carteirinha** — encerre a antiga e crie a nova com um identificador **novo**. Não
  reaproveite o identificador da antiga para a nova.

## O status `cancelled` foi aceito e a tela ainda mostra ativo

**Causa.** A tela lê de um cache de alguns minutos. A escrita já valeu.

**O que fazer.** Confirme por um `GET` que o status está `cancelled` e aguarde. Reenviar não
limpa o cache.

## `Group cannot be defined both in extension and contained`

**Causa.** Os grupos do paciente foram enviados pelos dois caminhos ao mesmo tempo — a extensão
de grupo e o `Group` em `contained`. A API não escolhe entre eles.

**O que fazer.** Use `contained` com um `Group` por grupo. É o caminho que suporta mais de um
grupo por paciente, e é o recomendado. Veja
[Grupo de pacientes](/guia/recursos/group).

## O paciente perdeu grupos depois de uma atualização

**Causa.** Historicamente, uma atualização de paciente sem `contained` podia sobrescrever os
grupos existentes. Hoje o comportamento é o esperado: **numa atualização, o que não é enviado é
preservado** — os grupos atuais permanecem, e a extensão de grupo só é considerada no cadastro
de um paciente novo.

**O que fazer.** Se você ainda vê grupos ou unidade mudando após uma atualização, confira se o
payload não está enviando esses campos **vazios** — enviar vazio é diferente de não enviar. Se o
payload não os menciona e a mudança acontece, abra um chamado com o payload e o horário.

## O paciente foi para um grupo que eu não pedi, ou o cadastro foi recusado por falta de grupo

**Causa.** Quando o payload não traz grupo, a unidade de cuidado aplica o grupo padrão dela. Se a
unidade não tem grupo padrão configurado, o grupo passa a ser obrigatório e o cadastro é
recusado.

**O que fazer.** Envie o grupo **explicitamente** em todo cadastro de paciente. Depender do
padrão da unidade funciona até a configuração dela mudar, e então uma carga inteira falha ou vai
para o grupo errado.

> **Note**
>
> A associação a grupo **não é derivada de outro dado**. Ela não vem do plano de saúde, do contrato
> nem da unidade: se o payload não diz a que grupo o paciente pertence, a integração não deduz.
> Numa atualização em que você quer mudar o grupo, o grupo novo tem de estar no payload.

## O grupo referenciado não existe

**Causa.** Duas variações do mesmo problema:

* **Variável de template não substituída** — o `system` do identificador do grupo chega com o
  marcador do template em vez do valor. O grupo é procurado sob um `system` que não existe.
* **Grupos duplicados na origem** — o mesmo grupo emitido com dois ids diferentes pelo sistema de
  origem. Os pacientes se dividem entre os dois, e a atribuição fica errada sem nenhum erro.

**O que fazer.** Valide a substituição de variáveis antes do envio, e garanta unicidade dos
grupos na origem. Se grupos duplicados já entraram, a limpeza envolve os dois lados: você remove
a duplicata na origem, e a Nilo consolida os pacientes.

## O paciente foi inativado e eu não sei por quê

**Causa.** Quase sempre a inativação veio pela própria integração, num payload com
`active: false`. Quando não há extensão de status no payload, o status inativo padrão da unidade
de cuidado é aplicado — o que parece uma inativação "espontânea".

**O que fazer.** Antes de tratar como bug, confira o payload enviado para aquele paciente. Se
`active: false` está lá, a inativação foi pedida — o ajuste é na lógica de envio da origem. Para
registrar um motivo específico de encerramento, use a extensão `patient-status` com o id do
status desejado; os ids disponíveis são os do seu care provider, e você os obtém com o time de
suporte. Veja [Extensões](/guia/conceitos/extensoes).

> **Warning**
>
> Se você usa CPF como identificador de paciente e a sua base tem CPFs repetidos, a inativação
> tende a atingir mais gente do que você esperava, porque dois pacientes distintos casam com a
> mesma chave. Antes de uma carga de inativação em massa, confira a unicidade da chave que você
> está usando.