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

# Atendimentos e agendamento

> Condição roteada para o fluxo errado, erros de período, identificador de agendamento repetido e etiquetas.

Atendimento, evento e agendamento compartilham um traço que causa confusão: o mesmo recurso FHIR
alimenta telas diferentes da plataforma, e o que decide qual é um campo do payload. Errar esse
campo não produz um erro de validação — produz um recurso que foi aceito e foi para o lugar
errado, ou um erro sobre um recurso referenciado que "não existe" quando ele existe.

Os fundamentos estão em [Atendimentos](/guia/recursos/encounter),
[Hospitalização](/guia/recursos/encounter-hospitalization),
[Pronto atendimento](/guia/recursos/encounter-emergency) e
[Agendamento](/guia/recursos/appointment).

## `Encounter does not exist` e `Unable to locate Nilo model for the resource`

**Causa.** A `Condition` foi roteada para o fluxo errado. O campo `category` é o que decide:

| `Condition.category` | Para onde vai              | Que atendimento ela procura                           |
| -------------------- | -------------------------- | ----------------------------------------------------- |
| com `event`          | Diagnóstico de evento      | O `Encounter` de hospitalização ou pronto atendimento |
| sem `event`          | Diagnóstico de atendimento | O atendimento comum do prontuário                     |

Sem `category`, uma condição ligada a uma hospitalização é tratada como diagnóstico de
atendimento e vai procurar um atendimento comum — que não existe. Daí o `Encounter does not
exist` sobre um `Encounter` que você acabou de criar com sucesso.

**O que fazer.** Sempre que a condição estiver associada a um evento de hospitalização ou pronto
atendimento, envie `category` com `system` e `code` de `event`. Veja
[Condição](/guia/recursos/condition).

> **Warning**
>
> Se você já enviou a condição sem `category` e o identificador ficou gravado no fluxo errado,
> corrigir o payload e reenviar com o **mesmo** identificador tende a produzir um erro diferente,
> não o sucesso — o identificador já está associado ao outro fluxo. Nesse caso, abra um chamado
> com o identificador afetado.

## `period.end` menor ou igual a `period.start`

**Causa.** O período do atendimento é validado: o fim não pode ser anterior nem igual ao início.

**O que fazer.** Confira o fuso e o formato das duas datas. Períodos de duração zero — início e
fim idênticos — também são recusados: se o atendimento não tem duração conhecida, envie só o
`start`.

## O mesmo identificador de agendamento chegou em datas diferentes

**Causa.** Não é duplicidade. Um agendamento tem ciclo de vida: ele pode ser cancelado,
reagendado e concluído, e cada mudança de status gera uma notificação — todas com o **mesmo**
identificador, porque é o mesmo agendamento.

**O que fazer.** Trate a notificação como "o estado atual deste agendamento é este", não como
"um novo agendamento chegou". Antes de tratar como duplicidade, olhe o `status` de cada evento na
sequência: `cancelled` seguido de `booked` seguido de `fulfilled` é um reagendamento normal.

## Cancelar um agendamento

**Causa de confusão.** Um agendamento cancelado não tem horário: ao cancelar, o início e o fim
deixam de existir.

**O que fazer.** Envie `status: cancelled` sem `start` e sem `end`. Isso é válido, e o
cancelamento é aplicado.

## Conflito de horário no agendamento

**Causa.** A plataforma sabe conferir a agenda do profissional antes de gravar, e três coisas
recusam o agendamento: colidir com outro compromisso dele, cair **fora da grade de atendimento**
dele, ou repetir um horário em que o mesmo paciente — ou o mesmo profissional — já tem
agendamento. As duas primeiras vêm como `400` com `code: exception`; a terceira, como `409`.

**Pela integração essa conferência não roda por padrão:** um `Appointment` sem a extensão
`appointment-allowConflict` é gravado como se ela viesse com `valueBoolean: true`. Se você está
vendo uma dessas recusas, o envio traz a extensão com `false`.

**O que fazer.** Remova a extensão, ou envie-a com `valueBoolean: true`. Se a conferência é mesmo
o que você quer daquele agendamento, mantenha o `false` e corrija o horário.

**A extensão é tudo ou nada.** `true` dispensa as três conferências juntas — não há como liberar
o encaixe e continuar barrando horário fora da grade.

**E o efeito não para naquele agendamento.** Um agendamento gravado com `true` deixa de bloquear
os seguintes: outro agendamento no mesmo horário passa a ser aceito, inclusive sem extensão e
inclusive pela tela. Como `true` é o padrão, na prática a conferência de agenda não está valendo
para o que entra por integração.

**Cuidado com o caso inverso.** Um `false` explícito **não** garante a conferência: se a
configuração de sobreposição do care provider está habilitada, a sobreposição continua permitida
e a resposta devolve `true`. Não há como recusá-la agendamento por agendamento.

**Na atualização, omitir a extensão apaga o `false`.** O padrão vale em toda escrita: um update
sem a extensão sobrescreve com `true` o `false` gravado antes. Reenvie o `false` em cada update
daquele agendamento.

Os detalhes e os payloads estão em [Agendamento](/guia/recursos/appointment).

## O diagnóstico enviado não aparece no atendimento

**Causa.** Um diagnóstico só aparece na tela do paciente quando está associado ao atendimento ou
evento a que pertence. Um diagnóstico enviado solto é gravado, mas não tem onde ser exibido.

**O que fazer.** Envie a condição referenciando o `Encounter` correspondente, com a `category`
certa para o tipo daquele atendimento — as duas coisas juntas, porque a `category` é o que define
qual atendimento a referência procura.

## Etiquetas

Duas mensagens aparecem com frequência ao registrar etiquetas — veja
[Etiqueta](/guia/recursos/flag) para os campos.

### `does not allow changing tag_id or patient_id after creation`

**Causa.** O `identifier.value` enviado pertence a uma etiqueta **já vinculada a outro
paciente**, ou a outra etiqueta do mesmo paciente. O vínculo entre etiqueta e paciente é fixo
depois de criado.

**O que fazer.** Use um identificador único por combinação de etiqueta e paciente. Não
reaproveite o identificador de uma etiqueta ao aplicá-la a outro paciente.

### `Period is required to create inactive flags`

**Causa.** Uma etiqueta criada já inativa precisa dizer em que período ela valeu — sem isso, ela
seria um registro inativo sem vigência.

**O que fazer.** Envie o `period` junto. Se a etiqueta é ativa, o período é opcional.