# Como armazenar registos médicos usando FHIR R4

> Tutorial: crie um Paciente, uma Observação de pressão arterial e uma Condição, use uma transação, pesquise, atualize com histórico e leia a proveniência — cada pedido com curl e a resposta real, na sandbox gratuita.

Source: https://developers.anpheros.com/pt/guides/store-medical-records-fhir

Este tutorial armazena um pequeno registo médico como recursos HL7 FHIR R4: um `Patient`, uma `Observation` de pressão arterial e um diagnóstico como `Condition`, depois um paciente e uma medição juntos numa única transação. Pesquisa-os, atualiza o diagnóstico sem perder a versão anterior e lê quem escreveu o quê. Cada pedido é `curl` simples contra a sandbox gratuita Anpheros, e cada resposta apresentada é o que a API retorna.

Se é novo no FHIR, leia primeiro [Plataforma FHIR](https://developers.anpheros.com/pt/guides/fhir) para os conceitos. Esta página é a parte prática.

## Os três recursos com que a maioria dos registos começa

| Recurso | O que contém | Codificado com |
|---|---|---|
| `Patient` | de quem é o registo: nome, data de nascimento, género, identificadores de outros sistemas | os seus sistemas de identificação |
| `Observation` | tudo o que é medido ou reportado: sinais vitais, resultados de laboratório, um peso, uma pontuação de sintoma | LOINC, unidades UCUM |
| `Condition` | um diagnóstico ou um problema de saúde, com o seu estado ao longo do tempo | ICD-10 (SNOMED CT por trás de uma bandeira de licença) |

Medicamentos (`MedicationStatement`), alergias (`AllergyIntolerance`), imunizações e documentos seguem o mesmo padrão; os [26 tipos de recursos suportados](https://developers.anpheros.com/pt/guides/fhir) estão listados na declaração de capacidade em `/fhir/R4/metadata`.

## Antes de começar

Obtenha uma chave de sandbox (`sk_test_…`) em [platform.anpheros.com/dashboard](https://platform.anpheros.com/dashboard/) com **Get a sandbox key**. Nada do que criar lá são dados reais de pacientes, e nada é visível para outros projetos.

```bash
export BASE=https://platform.anpheros.com/fhir/R4
export KEY=sk_test_…
```

## Passo 1: Criar um Paciente

```bash
curl -X POST "$BASE/Patient" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" -d '{
  "resourceType": "Patient",
  "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-10442"}],
  "name": [{"family": "Marin", "given": ["Ioana"]}],
  "gender": "female",
  "birthDate": "1979-04-12"
}'
```

`201 Created`, com o id e a versão que o servidor atribuiu:

```json
{"resourceType": "Patient",
 "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-10442"}],
 "name": [{"family": "Marin", "given": ["Ioana"]}], "gender": "female", "birthDate": "1979-04-12",
 "id": "d09e3942-ed86-4458-b099-fa674ab21b84",
 "meta": {"versionId": "1", "lastUpdated": "2026-10-12T20:16:51.043Z"}}
```

Mantenha os seus próprios ids em `identifier` com um `system` que controla (aqui um número de registo da clínica), para que possa sempre encontrar o paciente novamente com `GET $BASE/Patient?identifier=https://clinic.example/mrn|MRN-10442`. O `id` FHIR é da plataforma e é específico para o seu projeto: outro projeto vê a mesma pessoa sob um id diferente.

```bash
export PID=d09e3942-ed86-4458-b099-fa674ab21b84
```

## Passo 2: Armazenar uma medição como uma Observação

A pressão arterial é uma observação com dois componentes, sistólica e diastólica, cada um com o seu próprio código LOINC. Indique quem a mediu: aqui, um dispositivo doméstico.

```bash
curl -X POST "$BASE/Observation" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
     -H "X-Anpheros-Author-Type: device" -H "Idempotency-Key: bp-2026-10-10-0830" -d '{
  "resourceType": "Observation",
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure panel"}]},
  "subject": {"reference": "Patient/'$PID'"},
  "effectiveDateTime": "2026-10-10T08:30:00Z",
  "component": [
    {"code": {"coding": [{"system": "http://loinc.org", "code": "8480-6"}]},
     "valueQuantity": {"value": 138, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]"}},
    {"code": {"coding": [{"system": "http://loinc.org", "code": "8462-4"}]},
     "valueQuantity": {"value": 88, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]"}}
  ]
}'
```

A resposta é o recurso armazenado com `id` e `meta.versionId: "1"`. Três detalhes são importantes para um registo utilizável:

- **Códigos, não rótulos.** `85354-9` significa "painel de pressão arterial" em todos os sistemas FHIR; um texto livre "BP" não significa. Procure códigos com `GET /v1/terminology/loinc?q=blood pressure` ([Sistemas de códigos FHIR](https://developers.anpheros.com/pt/guides/fhir-code-systems)).
- **Unidades UCUM** (`mm[Hg]`, `kg`, `mg/dL`) em `valueQuantity.code`, para que os valores possam ser comparados e convertidos.
- **`Idempotency-Key`.** Uma nova tentativa após um timeout devolve a primeira resposta em vez de armazenar a leitura duas vezes.

Os resultados de laboratório são o mesmo recurso com `category` `laboratory` e geralmente um `referenceRange`. Para importar relatórios laboratoriais completos, consulte [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir).

## Passo 3: registar um diagnóstico como Condição

```bash
curl -X POST "$BASE/Condition" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
     -H "X-Anpheros-Author-Type: practitioner" -d '{
  "resourceType": "Condition",
  "subject": {"reference": "Patient/'$PID'"},
  "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]},
  "verificationStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "confirmed"}]},
  "code": {"coding": [{"system": "http://hl7.org/fhir/sid/icd-10", "code": "I10", "display": "Essential (primary) hypertension"}]},
  "onsetDateTime": "2026-03-02"
}'
```

`clinicalStatus` (ativo, resolvido, em remissão) e `verificationStatus` (confirmado, provisório) são separados propositadamente: um diagnóstico suspeito não é o mesmo que um confirmado, e um problema resolvido continua a fazer parte do histórico.

## Passo 4: criar recursos relacionados numa única transação

Quando um paciente e a sua primeira medição chegam juntos, por exemplo, de um sistema de clínica, envie-os como um `transaction` Bundle. Ou tudo é armazenado ou nada é. As referências entre novos recursos utilizam `urn:uuid:` ids temporários que o servidor substitui:

```bash
curl -X POST "$BASE" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" -d '{
  "resourceType": "Bundle", "type": "transaction",
  "entry": [
    {"fullUrl": "urn:uuid:9f1c0d1e-0000-4000-8000-000000000001",
     "resource": {"resourceType": "Patient", "name": [{"family": "Stan", "given": ["Mihai"]}], "gender": "male", "birthDate": "1990-02-01"},
     "request": {"method": "POST", "url": "Patient"}},
    {"resource": {"resourceType": "Observation", "status": "final",
       "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
       "code": {"coding": [{"system": "http://loinc.org", "code": "29463-7", "display": "Body weight"}]},
       "subject": {"reference": "urn:uuid:9f1c0d1e-0000-4000-8000-000000000001"},
       "effectiveDateTime": "2026-10-10",
       "valueQuantity": {"value": 82.4, "unit": "kg", "system": "http://unitsofmeasure.org", "code": "kg"}},
     "request": {"method": "POST", "url": "Observation"}}
  ]
}'
```

O `transaction-response` tem uma entrada por recurso, com `"status": "201 Created"`, o seu `location` e o recurso armazenado. O `subject` da Observation aponta agora para o `Patient/fad3665a-…` real.

## Passo 5: pesquisa

```bash
curl "$BASE/Observation?patient=$PID&code=http://loinc.org|85354-9&date=ge2026-10-01&_sort=-date" \
     -H "Authorization: Bearer $KEY"
```

Recebe um `searchset` Bundle com `total` e os recursos correspondentes, os mais recentes primeiro. Outras pesquisas que irá utilizar frequentemente: `Condition?patient=$PID&clinical-status=active`, `Observation?patient=$PID&category=laboratory` e `Patient/$PID/$everything` para o registo completo.

## Passo 6: Atualizar sem perder histórico

A hipertensão resolve-se. Altere o estado e adicione a data de fim, e utilize `If-Match` com a versão que leu para nunca sobrescrever a alteração de outra pessoa:

```bash
curl -X PUT "$BASE/Condition/$CID" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
     -H 'If-Match: W/"1"' -d '{ …the same Condition…, "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "resolved"}]}, "abatementDateTime": "2026-10-11" }'
```

`200 OK` com `ETag: W/"2"`. Se outra escrita chegou primeiro, receberá `412` e terá de ler novamente. A versão anterior ainda estará lá:

```bash
curl "$BASE/Condition/$CID/_history" -H "Authorization: Bearer $KEY"
```

retorna ambas as versões: `versionId` 2 (`resolved`) e 1 (`active`). `GET $BASE/Condition/$CID/_history/1` lê a antiga. Nada num registo é sobrescrito silenciosamente.

## Passo 7: Ver quem escreveu o quê

Cada escrita cria um recurso `Provenance`. Para a leitura da pressão arterial:

```bash
curl "$BASE/Provenance?target=Observation/$OBS" -H "Authorization: Bearer $KEY"
```

```json
{"resourceType": "Provenance",
 "target": [{"reference": "Observation/d83d9075-…/_history/1"}],
 "recorded": "2026-10-12T20:16:51.056000Z",
 "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": {"identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "device"}, "display": "proj_…"},
            "onBehalfOf": {"identifier": {"system": "https://anpheros.com/fhir/sid/organization", "value": "org_…"}, "display": "…"}}]}
```

O tipo de autor que enviou (`device`) é registado com o projeto e a organização. Envie `X-Anpheros-Author-Ref: Practitioner/<id>` para nomear o clínico por trás de uma escrita.

## Passo 8: o registo como resumo

```bash
curl "$BASE/Patient/$PID/\$summary" -H "Authorization: Bearer $KEY"
```

devolve um International Patient Summary: um `document` Bundle que começa com um `Composition` e tem secções como Problemas, Medicamentos, Alergias e Sinais Vitais, construído a partir dos recursos acima. Esse é o formato a entregar a outro sistema ou a imprimir para um médico ([plataforma FHIR](https://developers.anpheros.com/pt/guides/fhir)).

## Prefere JSON sem FHIR?

Os mesmos dados estão disponíveis através de uma vista REST mais simples, `/v1`, com os mesmos IDs: `POST /v1/patients/{id}/observations` obtém `{"code": "85354-9", "category": "vital-signs", "effective_at": "…", "components": […]}` e armazena a mesma Observação FHIR. Utilize o que melhor se adequa ao seu código. Veja a [API de dados médicos](https://developers.anpheros.com/pt/guides/medical-data-api) e os [SDKs](https://developers.anpheros.com/pt/guides/sdks).

## Perguntas Frequentes

### Qual é a melhor forma de armazenar registos médicos?
Como recursos codificados, versionados e com um registo de quem escreveu cada um. O HL7 FHIR R4 fornece a estrutura (Patient, Observation, Condition e outros), sistemas de codificação padrão como LOINC e ICD-10, e histórico; um backend FHIR adiciona pesquisa, consentimento e proveniência por cima.

### Preciso de um servidor FHIR para usar FHIR?
Precisa de um local que armazene e pesquise recursos FHIR e que reforce quem pode lê-los. Pode executar o seu próprio servidor FHIR de código aberto ou usar um gerido como o Anpheros; [Como o Anpheros se compara com outros servidores FHIR](https://developers.anpheros.com/pt/guides/fhir-server-comparison) pondera as opções, e [FHIR vs. uma base de dados médica personalizada](https://developers.anpheros.com/pt/guides/fhir-vs-custom-database) aborda a criação do seu próprio esquema.

### Como armazeno a pressão arterial em FHIR?
Como uma `Observation` com o código LOINC `85354-9` e duas entradas `component`: sistólica `8480-6` e diastólica `8462-4`, cada uma com uma `valueQuantity` em `mm[Hg]`.

### Posso alterar um recurso armazenado?
Sim, com `PUT` e `If-Match`. Cada alteração cria uma nova versão; versões anteriores permanecem legíveis através de `_history`, e os registos de Proveniência indicam quem fez cada alteração. As eliminações são "soft" e mantêm o histórico.

## Relacionado

- [Plataforma FHIR](https://developers.anpheros.com/pt/guides/fhir): os conceitos, tipos de recursos e operações
- [Sistemas de código FHIR](https://developers.anpheros.com/pt/guides/fhir-code-systems): LOINC, ICD-10, ATC, UCUM
- [Como importar resultados de laboratório para um registo FHIR](https://developers.anpheros.com/pt/guides/import-lab-results-fhir)
- [API de dados médicos](https://developers.anpheros.com/pt/guides/medical-data-api): a vista REST mais simples dos mesmos dados
- [Base de dados e sandbox FHIR gratuitos](https://developers.anpheros.com/pt/guides/free-fhir-database)