Procedimento
Um procedimento aqui é uma cirurgia do paciente: o que foi feito, por quem, onde e em que período. No Nilo Care ele aparece na linha de eventos da ficha do paciente, ao lado das hospitalizações e dos atendimentos; o card da linha mostra Procedimento, Profissional e as datas, e o detalhe da cirurgia mostra também Lateralidade, Endereço, Data de entrada, Data de saída, Horário, Duração e Informações adicionais.
No FHIR o recurso é o Procedure, e esta
integração o usa nas duas pontas: registrar uma cirurgia e consultar as que o paciente tem.
O procedimento é identificado por um código de tabela — TUSS ou Tabela SUS —, e o código enviado precisa existir no catálogo da plataforma. É a recusa mais comum deste recurso; veja Valores aceitos.
Campos
A coluna No Nilo Care traz o rótulo com que o dado aparece para a equipe; são rótulos, não caminhos de navegação.
Nove campos são obrigatórios: resourceType, identifier, status, code, subject,
performer, location e os dois extremos de performedPeriod. Confira a lista acima antes de
enviar.
Os dois que o próprio FHIR exige — status e subject — são recusados com o caminho do campo
em expression. Os outros sete não: a recusa vem com uma mensagem genérica, em inglês, sem
apontar o campo. Veja Erros.
status não é conferido contra o período
O status que você envia é gravado e devolvido como veio — a plataforma não o valida
contra o performedPeriod. Mandando completed num procedimento marcado para o mês que vem, é
completed que a leitura devolve.
A plataforma tem o seu próprio cálculo, a partir do período: preparation antes do início,
in-progress durante, completed depois do fim. Mas ele só vale do lado dela, e só chega
ao recurso quando a equipe edita o procedimento no Nilo Care — nesse momento o valor calculado
substitui o seu.
Consequência prática: status não é uma fonte confiável para saber se o procedimento já
aconteceu. Num procedimento vindo de integração ele é o que você mandou; num editado pela
equipe é o que valia no momento daquela edição, e nunca é recalculado depois.
Para saber se já aconteceu, compare o performedPeriod com a data de hoje do seu lado.
Se você mandar not-done, on-hold, stopped ou entered-in-error, o valor é gravado e
devolvido — mas ele não significa nada para a plataforma: o procedimento aparece na ficha
do paciente do mesmo jeito, e a equipe não vê nenhuma marca de cancelamento. Não há como
registrar um procedimento cancelado por esta API.
Campos que a Nilo não usa
O Procedure canônico traz muito mais do que esta integração lê: basedOn, partOf,
statusReason, category, encounter, performedDateTime, recorder, asserter,
reasonCode, reasonReference, outcome, report, complication, followUp,
focalDevice, usedReference e usedCode. Dentro de performer, também function e
onBehalfOf. Nenhum deles é lido, e por isso nenhum aparece na referência do recurso.
Dois merecem aviso, porque é natural mandá-los:
category— oProceduredo FHIR costuma vir com uma categoria SNOMED (Surgical procedure). Aqui ela é aceita e não significa nada: quem classifica o procedimento é ocode.performedDateTime— só operformedPeriodé lido. Um procedimento enviado comperformedDateTimeé recusado por falta de período.
A referência lista só os campos suportados, e é assim que ela deve ser lida: o que mandar na escrita. A API em si é mais tolerante — o que você mandar a mais fica guardado no recurso e volta nas leituras seguintes, sem nunca ter significado nada para a plataforma. Se o seu validador for estrito contra a referência, uma resposta assim vai parecer inválida; o remédio é não enviá-los.
Cadastrar ou atualizar
A resposta é o recurso gravado, sem envelope:
Guarde o id: é por ele que se faz a leitura direta. Ao lado do seu identifier, a resposta
traz o identificador Nilo do procedimento, no system
…/NamingSystem/hippocrates-api--patient-surgery.
O mesmo POST cria e atualiza. Reenviando um identifier que já corresponde a um
procedimento, ele é atualizado.
Reenvie o recurso inteiro em toda atualização. O que você omitir é apagado do Nilo Care:
um POST de atualização sem note limpa as informações adicionais na ficha, e sem bodySite
limpa a lateralidade.
E o pior é que você não vê isso na leitura: do lado FHIR, o campo omitido é preservado, e a consulta continua devolvendo o valor antigo — um valor que a equipe já não vê. Depois de uma atualização parcial, o recurso e a ficha do paciente ficam divergentes, e a API mostra a versão desatualizada.
O procedimento
O código vai em code.coding[0], e só o primeiro item da lista é lido:
O display que você mandar é guardado e devolvido como veio — mas não significa nada: quem
identifica o procedimento é o par system + code. O nome do catálogo é o que a equipe vê na
tela, e ele só aparece no recurso quando o procedimento é criado ou editado dentro do Nilo Care.
Ou seja: o display de um procedimento que você criou é o seu texto, não o da plataforma.
Não o use para conferir se o código foi entendido — para isso, olhe se a chamada foi aceita.
O local
O local é texto livre, em location.display:
Por compatibilidade, um location.identifier apontando para um
local de atendimento já cadastrado também é aceito, e o
nome daquele local é o que a equipe passa a ver na ficha. Não há vínculo: alterar o local
depois não muda o que ficou no procedimento.
Mas atenção: mandando identifier, é identifier que a leitura devolve — o display não
é preenchido a partir dele. Quem consome o recurso não encontra o nome do local em lugar nenhum.
Por isso, prefira display; ou mande os dois.
Ao contrário do que acontece nos eventos, aqui o
location é obrigatório. Um procedimento sem local é recusado.
As informações adicionais
Os itens de note[] voltam na leitura como você os enviou: três notas enviadas, três notas
lidas.
Do lado do Nilo Care, porém, elas viram um texto só, com quebras de linha entre os itens — é assim que a equipe as vê no campo Informações adicionais. A separação em itens existe no recurso, não na ficha.
Na tela, o rótulo do campo é Informações adicionais (uso interno da equipe de cuidado). O texto não é mostrado ao paciente.
Buscar
A resposta é sempre um Bundle do tipo searchset:
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.
A busca devolve mais do que cirurgias
GET /fhir/resources/Procedure não devolve só cirurgias. Uma conduta registrada num
atendimento cujo desfecho seja resultado de exame também é gravada como Procedure, e
aparece na mesma busca — inclusive num filtro por paciente.
Esses recursos são fáceis de reconhecer: eles não têm code, performer, location nem
performedPeriod, trazem um category SNOMED e o identificador deles está num system
próprio de conduta. Se a sua integração só trata cirurgias, filtre pela presença de
performedPeriod.
E há uma armadilha na escrita: se o identifier que você enviar casar com um desses recursos,
o POST falha com uma mensagem sobre não encontrar o identificador de cirurgia. Use chaves
suas, num system seu, e o problema não aparece.
Parâmetros de busca suportados
Prefira as formas :identifier. Um procedimento criado por integração guarda a referência
do paciente e a do profissional como você as mandou — só com identifier, sem o campo
reference. E é justamente em reference que patient=Patient/{id} e
performer=Practitioner/{id} procuram.
Essas duas formas só encontram os procedimentos originados no Nilo Care, ou os que já foram
editados por lá depois de criados por você. Para uma busca previsível, use
patient:identifier e performer:identifier.
Buscar por status não recorta por tempo. O valor gravado é o que você mandou — ou, nos
procedimentos vindos do Nilo Care, o que valia quando a equipe os editou. Ele não é
recalculado. Para recortar por tempo, use date.
Os demais parâmetros canônicos do Procedure existem e não encontram nada aqui, porque a
Nilo não preenche o campo correspondente: based-on, encounter, instantiates-canonical,
instantiates-uri, part-of, reason-code, reason-reference e subject:Group.
location é o caso curioso: o parâmetro canônico procura por referência, e o local
recomendado é texto em display — que não é encontrável. Se você mandou location.identifier,
aí sim location:identifier encontra o procedimento. Não há como buscar pelo nome do local.
E category encontra algo, mas não o que você espera — veja o aviso logo abaixo.
A paginação é por _count e _page_token; havendo página seguinte, o Bundle traz a URL
pronta em link.
Ler por ID
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 o procedimento está em
resource. Ler code ou subject na raiz da resposta não encontra nada.
Valores aceitos
code.coding[0].system
Dois, e só dois:
Qualquer outro system recusa a chamada. E o code precisa existir no catálogo da
plataforma naquela tabela: um código TUSS válido mas não cadastrado é recusado do mesmo
jeito.
O catálogo de procedimentos é único da plataforma, não do seu ambiente, e não é publicado por esta API. Se um código que você usa não é aceito, ele não consta desse catálogo — fale com o Suporte.
bodySite[0].coding[0].code
Três códigos SNOMED, e o campo guarda lateralidade, não sítio anatômico:
Qualquer outro código recusa a chamada — inclusive um código SNOMED de sítio anatômico legítimo. Não há como registrar onde no corpo o procedimento foi feito.
status
A plataforma só produz três: preparation, in-progress e completed. Mas o valor que você
manda é gravado como veio, qualquer que seja — e sem efeito. Veja
status não é conferido contra o período.
Efeitos colaterais
Registrar um procedimento não cria atendimento nem notifica o paciente. Ele entra apenas na linha de eventos da ficha.
Dois campos da ficha são preenchidos pela integração e não podem ser escolhidos por você: o procedimento entra sempre marcado como referido por outros, e com todas as atividades de diretriz habilitadas — a pergunta que o formulário do Nilo Care faz sobre quais atividades serão necessárias. Para mudar qualquer um dos dois, a equipe precisa editar o procedimento na tela.
Este endpoint nunca responde 204: não há remoção de procedimento por integração. Apagar uma
cirurgia é ação da equipe no Nilo Care — e, feita por lá, o id que você já leu passa a
responder 404.
Erros
Recusa é 400, e o corpo é um OperationOutcome.
As recusas vêm de dois lugares, e têm formas diferentes:
- Forma do payload — campo que o próprio FHIR exige (
status,subject), tipo inválido, valor fora do formato. Vem comcode: structuree o caminho do campo emexpression. - Regra de negócio — tudo o mais desta página. Vem com
code: exception, semexpression, e a única pista é a mensagem emdetails.text.
As mensagens da segunda lista são texto de erro de linguagem, em inglês, e não são
contrato. Não as interprete programaticamente: trate code: exception como “payload
recusado” e confira a lista de obrigatórios.
Os payloads completos estão na aba Referência, em POST /fhir/resources/Procedure.
429
Este recurso pode ter limite de escrita, conforme a configuração do ambiente. Havendo
limite e estourando-o, a chamada responde 429 com code: throttled, e a mensagem informa
quantos segundos esperar. Repita depois desse tempo — nada foi gravado.