# Proveniência de dados médicos explicada

> O que os registos de proveniência em cada escrita num registo FHIR R4 — tipo de autor, pessoa, organização, sistema de origem, versões — como defini-los com cabeçalhos, como lê-los e como eles rotulam dados fornecidos a modelos de IA.

Source: https://developers.anpheros.com/pt/guides/medical-data-provenance

**Proveniência é o registo de onde veio um dado médico: quem o escreveu, em nome de que organização, de que sistema, quando e o que mudou em cada versão.** Num registo que recolhe dados de pacientes, dispositivos, clínicas, laboratórios e IA, a proveniência é o que torna um valor confiável: uma leitura de pressão arterial digitada em casa e uma medida numa clínica parecem idênticas sem ela. No Anpheros, cada escrita num registo HL7 FHIR R4 produz automaticamente um recurso FHIR `Provenance`. Esta página explica o que ele contém, como preenchê-lo corretamente e como lê-lo.

## Porquê a proveniência é importante

- **Confiança clínica.** Um médico pondera um resultado de laboratório de forma diferente de um valor introduzido pelo paciente ou de um número que uma IA extraiu de uma fotografia.
- **Segurança da IA.** Um modelo que recebe um registo tem de saber quais os itens que são factos e quais são notas escritas por outro modelo. Sem rótulos, trata-os da mesma forma.
- **Correções e litígios.** Quando um valor muda, todos precisam de saber qual era anteriormente, quem o alterou e porquê.
- **Responsabilização.** Ao abrigo do RGPD e do Espaço Europeu de Dados de Saúde, uma organização deve ser capaz de demonstrar o que fez com os dados de saúde de uma pessoa.
- **Partilha.** Quando um paciente permite que uma segunda clínica leia o seu registo, essa clínica precisa de saber quais os dados que a primeira clínica escreveu.

## O que o Anpheros regista em cada escrita

| Questão | Onde é registado | Como definir |
|---|---|---|
| Que tipo de autor? | `agent.who.identifier` (tipo de autor) | `author_type` em `/v1`, ou cabeçalho `X-Anpheros-Author-Type`: `patient`, `practitioner`, `device`, `import`, `ai` |
| Qual pessoa? | `agent.who.reference` | `X-Anpheros-Author-Ref: Practitioner/<id>`, ou `X-Anpheros-Acting-As` |
| Para qual organização? | `agent.onBehalfOf` | a organização do `PractitionerRole`, ou `X-Anpheros-On-Behalf-Of: Organization/<id>` |
| De que sistema? | `entity` com função `source` | `X-Anpheros-Source-System: <name>` |
| Qual registo nesse sistema? | id de origem | `X-Anpheros-Origin-Id: <id>` |
| Quando, e o que aconteceu? | `recorded`, `activity` (CREATE, UPDATE, DELETE) | automático |
| Qual versão? | `target` aponta para `<Resource>/<id>/_history/<version>` | automático |

Se não indicar quem é o autor, a plataforma regista `import`. Nunca assume `patient`, pois um valor atribuído indevidamente ao paciente é pior do que um rotulado honestamente como importado.

## Uma escrita com proveniência completa

Um cardiologista numa clínica regista uma frequência cardíaca durante uma consulta, através do software da clínica:

```bash
curl -X POST https://platform.anpheros.com/fhir/R4/Observation -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/fhir+json" \
     -H "X-Anpheros-Author-Type: practitioner" \
     -H "X-Anpheros-Acting-As: PractitionerRole/$ROLE" \
     -H "X-Anpheros-Source-System: ccn-emr" \
     -d '{ "resourceType": "Observation", "status": "final", "code": {"coding": [{"system": "http://loinc.org", "code": "8867-4"}]}, … }'
```

A Provenance que a plataforma escreve:

```json
{"resourceType": "Provenance",
 "target": [{"reference": "Observation/8660eb7c-…/_history/1"}],
 "recorded": "2026-10-12T20:41:47.469000Z",
 "activity": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation", "code": "CREATE"}]},
 "agent": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type", "code": "author"}]},
            "who": {"reference": "PractitionerRole/e6d8c227-…",
                    "identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "practitioner"}},
            "onBehalfOf": {"reference": "Organization/c3a56a4b-…", "display": "Clinica Cardio Nord"}}],
 "entity": [{"role": "source", "what": {"identifier": {"system": "ccn-emr"}}}]}
```

O papel do médico, a sua clínica, o tipo de autor e o sistema de origem estão todos lá, em FHIR padrão. O `PractitionerRole` deve existir no diretório do seu projeto e estar ativo. Uma solicitação que nomeie o praticante de outra pessoa é recusada:

```json
{"resourceType": "OperationOutcome", "issue": [{"severity": "error", "code": "invalid",
  "diagnostics": "Unknown or inactive Practitioner in X-Anpheros-Acting-As."}]}
```

A configuração do diretório é abordada em [Como integrar sistemas de clínica com um backend FHIR](https://developers.anpheros.com/pt/guides/integrate-clinic-systems-fhir).

## Versões: nada é substituído silenciosamente

Cada atualização cria uma nova versão do recurso e uma nova Proveniência para ele. Após a frequência cardíaca acima ser corrigida de 92 para 88:

```bash
curl https://platform.anpheros.com/fhir/R4/Observation/$OBS/_history -H "Authorization: Bearer $KEY"
```

retorna a versão 2 (88) e a versão 1 (92). A vista REST resume a Proveniência de cada versão:

```bash
curl https://platform.anpheros.com/v1/patients/$PID/provenance/Observation/$OBS -H "Authorization: Bearer $KEY"
```

```json
{"data": [
  {"version": 1, "activity": "CREATE", "recorded": "2026-10-12T20:41:47.469000Z", "author_type": "practitioner", "author": "PractitionerRole/e6d8c227-…", "source_system": "ccn-emr", "fhir": "Provenance/6ed91529-…"},
  {"version": 2, "activity": "UPDATE", "recorded": "2026-10-12T20:41:47.500000Z", "author_type": "practitioner", "fhir": "Provenance/3fbf270f-…"}],
 "total": 2}
```

As eliminações são "soft": um recurso eliminado desaparece das pesquisas, mas o seu histórico e Proveniência permanecem.

## Leitura da proveniência

```bash
# who wrote this resource (all versions)
GET /fhir/R4/Provenance?target=Observation/{id}
# everything a practitioner recorded
GET /fhir/R4/Provenance?agent=PractitionerRole/{id}
# the same, summarised, per resource
GET /v1/patients/{pid}/provenance/Observation/{id}
```

## Proveniência em contextos de IA

A [API de contexto](https://developers.anpheros.com/pt/guides/llm-healthcare-data) transporta a proveniência para cada item que fornece a um modelo, como `author_type` e `source`. Em formato de texto:

```
- Type 2 diabetes mellitus (E11), active, onset 2024-10-15 [import/anpheros-sandbox]
- Metformin 1000 mg 1 tablet twice daily with meals, active [patient/anpheros-sandbox]
- Glucose [Mass/volume] in Blood: 2026-09-16: 140.0 mg/dL [device/anpheros-sandbox]
```

As medições escritas com `author_type: ai` nunca aparecem entre estes factos. São listadas separadamente em `ai_notes` e marcadas como não verificadas, para que um modelo não possa confundir uma suposição de um modelo anterior com uma medição. Indique ao modelo o que os rótulos significam e peça-lhe para os citar; [Como criar uma aplicação de saúde com IA com um backend FHIR](https://developers.anpheros.com/pt/guides/build-ai-healthcare-app) mostra um prompt que o faz.

## O que o paciente vê

A proveniência é também o que o paciente vê. O seu registo mostra quem adicionou cada item, e a lista de conexões mostra, para cada aplicação, quem acedeu a quê, pelo nome quando um profissional de saúde estava a atuar ("Dr. Ana Popescu · Clínica Cardio Nord leu os seus resultados de exames"). Ver [Modelo de consentimento e acesso](https://developers.anpheros.com/pt/guides/consent).

## Regras que tornam a proveniência útil

1. **Defina sempre o tipo de autor.** Custa um campo e é o rótulo mais importante no registo.
2. **Nomeie a pessoa quando uma pessoa a escreveu.** Use `X-Anpheros-Acting-As` para pessoal clínico.
3. **Nomeie o sistema de origem**, e passe o ID próprio da origem como ID de origem quando existir um.
4. **Corrija atualizando, nunca eliminando e recriando.** Uma atualização mantém a ligação entre o valor antigo e o novo.
5. **Rotule a saída de IA como `ai`**, incluindo valores que um modelo extraiu de um documento. Valores derivados de um documento também podem apontar de volta para ele com `derived_from`.

## Perguntas Frequentes

### O que é a proveniência de dados em saúde?
A origem e o histórico documentados de um dado de saúde: quem o criou ou alterou, em nome de quem, a partir de que sistema e quando. Em HL7 FHIR, é representado pelo recurso `Provenance`, que aponta para a versão exata do recurso que descreve.

### A proveniência é o mesmo que um registo de auditoria?
Não. A proveniência descreve os dados: quem escreveu cada versão. Um registo de auditoria descreve o acesso: quem leu ou escreveu o quê, quando, sob qual consentimento. O Anpheros mantém ambos; o paciente vê o registo de acesso de cada aplicação ligada ao seu registo.

### Posso escrever os meus próprios recursos de Proveniência?
O Anpheros escreve um para cada criação, atualização e eliminação, pelo que normalmente não o fará. Utilize os cabeçalhos acima para o tornar preciso. Uma Proveniência fornecida pelo cliente deve ter como alvo recursos de um único paciente.

## Relacionado

- [Modelo de consentimento e acesso](https://developers.anpheros.com/pt/guides/consent)
- [Como integrar sistemas de clínica com um backend FHIR](https://developers.anpheros.com/pt/guides/integrate-clinic-systems-fhir)
- [Como normalizar dados médicos](https://developers.anpheros.com/pt/guides/normalize-medical-data)
- [Interoperabilidade de dados de saúde](https://developers.anpheros.com/pt/guides/interoperability)
- [Segurança, privacidade e residência de dados](https://developers.anpheros.com/pt/guides/security)