Consulta prevista

Este recurso é somente leitura. Não existe POST /fhir/resources/Schedule — as consultas previstas são geradas pela plataforma a partir da diretriz, e não há como criá-las, alterá-las ou cancelá-las por esta API.

As mesmas consultas previstas também aparecem em activity[] da diretriz aplicada do paciente, junto com as tarefas e os questionários que a diretriz gerou. A vantagem desta página é poder buscá-las diretamente, sem passar pela diretriz aplicada.

specialty vem sempre — a especialidade é obrigatória do lado da plataforma. serviceType, não: só aparece quando o tipo de atendimento está definido, e o vocabulário dele é o da plataforma, não uma lista fixa deste contrato.

active: true não quer dizer que a consulta foi marcada. Uma consulta prevista que o paciente ainda não agendou e uma que ele já agendou saem exatamente iguais aqui. E active: false junta o cancelamento, a conclusão e a desatualização num valor só.

Se a sua integração precisa saber se a consulta aconteceu, este recurso não responde. O agendamento de verdade é outro recurso, e a consulta prevista não traz referência para ele — mas o activity[] da diretriz aplicada traz.

E há uma segunda situação, que não é a mesma coisa. Além da situação acima, a equipe pode marcar uma consulta prevista à mão como feita ou não feita. Esse segundo eixo não mexe no active: uma consulta marcada à mão como feita continua active: true — e, apesar disso, ganha um planningHorizon.end.

O único lugar onde essa marcação aparece é o comment, como manual-status:done ou manual-status:not_done. Não conte com active para saber se a consulta foi resolvida.

O selo Atrasada, que a equipe vê quando o prazo de agendar passou, também não tem campo aqui: uma consulta prevista atrasada continua active: true.

Os selos que a equipe vê não são um por situação: a tela combina a situação, o atraso e a marcação manual antes de escolher o selo, e mais de uma situação desta tabela pode aparecer sem selo nenhum. Não tente casar active com o que está na tela.

planningHorizon.start é a data prevista para a consulta, e planningHorizon.end é o instante em que a consulta prevista foi encerrada — não a data limite para marcá-la.

Três consequências:

• numa consulta prevista em aberto, planningHorizon vem só com start. Um cliente que espere sempre os dois extremos quebra;
• end aparece também quando a equipe marca a consulta à mão como feita — e nesse caso active continua true. Ver end preenchido não significa active: false;
• end é um instante com hora, enquanto start é uma data pura. Eles não descrevem a mesma coisa e não formam um intervalo de agenda.

O prazo para o paciente marcar não tem campo neste recurso. Ele aparece na diretriz aplicada, em activity[].detail.scheduledPeriod, como uma janela fixa de sete dias a partir da data prevista.

Quando há motivo de cancelamento ou situação marcada à mão, comment traz os dois num texto montado internamente:

cancelled-reason:Paciente remarcou | manual-status:not_done

Não é contrato. O formato pode mudar sem aviso, os valores não são traduzidos e não há garantia de que os dois pedaços apareçam. Use comment só para exibição a um humano, e nunca faça parsing dele.

Quando não há nem motivo de cancelamento nem situação manual, o campo não vem.

Um cancelled-reason não implica consulta cancelada. Cancelar o agendamento sem remover a consulta prevista devolve ela para disponível — e o motivo do cancelamento fica gravado. Você verá active: true com um cancelled-reason no comment.

Na prática o paciente vem primeiro e o profissional depois, mas isso não é garantido: se o paciente não puder ser resolvido, o profissional ocupa a primeira posição e o array vem com um item só.

Case pelo actor[].type — Patient ou Practitioner —, nunca por índice.

Qual identificador a referência de actor carrega depende da sua implantação. Na configuração que usa identificadores externos, cada referência sai com o identificador do seu sistema se o recurso apontado tiver um; se não tiver, cai silenciosamente no identificador Nilo. Confira o que veio na resposta antes de montar a busca em volume.

specialty e serviceType são CodeableConcept, mas vêm só com text, nunca com coding. Não há código para casar com um catálogo: o que você recebe é o nome, como ele está cadastrado — e, por isso, não há como buscar por eles (veja Parâmetros de busca).

specialty ainda tem uma degradação silenciosa: quando a especialidade não tem nome cadastrado, o text traz o identificador numérico dela — um valor como "418", que parece um nome e não é. Se o texto for só dígitos, trate como desconhecido.

Um POST /fhir/resources/Schedule não é uma operação suportada e não devolve um erro de validação tratável: a chamada falha com erro inesperado do servidor (500). Não escreva tratamento em cima desse comportamento — ele não é contrato, e nada é gravado de qualquer forma.

Dentro de uma carga em lote o erro é limpo, e igualmente definitivo: a entrada é recusada com Resource Schedule not supported.

Em date, prefira o prefixo ge. Como a consulta prevista em aberto não tem planningHorizon.end, o período é semanticamente aberto, e eq e le sobre um período aberto se comportam de forma pouco intuitiva.

actor não distingue paciente de profissional. É um só parâmetro para os dois papéis: buscar por um profissional devolve as consultas previstas em que ele é o profissional, e buscar por um paciente devolve as dele — mas não há como pedir “as consultas em que este paciente é o paciente” de forma explícita. Na prática isso não gera confusão, porque um identificador de paciente não casa com um profissional.

Os demais parâmetros canônicos do Schedule existem e não encontram nada aqui: service-category, porque a plataforma não preenche o campo; e specialty e service-type, porque os dois são parâmetros de token, que procuram dentro de coding — e a Nilo preenche só o text. Buscar pelo nome da especialidade ou do tipo de atendimento não devolve nada.

Não há parâmetro que ligue a consulta prevista à diretriz aplicada que a gerou. Para listar as consultas previstas de uma diretriz aplicada, leia o activity[] da diretriz aplicada.

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 consulta prevista está em resource. Ler active ou planningHorizon na raiz da resposta não encontra nada.