Diretriz aplicada

O conteúdo da diretriz — as consultas, tarefas e questionários que ela gera — é montado pela equipe no NiloCare, não por esta API. O que você faz aqui é aplicá-la, e para isso precisa da URL da diretriz, que a busca de diretrizes devolve. O cabeçalho da diretriz (nome, descrição e tipo) esse sim é gravável — veja Diretriz.

Os dois erros vêm da plataforma, não da validação do recurso: saem com expression igual a CarePlan.? e com o motivo em texto (patient_without_care_team, todo_without_responsible). CarePlan.? não é FHIRPath válido — não tente resolvê-lo automaticamente para apontar o campo culpado.

author é a exceção que morde. Ele não grava nada — nem o profissional que aplicou a diretriz — mas, ao contrário dos outros, é validado. O type é conferido em toda escrita: qualquer coisa diferente de Practitioner recusa a chamada. E, nas chamadas que criam ou recriam a diretriz aplicada, o identificador também é resolvido: um profissional inexistente ou inativo recusa a escrita inteira. Num encerramento ou cancelamento o identificador nem chega a ser consultado.

Como não há benefício algum em enviá-lo, não envie. Ele não aparece na referência do recurso justamente por isso; as linhas de erro abaixo existem para quem já o manda hoje.

A resolução aceita duas formas: a API tenta primeiro o último segmento da URL como id do recurso e, não achando, procura uma diretriz cujo campo url seja exatamente o que você enviou. Nos dois caminhos a diretriz precisa estar com status: active.

A URL embute o host do ambiente. Um payload com a URL de produção enviado para o ambiente de homologação é recusado antes de qualquer validação de negócio, com a mensagem Resource has identifier from a Nilo environment that is not the current environment. Ao promover uma integração entre ambientes, troque o host de todos os instantiatesCanonical.

A aplicação imediata confirma a criação da diretriz aplicada, não a geração dos itens. As tarefas, os agendamentos, os questionários e as mensagens são gerados depois, de forma assíncrona, e a geração pode levar alguns minutos.

O status da resposta repete o que você enviou, não o estado derivado da diretriz aplicada na plataforma. Uma aplicação imediata responde active mesmo enquanto os itens ainda estão sendo gerados — nesse intervalo a diretriz aplicada vale como pendente do outro lado, e uma leitura posterior pode trazê-la como on-hold, sem activity. O sinal de que a geração terminou é a activity aparecer numa leitura, não o status da resposta ao POST.

Uma diretriz aplicada criada com status: draft não tem identificador Nilo: nada foi criado na plataforma ainda. O recurso FHIR é o seu próprio payload, sem title, sem category, sem period e sem activity. Não conte com esses campos antes de a alocação acontecer — e veja o que isso implica para cancelar uma diretriz aplicada ainda na fila.

subject.identifier volta trocado. Você envia o identificador do seu sistema, e a resposta traz o identificador Nilo do paciente (…/NamingSystem/hippocrates-api--patient). Não é perda de dado: é a referência que a plataforma usa internamente. Leituras posteriores da mesma diretriz aplicada podem trazer o seu identificador de volta, dependendo da configuração da sua implantação.

A célula que costuma surpreender é a da última coluna: enviar um identifier novo para um paciente que já está naquela diretriz não cria diretriz aplicada nenhuma e não devolve erro. A resposta é 200 com a diretriz aplicada que já existia, agora carregando também a sua chave. Se o seu integrador conta chamadas bem-sucedidas como diretrizes aplicadas criadas, ele vai contar errado. Confira o identificador Nilo da resposta antes de concluir que aplicou a diretriz — e note que o status da resposta não ajuda nessa distinção, porque ele repete o que você enviou.

Um paciente tem, no máximo, uma diretriz aplicada não terminal por diretriz. Havendo mais de uma no store — estado inconsistente, que não deveria acontecer — a escrita falha com IntegrityError: has more than one Care Plan for Patient and PlanDefinition, e o caso é de chamado no Suporte.

revoked e completed são terminais. Uma diretriz aplicada nesses estados não aceita mais nenhuma atualização: qualquer POST que o alcance pelo identifier é recusado com CarePlan with status … can't be updated.

Para aplicar a mesma diretriz de novo ao mesmo paciente, envie um identifier novo. Isso é deliberado: cada aplicação é uma entrada distinta no histórico do paciente naquela diretriz, com a data em que entrou e a data em que saiu.

entered-in-error é o único estado não terminal do qual se volta. Uma diretriz aplicada que falhou na alocação em massa pode ser reenviada com status: active, e aí uma nova é criada — ou com status: draft, e ela volta para a fila.

entered-in-error tem, na plataforma, o mesmo efeito de revoked. A distinção existe no recurso FHIR, não no registro.

Uma diretriz aplicada ainda em draft não pode ser cancelada. Ela existe só como recurso FHIR, e o cancelamento precisa de um registro na plataforma para atualizar — a chamada falha com CarePlan with nilo identifier does not exist, e o paciente continua na fila.

Duas saídas: esperar a alocação acontecer e cancelar depois, ou aplicá-la agora enviando um identifier novo com status: active — é esse caminho, e não o reenvio sem identifier, que promove uma diretriz aplicada da fila. Aplicada, ela passa a aceitar o cancelamento.

Essa mensagem não é exclusiva do draft: ela aparece sempre que o recurso alcançado não carrega o identificador Nilo da diretriz aplicada. A diretriz aplicada na fila é o caso comum porque nunca teve um — mas um recurso active que tenha perdido o identificador falha igual.

A janela de scheduledPeriod é fixa em sete dias: o fim é sempre sete dias depois do início. Ela não reflete um prazo configurado na diretriz.

Tarefas e questionários compartilham o type: Task da referência, e se distinguem pelo system do identificador. Nos dois casos o item é lido como Tarefa — o questionário da diretriz aplicada é uma tarefa atribuída ao paciente, não a resposta dele. As respostas são outro recurso, o Questionário respondido, e não é para ele que esta referência aponta.

Um item pode vir sem reference, sem progress e sem detail. Acontece quando o item já tem agendamento, mas o agendamento está num estado que esta integração não representa.

Qual identificador as referências de activity carregam depende da mesma configuração de implantação que vale para subject: com identificadores externos ligados, vem o identificador do seu sistema; sem ela, o identificador Nilo. Confira numa resposta real antes de casar as referências com os seus registros.

Uma diretriz aplicada na fila ou ainda em geração (status: on-hold) volta sem activity. A lista vazia não significa diretriz sem itens: significa que a geração não terminou. Não conclua nada sobre o conteúdo de uma diretriz aplicada até ela estar active.

Busca sem resultados não é erro: volta 200 com um Bundle cujo entry é uma lista vazia. Trate a ausência de resultados pela lista vazia, não esperando um 404.

Qual identificador do paciente o subject carrega depende da sua implantação. Na configuração que usa identificadores externos nas referências, é o identificador do seu sistema — e o filtro acima funciona como está. Sem ela, o subject traz o identificador Nilo do paciente (…/NamingSystem/hippocrates-api--patient), e é esse system que você tem de usar no filtro. Confira numa resposta de leitura qual dos dois está lá antes de montar a busca em volume.

Vários parâmetros canônicos da CarePlan existem e não encontram nada aqui, porque a Nilo não preenche o campo correspondente: care-team, condition, goal, encounter, based-on, replaces, part-of, performer, activity-code e activity-reference.

intent é um caso diferente: ele funciona, e por isso é inútil — o valor é constante, então intent=order traz todas as diretrizes aplicadas.

category é um caso à parte: o tipo da diretriz vem apenas como texto em category[0].text, sem coding. Uma busca por token no category não encontra a diretriz aplicada por care_line nem por protocol.

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 diretriz aplicada está em resource. Ler status ou activity na raiz da resposta não encontra nada.

É o único caso em que note aparece numa diretriz aplicada. Uma diretriz aplicada com note preenchido é sempre uma diretriz aplicada que falhou.

status: active cria a diretriz aplicada na plataforma durante a requisição. É a única escrita desta página que altera o cadastro do paciente de forma imediata — e o que ela dispara em seguida (geração de tarefas, agendamentos, questionários e mensagens) acontece de forma assíncrona, fora do controle da chamada.

revoked e completed tiram o paciente do acompanhamento e são irreversíveis. A diretriz aplicada deixa de estar em execução e não aceita mais nenhuma atualização. O que acontece com as tarefas e mensagens ainda não executadas é decidido pela plataforma, fora do alcance desta chamada — não conte com elas depois de encerrar a diretriz aplicada.

Um identifier novo num paciente já alocado não cria diretriz aplicada. A chamada responde 200 com a diretriz aplicada existente e a sua chave anexada a ele. Veja a tabela em Como a API reconhece o plano.

Este endpoint não remove diretrizes aplicadas: a escrita nunca responde 204. O que existe é o cancelamento, por revoked — e ele preserva o registro no histórico do paciente.

Cinco linhas da tabela trazem expression que não é FHIRPath válido: as duas de CarePlan.?, que vêm da plataforma, e as três de CarePlan.None. Some-se a elas a linha de exception, que vem sem expression nenhum. Um integrador que usa o expression para destacar o campo culpado precisa tratar esses casos à parte.