Diretriz

Esta API grava o cabeçalho da diretriz, não o conteúdo dela. Nome, descrição e tipo são graváveis. As consultas previstas, as tarefas, os questionários e as mensagens programadas que a diretriz gera são montados pela equipe no Nilo Care — e uma diretriz criada por aqui nasce vazia, sem gerar nada quando aplicada a um paciente.

Na prática, o uso mais comum deste recurso é de leitura: descobrir a URL da diretriz para aplicá-la.

O tipo é uma convenção de uso, não uma regra que a plataforma aplique: a duração da diretriz é um campo à parte, e nada impede uma linha de cuidado com término definido nem um protocolo sem. A duração, aliás, não é gravável nem legível por esta API — é configurada no Nilo Care.

O status é derivado da vigência: active enquanto a data de hoje está dentro do effectivePeriod, retired fora dele — antes do início e depois do fim. Uma diretriz sem período nenhum é sempre active.

Os dois são definidos na plataforma. Enviar status ou effectivePeriod não tem efeito: o status é obrigatório pelo FHIR, então mande active e ignore o que ele significa na escrita.

Só diretriz active pode ser aplicada a um paciente. Uma retired continua aparecendo na busca — e uma diretriz cujo início ainda não chegou também é retired —, mas um plano de cuidado que a referencie é recusado com does not exist or is not active. Filtre por status=active antes de aplicar.

action é o campo em que o FHIR descreve o conteúdo de uma diretriz, e ele não é suportado. Não há como enviar as consultas, tarefas ou questionários da diretriz por esta API, nem lê-los. O que a diretriz gera só se vê depois de aplicada, em CarePlan.activity[] — veja Plano de cuidado.

Repare também em title: o FHIR distingue name (identificador legível) de title (nome de exibição), e aqui só o name é lido. É ele que a equipe vê.

E a duração da diretriz, que o Nilo Care pede no cadastro, não tem campo aqui: não é gravável nem legível por esta API.

A referência lista só os campos suportados, e é assim que ela deve ser lida: o que mandar na escrita. A API em si não recusa quem manda os outros — eles ficam guardados no recurso e voltam nas leituras seguintes, sem nunca terem significado nada para a plataforma. Omita-os.

A resolução 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 active.

A forma pelo id embute o host do ambiente, e o id é diferente em cada um. Uma integração que promove configuração entre homologação e produção tem de reescrever essas URLs. Definir uma url própria em cada diretriz resolve isso de vez: o mesmo valor funciona nos dois ambientes.

type é o único campo desta página com preservação por omissão:

• numa diretriz existente, omitir type mantém o tipo que ela já tem;
• numa diretriz nova, omitir type cria uma linha de cuidado.

A API varre todos os coding e usa o primeiro cujo system seja o de tipo de diretriz do HL7, em qualquer posição da lista. Um coding em outro system, ou com um código fora dos dois aceitos, é ignorado — e cai na mesma regra da omissão, sem erro.

name e description, ao contrário, não são preservados: uma atualização sem description apaga a descrição. O exemplo acima faz exatamente isso — repare que ele não traz description. Reenvie os dois sempre.

A url tem de ser única. Uma URL já usada por outra diretriz recusa a chamada com 409, e o mesmo acontece quando a url e o identifier do payload apontam para diretrizes diferentes — o caso clássico de copiar um payload e trocar só a chave.

São os dois únicos 409 deste recurso.

Defina a url na mesma chamada em que cria a diretriz. Acrescentá-la depois, sem mudar nome, descrição ou tipo, pode não ter efeito: a plataforma reconhece que nada mudou do lado dela e devolve o recurso como já estava, com 200 e sem gravar a URL. O mesmo vale para acrescentar um identifier seu ou qualquer outro campo que a plataforma não guarda.

Confira a url na resposta. Se ela não voltou, reenvie junto com uma alteração real — de nome ou de descrição.

Os demais parâmetros canônicos do PlanDefinition — title, version, date, publisher, context, jurisdiction, topic, composed-of, depends-on, derived-from, predecessor e successor — só encontram o que você tiver enviado: a Nilo não preenche esses campos, mas guarda o que vier no payload. Numa diretriz criada pela plataforma eles vêm vazios, e a busca não devolve nada.

Uma diretriz antiga, que ninguém tenha tocado desde que a sua integração começou, pode não aparecer na lista. Se você espera uma diretriz e ela não vem, peça ao Suporte: a busca não é um inventário garantido.

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

Criar ou renomear uma diretriz não afeta os pacientes que já estão nela. Os planos de cuidado existentes continuam como estão; o que muda é o nome exibido.

Mudar o type de uma diretriz com pacientes é uma decisão de negócio, não de integração. Linha de cuidado e protocolo têm regras de duração diferentes. Se a sua integração sincroniza o tipo a partir de um sistema seu, confira antes que a mudança é intencional.

Uma diretriz excluída no Nilo Care some daqui. Ela não vira retired: o recurso deixa de existir, a leitura por id passa a responder 404 e ela some da busca — sem aviso. Se você guarda o conteúdo de uma diretriz, guarde o conteúdo, não o id.

Este endpoint nunca responde 204: não há remoção de diretriz por integração.

A linha exception não é uma validação desta API — é a recusa da própria plataforma, repassada como está. Ela sai sem expression e com uma mensagem de erro de linguagem, que inclui o endereço interno chamado. Nada disso é contrato: não interprete o texto e não o exiba para o usuário final.