# API de dados longitudinais do paciente

> O histórico de um paciente ao longo do tempo, proveniente de clínicas, laboratórios, aplicações e dispositivos: o que um registo longitudinal necessita e quatro formas de o ler — linha cronológica, $everything, IPS e contexto de IA.

Source: https://developers.anpheros.com/pt/guides/longitudinal-patient-data-api

**Uma API de dados longitudinais do paciente devolve o histórico de saúde de uma pessoa ao longo do tempo — diagnósticos, medicamentos, resultados de laboratório, sinais vitais, vacinações e consultas de todas as fontes — como um único registo ordenado, em vez de documentos separados por prestador de cuidados.** A Anpheros mantém esse histórico como um único registo HL7 FHIR R4 por paciente, escrito por clínicas, laboratórios, aplicações e dispositivos, mantendo todas as versões e todos os autores. Os programadores leem-no de quatro formas: uma linha cronológica cronológica, o registo FHIR completo com `Patient/$everything`, um Resumo Internacional do Paciente (IPS) ou um contexto compacto para modelos de IA.

<!-- visual:longitudinal-sources -->

## O que "longitudinal" requer

Uma lista de resultados não é ainda um registo longitudinal. Para que uma aplicação confie num histórico que abrange anos e fornecedores, cada entrada tem de conter:

| Requisito | Porquê é importante | Como o Anpheros o armazena |
|---|---|---|
| Um significado codificado | Valores de diferentes laboratórios devem ser comparáveis | LOINC para resultados, ICD-10 para condições, ATC para medicamentos |
| Uma data clínica | Ordenação por quando aconteceu, não quando foi carregado | Datas `effective`, `onset`, `occurrence` em cada recurso |
| O autor | O diagnóstico de um médico e uma nota de um paciente não são iguais | Proveniência em cada escrita: tipo de autor, pessoa, organização, sistema de origem |
| Cada versão | Correções não devem apagar o que era conhecido anteriormente | Histórico de versões em cada recurso (`_history`) |
| Consentimento | Outras aplicações veem o histórico apenas se a pessoa concordar | Concessões OAuth com âmbitos (scopes), expiração e um registo de acesso |

## Um registo, múltiplos escritores

<!-- visual:longitudinal-timeline -->

## Quatro formas de ler o histórico

| Necessidade | Endpoint | O que obtém |
|---|---|---|
| Um feed cronológico para um ecrã | `GET /v1/patients/{id}/timeline` | Itens de oito tipos (observation, condition, medication, document, encounter, appointment, immunization, episode) com data, título, resumo e a referência FHIR; filtrar com `from`, `to`, `types` |
| O registo completo como FHIR | `GET /fhir/R4/Patient/{id}/$everything` | Um Bundle searchset; `_since`, `_type`, `_count` e `_offset` são suportados |
| Um resumo clínico partilhável | `GET /fhir/R4/Patient/{id}/$summary` | Um documento International Patient Summary (IPS) |
| Entrada para um modelo de IA | `POST /v1/context` | Secções dentro de um orçamento de tokens, cada facto rotulado com a sua origem |

A linha temporal com o SDK TypeScript:

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });   // a sandbox key, sk_test_…
const { data: patients } = await anpheros.patients.list();
const page = await anpheros.timeline.list(patients[0].id, {
  from: '2025-01-01',
  types: 'condition,medication,observation',
  limit: 50,
});
for (const item of page.data) console.log(item.date, item.type, item.title);
```

E o mesmo registo como FHIR, limitado ao que mudou desde uma data:

```bash
curl -H "Authorization: Bearer $ANPHEROS_KEY" \
  "https://platform.anpheros.com/fhir/R4/Patient/$PATIENT/\$everything?_since=2026-01-01&_type=Observation,Condition"
```

## Manter a sua cópia sincronizada

Se a sua aplicação mantiver a sua própria vista do histórico, subscreva os webhooks `resource.created`, `resource.updated` e `resource.deleted`. Estes também são acionados quando outro projeto escreve num registo ao qual tem acesso, com `data.external: true` e o autor em `data.source`, para que dados de outras clínicas cheguem até si sem necessidade de polling.

## Limites a ter em conta

- O registo contém o que foi escrito nele. A Anpheros não recupera o histórico de hospitais ou redes nacionais por si só; clínicas, laboratórios, aplicações e a pessoa escrevem-no.
- São armazenados 26 tipos de recursos FHIR R4. Recursos de faturação como Claim e ExplanationOfBenefit não são.
- Outras aplicações leem o histórico de uma pessoa apenas com o consentimento dessa pessoa; a chave própria de um projeto vê os pacientes que criou.

## Perguntas Frequentes

### O que são dados longitudinais do paciente?
Informações de saúde de uma pessoa recolhidas ao longo do tempo e em vários locais de cuidados — diagnósticos, medicamentos, resultados, sinais vitais, vacinações e consultas — mantidas de forma a poderem ser lidas como um histórico contínuo.

### Qual API fornece uma vista cronológica do registo de um paciente?
No Anpheros, `GET /v1/patients/{id}/timeline` devolve entradas de oito tipos de recursos por ordem de data, com paginação e filtros de data e tipo. Para os dados FHIR completos, utilize `Patient/$everything`.

### O histórico é armazenado num formato standard?
Sim. Cada entrada é um recurso HL7 FHIR R4 com códigos standard (LOINC, ICD-10, ATC, CVX, UCUM), e o resumo é um International Patient Summary.

### Como sei quem escreveu cada entrada?
Cada escrita cria um recurso Provenance com o tipo de autor (paciente, profissional de saúde, dispositivo, importação ou IA), a pessoa, a organização e o sistema de origem.

### Posso testar com dados longitudinais realistas?
Sim. Cada projeto sandbox começa com 30 pacientes sintéticos com cerca de seis meses de condições, medicamentos, resultados de laboratório e sinais vitais.

<!-- visual:cta-longitudinal -->

## Relacionado

- [Aplicação de registo de saúde pessoal (PHR) com FHIR](https://developers.anpheros.com/pt/guides/personal-health-record-app): uma linha cronológica numa aplicação real
- [Proveniência de dados médicos explicada](https://developers.anpheros.com/pt/guides/medical-data-provenance)
- [Plataforma de consentimento do paciente para aplicações de saúde](https://developers.anpheros.com/pt/guides/patient-consent-platform)
- [Como armazenar registos médicos usando FHIR R4](https://developers.anpheros.com/pt/guides/store-medical-records-fhir)
- [Agentes de IA e dados médicos](https://developers.anpheros.com/pt/guides/ai-agents-medical-data): o endpoint de contexto
- [Webhooks](https://developers.anpheros.com/pt/guides/webhooks)