Arquivos do paciente
Contexto NiloCare
Esse endpoint permite aos clientes Nilo Saúde enviar arquivos (documentos em PDF) e associá-los a um paciente da plataforma NiloCare, é uma alternativa à interface de usuário para integração e automatização. Os arquivos enviados ficam disponíveis na ficha do paciente.
A consulta retorna tanto os arquivos enviados por integração quanto os arquivos criados dentro do próprio NiloCare.
O caminho para acessar os arquivos no NiloCare é: Pacientes > [Nome do paciente] > Arquivos.
Mapeamento de Campos
Recurso FHIR: Media
| # | Campo | Expressão de caminho no objeto FHIR | |||||
|---|---|---|---|---|---|---|---|
| 1 | Identificador do arquivo | identifier | |||||
| 2 | Paciente | subject.identifier | |||||
| 3 | Nome do arquivo (somente no envio em base64) | content.title | |||||
| 4 | Arquivo (por URL) | content.url | |||||
| 5 | Arquivo (conteúdo em base64) | content.data | |||||
Apenas identifier, subject e content são utilizados. O identifier é obrigatório e usado
como chave de deduplicação (ver abaixo).
Os campos content.contentType e content.size não são armazenados: servem apenas para validar o
envio em base64 (ver Formato e limites) e não são devolvidos na consulta.
O status é obrigatório pela especificação FHIR, porém é ignorado na escrita — o NiloCare não
armazena o status do arquivo. Envie completed, que é o valor que a consulta sempre retorna.
Os demais atributos do recurso FHIR Media (type, encounter, createdDateTime, operator,
device, note, etc.) não são armazenados nem afetam o sistema e por isso não constam do schema
— omita-os do payload.
Especificações de comportamento FHIR - NiloCare
Identificação e ausência de atualização
O campo identifier é obrigatório e deve ser novo e único a cada
arquivo enviado.
Diferente dos outros recursos, Media não suporta atualização: se algum dos identifier enviados
já corresponder a um arquivo existente, a requisição é rejeitada em vez de atualizar o registro. Como
a API expõe apenas GET e POST, também não é possível apagar um arquivo por integração — pela API,
só criar e consultar.
Os cenários de erro correspondentes estão documentados em Cadastrar.
Paciente (subject)
O campo subject é obrigatório, e o subject.identifier também: a resolução do paciente usa
sempre o identificador, e o reference literal é ignorado. Enviar apenas o reference resulta em
erro (ver Cadastrar). Informe também o subject.type como Patient — quando
ausente, o NiloCare assume esse valor.
O paciente é resolvido antes de qualquer processamento do arquivo, para não baixar nem armazenar conteúdo de um paciente inexistente.
Envio do arquivo: URL ou base64
Existem duas formas de enviar o arquivo, e content.url tem precedência: se os dois campos forem
enviados, o content.data é ignorado.
A escolha do fluxo determina o nome do arquivo: o content.title só é preservado no envio em
base64. No envio por URL o nome é definido pelo NiloCare a partir do paciente, e o content.title
enviado é descartado.
content.url | content.data | |
|---|---|---|
| Como funciona | O NiloCare baixa o arquivo da URL informada | O conteúdo em base64 é enviado na própria requisição |
| Nome do arquivo | Definido pelo NiloCare — content.title não é preservado | Derivado de content.title |
content.contentType | Não validado | Obrigatório e deve ser application/pdf |
| Limite de tamanho | — | 10 MiB (10485760 bytes) após a decodificação |
Formato e limites
Somente arquivos application/pdf são aceitos no envio. No fluxo via content.data, além do
content.contentType, o próprio conteúdo é verificado pelos bytes iniciais do arquivo (%PDF-), de
forma que um conteúdo que não seja realmente um PDF é rejeitado mesmo com o contentType correto.
O limite é de 10485760 bytes (10 MiB) do conteúdo decodificado. O campo content.size é opcional,
mas se informado deve corresponder exatamente ao tamanho do conteúdo enviado. O content.hash é
aceito, porém não é validado.
Essa restrição vale apenas para a escrita: a consulta pode retornar arquivos de outros formatos (ver abaixo).
Consulta e sincronização
Arquivos criados dentro do NiloCare também são sincronizados e aparecem como Media na consulta.
Arquivos que não estejam associados a um paciente não são expostos.
Como a consulta devolve todos os arquivos do paciente, ela não se limita a PDFs: anexos recebidos
por outros canais (imagens, áudios e vídeos trocados no chat, por exemplo) também são retornados como
Media. O content.contentType não é preenchido na resposta, portanto não assuma que todo Media
retornado é um PDF — se a sua integração só trata documentos, filtre pela extensão do
content.title.
Excluir um arquivo no NiloCare também o remove da consulta: o recurso Media correspondente deixa de
existir.
Na consulta, o NiloCare acrescenta um identifier próprio (system
.../fhir/resources/NamingSystem/care-api--file-storage, cujo value é o identificador interno do
arquivo). O identifier enviado na criação é preservado ao lado dele, de modo que um arquivo enviado
por integração retorna com os dois — e pode ser consultado por qualquer um deles.
Arquivos criados dentro do NiloCare, por não terem origem em uma integração, retornam apenas com o
identifier do NiloCare.