# Aplicação de registo de saúde pessoal (PHR) com FHIR

> Tutorial: o backend de um PHR conectado em FHIR R4 — dados de pessoas, laboratórios, documentos e dispositivos, uma linha temporal, um IPS para partilhar, consentimento. Código testado.

Source: https://developers.anpheros.com/pt/guides/personal-health-record-app

**Uma aplicação de registo de saúde pessoal (PHR) mantém a informação de saúde de uma pessoa — resultados, medições, diagnósticos, medicamentos, documentos — num registo que a pessoa controla, recolhida de várias fontes em vez de um único hospital.** As partes difíceis não são os ecrãs: são obter dados de laboratórios, clínicas e dispositivos numa forma utilizável, manter o controlo de onde cada item veio e permitir que a pessoa partilhe o registo sem perder o controlo sobre ele. Este tutorial constrói o backend de um PHR em HL7 FHIR R4 com o SDK TypeScript Anpheros; o código abaixo foi executado contra uma instância local da plataforma com uma chave de sandbox.

## PHR (Registos de Saúde Pessoais) Ligados, Desligados e Conectados

| Tipo | Onde os dados residem | Limitação |
|---|---|---|
| Ligado (portal do paciente de um hospital) | O EHR do prestador | Mostra apenas os dados desse prestador; muda quando a pessoa muda de médico |
| Desligado (aplicação autónoma ou caderno) | A base de dados da própria aplicação | A pessoa digita tudo; os dados raramente saem da aplicação |
| Conectado | Um registo padrão que aplicações, laboratórios e clínicas leem e escrevem com o consentimento da pessoa | Requer padrões, consentimento e proveniência subjacentes |

Um PHR Conectado é o que vale a pena construir hoje. É também para onde a política se está a mover: nos Estados Unidos, os EHRs certificados devem oferecer aos pacientes acesso via API baseado em FHIR aos seus dados (US Core), e na União Europeia o Espaço Europeu de Dados de Saúde confere às pessoas o direito de aceder aos seus dados de saúde eletrónicos e de os partilhar com prestadores à sua escolha, implementado gradualmente a partir de 2029.

## De onde vêm os dados de um PHR

1. **A pessoa:** medições caseiras, sintomas, medicamentos que toma, condições de que tem conhecimento. Marque-os como reportados pelo paciente.
2. **Relatórios de laboratório:** a maioria das pessoas recebe PDFs; alguns laboratórios podem enviar HL7 v2 ou CSV. Cada resultado deve tornar-se uma Observação codificada ([API de resultados de laboratório](https://developers.anpheros.com/pt/guides/lab-results-api)).
3. **Documentos:** cartas de alta, relatórios de imagem, prescrições. Mantenha o ficheiro original, inalterado, ao lado dos dados estruturados.
4. **Dispositivos e wearables:** passos diários, frequência cardíaca, sono, pressão arterial do Apple Health ou Health Connect ([dados de wearables em FHIR](https://developers.anpheros.com/pt/guides/wearable-data-fhir)).
5. **Prestadores de cuidados:** nos EUA, APIs FHIR de acesso ao paciente de hospitais e seguradoras, acedidas com SMART on FHIR; noutros locais, maioritariamente documentos e resumos como o International Patient Summary.

Cada fonte escreve no mesmo registo. O que o mantém fiável é que cada item regista quem o escreveu e de que sistema ([proveniência de dados médicos](https://developers.anpheros.com/pt/guides/medical-data-provenance)).

## A arquitetura

```
 person ──► your PHR app (mobile / web) ──► your backend ──► Anpheros: one FHIR R4 record per person
                                               │                 ├─ Observations, Conditions, Medications, Documents…
   lab report, PDF, device data ───────────────┘                 ├─ Provenance on every write
                                                                 ├─ access log the person can see
   other apps, doctors, AI assistants ◄── consent (OAuth) ───────┴─ $summary (IPS) to share
```

O seu backend detém a chave do projeto (`sk_test_…` na sandbox, nunca na aplicação). A sua aplicação autentica utilizadores com a sua própria autenticação e comunica com o seu backend; o backend mapeia cada utilizador para um registo de paciente.

## Passo a passo

Instale o SDK (`npm install @anpheros/sdk`) e obtenha uma chave de sandbox gratuita no [painel](https://platform.anpheros.com/dashboard/). O exemplo utiliza um painel de lípidos HL7 v2 com dois resultados (`lipid-panel.hl7`) e qualquer PDF (`report.pdf`).

```ts
import { readFile } from 'node:fs/promises';
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });

// 1. One record per person who signs up in your PHR app
const jane = await anpheros.patients.create({ given: 'Jane', family: 'Doe', birth_date: '1984-07-19', gender: 'female' });

// 2. Something the person measured at home
await anpheros.observations.create(jane.id, {
  code: '85354-9', category: 'vital-signs', effective_at: '2026-10-01T08:30:00-05:00', author_type: 'patient',
  components: [{ code: '8480-6', value: 128, unit: 'mm[Hg]' }, { code: '8462-4', value: 82, unit: 'mm[Hg]' }],
});

// 3. A diagnosis and a medication the person reports
await anpheros.conditions.create(jane.id, { code: 'E11.9', system: 'http://hl7.org/fhir/sid/icd-10',
  display: 'Type 2 diabetes mellitus without complications', clinical_status: 'active', onset: '2021-03-15', author_type: 'patient' });
await anpheros.medications.create(jane.id, { code: 'A10BA02', display: 'Metformin 500 mg', status: 'active',
  dosage: '500 mg twice a day', start: '2021-03-20', author_type: 'patient' });

// 4. A lab report the person received, as the lab sent it (HL7 v2)
const lab = await anpheros.labs.importHl7(jane.id, await readFile('lipid-panel.hl7', 'utf8'), { sourceSystem: 'springfield-lis' });

// 5. A PDF they want to keep with the record
const doc = await anpheros.documents.upload(jane.id,
  { title: 'Chest X-ray report', kind: 'imaging_report', content_type: 'application/pdf', date: '2026-10-03' },
  await readFile('report.pdf'));

// 6. One timeline for the home screen
const timeline = await anpheros.timeline.list(jane.id, { limit: 10 });

// 7. A summary to share with a new doctor: the International Patient Summary
const ips = await anpheros.fhir.summary(jane.id);

// 8. Who else can read this record (empty until the person consents to another app)
const grants = await anpheros.grants.of(jane.id);
```

Impresso desse registo:

```
lab:       created 2, unmapped []
document:  final
timeline:  2026-10-03  document    Chest X-ray report
           2026-10-02  observation Cholesterol in HDL [Mass/volume] in Serum or Plasma
           2026-10-02  observation Cholesterol [Mass/volume] in Serum or Plasma
           2026-10-01  observation Blood pressure panel
           2021-03-20  medication  Metformin 500 mg
           2021-03-15  condition   Type 2 diabetes mellitus without complications
IPS:       Allergies, Medications, Problems, Results, Vital signs
grants:    0
```

Tudo o que está acima é armazenado como FHIR R4 — Patient, Observation, Condition, MedicationStatement, DocumentReference — para que o mesmo registo possa ser lido com qualquer cliente FHIR (`GET /fhir/R4/Patient/{id}/$everything`) e movido para outro local intacto. As chamadas `/v1` no SDK são uma vista mais simples dos mesmos recursos; a [API de dados médicos](https://developers.anpheros.com/pt/guides/medical-data-api) lista-as.

## Partilha sem perder o controlo

Um PHR existe para ser partilhado, nos termos da pessoa:

- **Com um médico:** o International Patient Summary (`$summary`) é um documento FHIR feito para clínicos — problemas, medicamentos, alergias, resultados — que a sua aplicação pode mostrar, imprimir ou enviar. [FHIR platform](https://developers.anpheros.com/pt/guides/fhir) descreve `$summary` e `$everything`.
- **Com outra aplicação:** a outra aplicação pede consentimento através de OAuth 2.1 e SMART on FHIR; a pessoa escolhe quais os dados (por exemplo, apenas resultados de laboratório) e por quanto tempo, podendo revogá-lo a qualquer momento. [How to implement patient consent with SMART on FHIR](https://developers.anpheros.com/pt/guides/smart-on-fhir-backend) explica o processo.
- **Com um assistente de IA:** `POST /v1/context` constrói um resumo orçamentado e com rótulo de origem do registo para um modelo, e a leitura aparece no registo de acesso ([How to build an AI healthcare app](https://developers.anpheros.com/pt/guides/build-ai-healthcare-app)).
- **Transparência:** cada leitura e escrita, por qualquer aplicação, é registada por aplicação, e a pessoa pode ver o registo e as autorizações ativas.

## Famílias

Muitos PHR são mantidos por uma pessoa para vários indivíduos: filhos, um parceiro, um pai idoso. Dê a cada pessoa o seu próprio registo e ligue-os ao tutor, em vez de misturar os dados de todos num só. O consentimento é então dado por registo. [Registo médico do paciente](https://developers.anpheros.com/pt/guides/patient-medical-record) descreve o modelo.

## O que construir você mesmo e o que não construir

Você constrói a experiência: o onboarding, como os resultados são explicados, lembretes, gráficos, a linguagem que a pessoa lê. A Anpheros fornece o registo, os formatos padrão, o consentimento, a proveniência, o registo de acesso e as operações de laboratório, documento e resumo.

O que a Anpheros não faz hoje para um PHR: não faz login em portais de pacientes de hospitais ou APIs de acesso a pacientes dos EUA em nome da pessoa (a sua aplicação pode fazer isso com um cliente SMART on FHIR e escrever o que recebe), não lê relatórios em PDF através da API, e não dá conselhos médicos. A própria aplicação PHR da Anpheros, **Anpheros Daily**, é construída sobre esta mesma API.

## Perguntas frequentes

### O que é um registo de saúde pessoal (PHR)?
Um registo de informações de saúde de uma pessoa que a pessoa mantém e controla, recolhido de várias fontes — as suas próprias entradas, laboratórios, clínicas, dispositivos — em vez de ser mantido por um único prestador.

### Qual é a diferença entre um PHR e um EHR?
Um EHR é mantido por uma organização de saúde e abrange o que os seus prestadores registaram. Um PHR é mantido pela pessoa e pode combinar dados de todos os seus prestadores e dispositivos. Um PHR "tethered" (ligado) é uma janela para o EHR de um prestador; um PHR conectado utiliza padrões para reunir várias fontes.

### Um PHR deve usar FHIR?
Se os dados forem alguma vez partilhados com um médico, outra aplicação ou um assistente de IA, sim: FHIR R4 fornece recursos codificados e versionados que outros sistemas já entendem, e é o formato das APIs de acesso do paciente nos EUA e do resumo do paciente europeu.

### Como é que uma aplicação PHR obtém dados de hospitais?
Nos EUA, através das APIs de acesso do paciente FHIR que os EHRs certificados e muitos seguradores expõem, utilizando SMART on FHIR para permitir que a pessoa autorize a aplicação. Noutros locais, são principalmente documentos e resumos, importados e armazenados ao lado de dados estruturados.

### Onde é que uma aplicação PHR deve guardar as chaves da API?
No seu servidor. Uma chave de projeto pode ler todos os registos que o seu projeto criou, pelo que nunca deve ser enviada dentro de uma aplicação móvel ou web; a aplicação comunica com o seu backend, e as aplicações de outras pessoas utilizam OAuth com o consentimento da pessoa.

## Relacionado

- [Criar uma aplicação de saúde](https://developers.anpheros.com/pt/guides/build-a-healthcare-app): o guia geral
- [Registo médico do paciente](https://developers.anpheros.com/pt/guides/patient-medical-record): o que o registo contém e quem pode aceder a ele
- [Infraestrutura de registo médico digital](https://developers.anpheros.com/pt/guides/digital-medical-record)
- [Dados de wearables em FHIR](https://developers.anpheros.com/pt/guides/wearable-data-fhir): Apple Health, Health Connect e Samsung Health
- [API de resultados laboratoriais](https://developers.anpheros.com/pt/guides/lab-results-api)
- [SDKs](https://developers.anpheros.com/pt/guides/sdks)