Tarefa

Este recurso é somente leitura. Não existe POST /fhir/resources/Task — tarefas são criadas dentro do NiloCare ou pela diretriz que as gera. Veja O que a integração não cobre para o que acontece se você tentar enviá-la mesmo assim.

Filtrar por origem na busca não é confiável. code é um parâmetro de token, e a plataforma preenche code só com text, sem coding — buscar code=patient-questionnaire não encontra nada. Por identifier, a sintaxe de token do FHIR admite filtrar só pelo system (identifier=…|, com o valor vazio); esse recorte, como o modificador :text no code, não foi confirmado neste store. Enquanto isso, o caminho seguro é trazer as tarefas do paciente e separar as duas origens no seu lado.

executionPeriod não é o prazo, e também não é quando a tarefa foi de fato iniciada. Na tarefa da equipe, executionPeriod.start repete a data de criação — o mesmo valor de authoredOn — e end só aparece depois de concluída. O momento em que alguém efetivamente começou a tarefa existe na plataforma (é o que faz o status virar in-progress) e não é exposto: não há como medir quanto tempo a tarefa levou entre começar e terminar.

O prazo combinado está em restriction.period.end, e restriction.period.start nunca vem preenchido.

No questionário do paciente o executionPeriod é outra coisa: é o período de vigência da atividade. O end traz a data em que foi respondido quando já houve resposta, e o fim do período de vigência quando não houve — então, num questionário ainda em aberto, end não indica conclusão. Essa origem não tem restriction, então não há um campo separado de prazo para comparar.

executionPeriod.end da tarefa da equipe é o maior entre a data de criação e a data de conclusão. A plataforma admite registros com conclusão anterior à criação, e o campo é calculado assim para nunca devolver um período invertido. Se você compara as duas pontas esperando a diferença exata entre criar e concluir, num registro assim ela sai zerada.

Duas armadilhas aqui, e as duas geram interpretação errada:

• urgent é a prioridade normal. Uma tarefa comum, sem nenhuma urgência marcada pela equipe, chega com priority: urgent. Não a trate como prioritária, e não conte urgent como sinal de risco.
• routine é ambíguo. Baixa e Baixíssima saem as duas como routine, e não há como distinguir uma da outra pela API.

Não existe cancelled neste recurso. Uma tarefa apagada no NiloCare não muda de status: ela é removida do store, e o id que você já leu com sucesso passa a responder 404 sem aviso nenhum. Se você guarda o conteúdo de uma tarefa, guarde o conteúdo — não o id.

status também não diz se a tarefa está atrasada. Atrasada é a comparação do prazo com a data de hoje, e a tela a mostra como tag; a API não traz esse cálculo. Compare restriction.period.end com a data corrente.

Vale para code, requester e performerType. Removido o tipo da tarefa, ou o solicitante, a leitura continua devolvendo o valor antigo indefinidamente.

O caso mais enganoso é performerType: ele é a especialidade do responsável atual, mas só é reescrito quando o novo responsável tem alguma especialidade cadastrada. Passar a tarefa para alguém sem especialidade deixa ali a especialidade do responsável anterior. Não use performerType para deduzir quem é o responsável — para isso existe owner.

output[] está na mesma situação, por um motivo diferente: a lista é omitida quando fica vazia, e o valor gravado antes é o que continua sendo devolvido.

note[] é a exceção real: removidas as anotações, elas somem da leitura.

note[].authorReference vem só quando quem anotou foi um profissional. Anotação registrada por automação da plataforma vem sem autor, e o mesmo acontece quando o profissional que anotou não é mais localizável. Trate a ausência de authorReference como “autor não identificado”, não como erro.

A lista está ordenada como a plataforma a devolve, não necessariamente por time.

output é o elo com o Questionário respondido: o item questionnaire-response é a chave para ler o conteúdo das respostas. Enquanto o paciente não responde, esse item simplesmente não existe.

Diferente das outras referências deste recurso, as de output vêm por identificador, sem reference — resolva-as por uma busca por identifier, não por leitura direta.

O item questionnaire-response pode apontar para uma submissão que a busca de Questionário respondido não devolve: uma submissão sem nenhuma resposta válida não chega a existir como recurso FHIR. A referência fica lá, irresolvível.

O contrário também acontece: não toda resposta de questionário tem uma tarefa. Só o questionário atribuído ao paciente gera Task — um questionário respondido fora desse fluxo existe como resposta e não aparece neste recurso.

Um POST /fhir/resources/Task não é uma operação suportada e não devolve um erro de validação tratável: com um corpo válido, a chamada falha com erro inesperado do servidor (500). Não escreva tratamento em cima desse comportamento — ele não é contrato, e nada é gravado no NiloCare de qualquer forma. Um corpo malformado responde 400 antes disso, pela validação do recurso — não conclua daí que a operação existe.

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

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.

As referências deste recurso trazem reference e identifier, então as duas formas de busca por referência estão disponíveis: patient=Patient/{id}, com o id Nilo FHIR, e patient:identifier=system|valor, com o identificador do paciente. A segunda é a prática, porque dispensa conhecer o id do store.

Isso não vale para todos os recursos desta API — em Avaliação clínica, por exemplo, as referências saem sem reference e só a forma com :identifier encontra algo.

Qual identificador do paciente o for 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 for 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. O mesmo vale para owner e requester.

Vários parâmetros canônicos da Task existem e não encontram nada aqui, porque a plataforma não preenche o campo correspondente: based-on, part-of, focus, encounter, business-status e group-identifier.

code e performer são um caso diferente, e mais traiçoeiro: os campos existem e vêm preenchidos, mas só com text, sem coding — e os dois parâmetros são de token, que procura em coding. Buscar o tipo de tarefa ou a especialidade do responsável pelo valor puro não encontra nada. O modificador :text do FHIR existe justamente para procurar no text, mas o suporte a ele neste store não foi confirmado — não conte com ele sem testar.

intent funciona, e por isso é inútil: o valor é constante, então intent=order traz todas as tarefas.

Não há parâmetro para output, então não se busca a tarefa a partir do questionário ou da resposta dele. O caminho é o inverso: leia a tarefa e siga o output.

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

A geração é assíncrona. Confirmada a aplicação da diretriz, as tarefas levam um tempo para existir, e esse tempo é decidido pela plataforma — não há garantia de prazo. Uma busca imediata que não devolve nada não significa diretriz sem tarefas: significa que a geração não terminou. Reconsulte em vez de tratar a primeira resposta vazia como definitiva; o sinal de que a geração acabou é a activity aparecer no plano de cuidado.

Nem toda tarefa vem de uma diretriz, e a API não diz de onde a tarefa veio. A ausência de requester é um indício, não uma garantia. Para saber quais tarefas pertencem a um plano, leia o activity[] do plano — é lá que o vínculo está.

performerType[0] tem a forma de um código FHIR, mas não é um: traz apenas text, com o nome da especialidade. Não há system nem code para casar com um catálogo.