# API de dados médicos

> Para onde vai cada tipo de dados médicos na API Anpheros, como é codificado e como escrevê-lo, filtrá-lo, rastreá-lo, corrigi-lo e eliminá-lo — com exemplos funcionais.

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

**Uma API de dados médicos fornece acesso estruturado de software ao conteúdo dos registos de pacientes: criar um paciente, registar uma leitura de pressão arterial, listar medicamentos ativos, anexar um relatório de laboratório, rastrear quem escreveu o quê.** Esta página descreve as operações de dados da API Anpheros — que tipo de dados médicos vai para onde, como é codificado e como lê-lo de volta — com exemplos que funcionam contra o sandbox.

As aplicações utilizam estas operações para tratar a Anpheros como a base de dados médica do seu produto: os registos de pacientes residem no armazenamento HL7 FHIR R4 da plataforma, e a aplicação lê-os e escreve-os através da API em vez de manter as suas próprias tabelas de dados médicos.

Para uma visão mais abrangente (autenticação, consentimento, eventos), consulte [API de Saúde](https://developers.anpheros.com/pt/guides/healthcare-api).

## Onde cada tipo de dado médico é armazenado

| Dado médico | REST v1 | Recurso FHIR | Codificação |
|---|---|---|---|
| A pessoa | `POST /v1/patients` | `Patient` | nome, data de nascimento, género, identificadores |
| Sinais vitais, resultados de laboratório, sintomas, atividade, inquéritos | `/v1/patients/{id}/observations` | `Observation` | LOINC (sintomas: capítulo R do ICD-10); unidades UCUM |
| Diagnósticos e problemas | `/v1/patients/{id}/conditions` | `Condition` | ICD-10 |
| Medicamentos | `/v1/patients/{id}/medications` | `MedicationStatement` | ATC, nome do produto mantido como texto |
| Documentos (PDF, imagens) | `/v1/patients/{id}/documents` | `DocumentReference` | Tipos de documento LOINC |
| Um relatório de laboratório completo | `POST /v1/patients/{id}/labs/import` | `Observation` (laboratory) | LOINC quando conhecido, o código próprio do laboratório caso contrário |
| Doses tomadas ou omitidas, vacinações, alergias, procedimentos, relatórios, planos de cuidados, objetivos, referências, consultas, agendamentos, equipas de cuidados, histórico familiar, questionários | `/fhir/R4/{type}` | `MedicationAdministration`, `Immunization`, `AllergyIntolerance`, `Procedure`, `DiagnosticReport`, `CarePlan`, `Goal`, `ServiceRequest`, `Encounter`, `Appointment`, `CareTeam`, `FamilyMemberHistory`, `QuestionnaireResponse` | por [sistemas de código FHIR](https://developers.anpheros.com/pt/guides/fhir-code-systems) |

Os objetos REST v1 e os recursos FHIR são os mesmos registos com os mesmos IDs; cada objeto v1 carrega a sua referência `fhir`.

## Escrever dados médicos

```bash
# a lab result with its reference range, linked to the report it came from
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
     -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "4548-4", "display": "Hemoglobin A1c", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-09-01T08:00:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "derived_from": ["DocumentReference/'$DOC'"], "author_type": "import"
}'
```

- **Categorias de observação:** `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`.
- **Medições compostas**, como a pressão arterial, utilizam `components` (sistólica `8480-6`, diastólica `8462-4` dentro do painel `85354-9`).
- **Tipos de autor:** `patient`, `practitioner`, `device`, `import`, `ai`. Sem um, a plataforma regista `import`.
- **Códigos que não sabe de cor:** `GET /v1/terminology/loinc?q=hba1c` pesquisa o subconjunto LOINC incluído e `GET /v1/search?q=metformin` o catálogo de sintomas, condições e medicamentos; uma observação escrita sem um nome de exibição recebe automaticamente o nome LOINC.

## Leitura de dados médicos

```bash
curl "https://platform.anpheros.com/v1/patients/$PID/observations?category=laboratory&code=4548-4&from=2026-01-01" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/conditions?clinical_status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
```

| Endpoint | Filtros |
|---|---|
| observations | `category`, `code`, `from`, `to` |
| conditions | `clinical_status` |
| medications | `status` |
| documents | `kind` |
| timeline | `from`, `to`, `types` |

As listas são paginadas com `limit` e `cursor`. A **timeline** funde observações, condições, medicamentos, documentos, visitas, consultas, vacinações e episódios de cuidados numa única lista cronológica — a entrada natural para um ecrã de histórico do paciente.

Para tudo o que os filtros REST não cobrem, utilize a pesquisa FHIR: `GET /fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date` ([plataforma FHIR](https://developers.anpheros.com/pt/guides/fhir)).

## Rastreamento e correção de dados

- **Quem escreveu:** `GET /v1/patients/{id}/provenance/{type}/{resourceId}` — uma entrada por versão, com tipo de autor, projeto, organização e sistema de origem.
- **Cada versão:** `GET /fhir/R4/{type}/{id}/_history`; atualize com `If-Match` para evitar sobrescrever a alteração de outra pessoa.
- **Propriedade:** com consentimento, pode ler o que outras organizações escreveram, mas altere ou elimine apenas o que o seu projeto escreveu (`403` caso contrário).
- **Eliminação:** `DELETE /v1/{observations|conditions|medications}/{id}`; eliminar um `Patient` elimina o registo completo.

## Documentos

Crie o documento (obtém um destino de carregamento), carregue os bytes através da plataforma ou diretamente para o armazenamento, e depois finalize. Após a finalização, o original é imutável; o seu SHA-256 e tamanho são registados. Até 25 MiB por ficheiro.

## Relacionado

- [Como normalizar dados médicos](https://developers.anpheros.com/pt/guides/normalize-medical-data): códigos, unidades, datas, duplicados, validação
- [Proveniência de dados médicos explicada](https://developers.anpheros.com/pt/guides/medical-data-provenance): quem escreveu o quê e como registar
- [API de Saúde](https://developers.anpheros.com/pt/guides/healthcare-api)
- [Registo médico do paciente](https://developers.anpheros.com/pt/guides/patient-medical-record)
- [Criar uma aplicação de saúde](https://developers.anpheros.com/pt/guides/build-a-healthcare-app)
- [Referência da API (OpenAPI)](https://developers.anpheros.com/docs) · [Introdução](https://developers.anpheros.com/pt/guides/getting-started)