Escritas
Não existe endpoint separado para criar e para atualizar. Todo envio é um POST no tipo do
recurso, e o que decide entre criar e atualizar é o identificador.
Upsert por identificador
Todo recurso carrega um ou mais identifier, cada um com system (o namespace, uma URI que
identifica o seu sistema) e value (a chave daquele registro no seu sistema):
Se já existir um recurso com aquele identificador, ele é atualizado. Se não existir, é criado. Reenviar o mesmo payload duas vezes não gera duplicata — é o que torna a integração segura para reprocessamento.
Mantenha o system estável ao longo do tempo. Trocar o system de um paciente já integrado
faz a Nilo tratá-lo como um paciente novo, e o histórico fica partido em dois registros.
O que a API devolve
A escrita é síncrona: o processamento já terminou quando a resposta chega, e o corpo da resposta é o recurso gravado.
A validação acontece antes da gravação. Um payload que não passa na validação FHIR é recusado sem criar nada.
Várias escritas de uma vez
Para agrupar várias escritas numa requisição só — inclusive criando um recurso e outro que o referencia no mesmo envio —, veja Carga em lote.
Para ser avisado quando um recurso mudar, em vez de consultar, veja Webhooks.
Versionamento
Toda escrita bem-sucedida gera um novo meta.versionId no recurso. As versões anteriores
continuam legíveis, o que permite auditar o que mudou e quando:
O versionId é opaco — a codificação em base64 do instante da gravação, em nanossegundos.
Não é sequencial: guarde o valor devolvido em cada escrita se quiser poder reler aquela
versão depois. Veja Histórico de versões.