# API de Saúde: o que é e como funciona

> O que é uma API de saúde, como funciona uma chamada, o que procurar e uma API de saúde FHIR R4 gratuita com consentimento do paciente, proveniência e alojamento na UE — com exemplos e FAQ.

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

**Uma API de saúde é uma interface programática através da qual o software lê e escreve dados de saúde — registos de pacientes, observações, diagnósticos, medicamentos, documentos — e através da qual o acesso a esses dados é autorizado.** A API da Plataforma Anpheros é uma API de saúde sobre um registo HL7 FHIR R4 controlado pelo paciente: as aplicações utilizam-na para armazenar e recuperar dados médicos, para obter o consentimento de um paciente e para ser notificado de alterações.

<!-- visual: hapi-hero -->

## Como funciona uma chamada de API de saúde

Independentemente do fornecedor, uma chamada de API de saúde passa pelos mesmos pontos de verificação: quem está a chamar, qual o paciente e quais os dados que podem aceder, onde os dados estão armazenados, quem os escreveu e quem precisa de saber que foram alterados.

<!-- visual: hapi-request -->

## Tipos de APIs de saúde

| Tipo | O que troca | Uso típico |
|---|---|---|
| APIs REST FHIR | Recursos FHIR sobre HTTP (`GET /Observation?patient=…`) | o padrão moderno para troca de dados clínicos |
| SMART on FHIR / OAuth | autorização para APIs FHIR | permitir que aplicações de terceiros acedam a um registo com a permissão do utilizador |
| Mensagens HL7 v2 | mensagens delimitadas por pipe (`ORU^R01` para resultados, `ADT` para admissões) | sistemas de laboratório e hospitalares, frequentemente através de interfaces em vez de HTTP |
| Troca de documentos | documentos clínicos (PDF, CDA, pacotes de documentos FHIR) | resumos, cartas de alta, referências |
| APIs REST proprietárias | JSON específico do fornecedor | a aplicação móvel de um único produto ou integrações |

A Anpheros combina as duas primeiras como o seu núcleo, aceita resultados de laboratório HL7 v2 como entrada, armazena documentos com os seus originais e produz pacotes de documentos FHIR (o Resumo Internacional do Doente). Oferece também uma API REST mais simples sobre os mesmos dados para programadores que não querem trabalhar diretamente com FHIR.

## O que procurar numa API de saúde

<!-- visual:hapi-checklist:replace -->

- **Um modelo de dados standard**, para que os dados possam transitar entre sistemas sem mapeamento personalizado.
- **Autorização controlada pelo paciente**, não apenas credenciais controladas pela aplicação.
- **Proveniência**: quem escreveu cada valor, em nome de quem, a partir de que sistema.
- **Histórico**: versões em vez de sobrescritas silenciosas.
- **Auditabilidade** de leituras, não apenas de escritas.
- **Retentativas seguras** (idempotência) e **erros previsíveis**, pois os dados de saúde não devem ser duplicados ou perdidos.
- **Isolamento** entre as aplicações que partilham a mesma infraestrutura.
- **Residência de dados** que corresponda à localização dos pacientes.

O resto desta página mostra como cada um destes aspetos aparece na API Anpheros.

## A API Anpheros em resumo

| Superfície | Caminho base | Propósito |
|---|---|---|
| FHIR R4 | `/fhir/R4` | 26 tipos de recursos; read, search, create, update, delete, history, transactions, `$everything`, `$summary`, `$validate` |
| REST v1 | `/v1` | patients, observations, conditions, medications, documents, timeline, provenance, AI context, lab import, terminology, webhooks |
| OAuth 2.1 | `/oauth` | página de consentimento, tokens (PKCE), revogação, chaves OpenID Connect |
| Lado do paciente | `/me` | os próprios registos de uma pessoa, quem tem acesso, registo de acesso, revogar |
| Descoberta | `/fhir/R4/metadata`, `/fhir/R4/.well-known/smart-configuration`, `/openapi.json` | descrições da API legíveis por máquina |

URL base: `https://platform.anpheros.com`. O sandbox e a produção partilham-no; a chave decide o plano de dados.

### Autenticação

- **API keys** (`sk_test_…`, `sk_live_…`) para os seus servidores; veem os pacientes que o seu projeto criou.
- **OAuth access tokens** (`at_…`) para uma aplicação que atua em nome de um paciente sob consentimento.

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

### Escrita segura

As requisições `POST` aceitam um `Idempotency-Key`: uma requisição repetida com a mesma chave retorna a resposta original e não cria nada. Cada escrita recebe um `Provenance`; o tipo de autor é enviado no corpo (`author_type`) ou em cabeçalhos como `X-Anpheros-Author-Type`, `X-Anpheros-Source-System`, `X-Anpheros-Origin-Id` e `X-Anpheros-On-Behalf-Of`.

```bash
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": "29463-7", "display": "Body weight", "category": "vital-signs",
          "value": 71.4, "unit": "kg", "effective_at": "2026-09-28T07:30:00Z", "author_type": "patient"}'
```

### Erros e limites

Os endpoints FHIR respondem com `OperationOutcome`; os outros com `{"error": {"type", "message", "field"}}`. Cada resposta contém `Anpheros-Request-Id`. O limite padrão é de 600 requisições por minuto por chave e por IP. [Erros](https://developers.anpheros.com/pt/guides/errors) · [Limites](https://developers.anpheros.com/pt/guides/limits)

### Eventos

Webhooks assinados para `resource.created`, `resource.updated`, `resource.deleted`, `consent.granted`, `consent.revoked`, `document.finalized` e `ping`. [Webhooks](https://developers.anpheros.com/pt/guides/webhooks)

## Escolher entre FHIR e REST v1

Utilize **FHIR** quando já trabalha com FHIR, necessita de tipos de recursos que `/v1` não cobre (por exemplo `Immunization`, `Procedure` ou `CarePlan`), ou troca dados com outros sistemas FHIR. Utilize **REST v1** para código de aplicação que pretenda JSON plano para os casos comuns. Ambos leem e escrevem os mesmos recursos com os mesmos IDs, pelo que um projeto pode misturá-los. [Medical data API](https://developers.anpheros.com/pt/guides/medical-data-api) descreve as operações de dados em detalhe.

## Perguntas Frequentes

### O que é uma API de saúde?
Uma interface programática através da qual o software lê e escreve dados de saúde — registos de pacientes, observações, diagnósticos, medicamentos e documentos — e através da qual o acesso a esses dados é autorizado. As APIs de saúde modernas utilizam HL7 FHIR R4 para os dados e OAuth 2.0 ou 2.1 com SMART on FHIR para autorização.

### Qual é a diferença entre uma API de saúde e uma API FHIR?
FHIR é um padrão que uma API de saúde pode seguir. Uma API FHIR troca recursos FHIR sobre REST; uma API de saúde pode também aceitar mensagens HL7 v2, documentos ou JSON proprietário. A Anpheros oferece uma API FHIR R4 e uma API REST mais simples sobre os mesmos dados.

### Existe uma API de saúde gratuita para programadores?
Sim. O sandbox da Anpheros é gratuito e auto-serviço: inicie sessão com o Google, obtenha uma chave de API e trabalhe com 30 pacientes sintéticos sobre FHIR R4 ou REST. A produção começa em €99 por mês, com o primeiro mês gratuito.

### Como é que os pacientes dão consentimento a uma API de saúde?
Através do OAuth 2.1 com PKCE: a aplicação envia a pessoa para uma página de consentimento com âmbitos SMART on FHIR; a pessoa escolhe o que partilhar e por quanto tempo, pode ver um registo de acesso e pode revogar o acesso a qualquer momento.

### Onde são armazenados os dados?
Na União Europeia: o serviço e as suas bases de dados funcionam no Google Cloud `europe-west4` (Países Baixos).

### Qual API de saúde devo escolher?
Compare o padrão de dados, quem autoriza o acesso, proveniência e auditoria, residência dos dados, como as retentativas e os erros se comportam, e se pode testar com dados realistas gratuitamente. [Plataforma de API de saúde: o que inclui e como escolher](https://developers.anpheros.com/pt/guides/healthcare-api-platform) transforma estes pontos em perguntas a fazer a qualquer fornecedor.

<!-- visual:cta-hapi -->

## Relacionado

- [API EHR e API de registos médicos](https://developers.anpheros.com/pt/guides/ehr-api)
- [Plataforma de API de saúde: o que inclui e como escolher](https://developers.anpheros.com/pt/guides/healthcare-api-platform)
- [Como criar uma API de saúde com TypeScript](https://developers.anpheros.com/pt/guides/healthcare-api-typescript): tutorial passo a passo com Express
- [Como armazenar registos médicos usando FHIR R4](https://developers.anpheros.com/pt/guides/store-medical-records-fhir): tutorial passo a passo com curl
- [API de saúde com consentimento do paciente](https://developers.anpheros.com/pt/guides/healthcare-api-patient-consent)
- [Backend SMART on FHIR](https://developers.anpheros.com/pt/guides/smart-on-fhir-backend)
- [API de dados médicos](https://developers.anpheros.com/pt/guides/medical-data-api)
- [Plataforma FHIR](https://developers.anpheros.com/pt/guides/fhir)
- [Interoperabilidade de dados de saúde](https://developers.anpheros.com/pt/guides/interoperability)
- [Integrações de saúde](https://developers.anpheros.com/pt/guides/healthcare-integrations)
- [Referência da API (OpenAPI)](https://developers.anpheros.com/docs) · [Autenticação e OAuth](https://developers.anpheros.com/pt/guides/authentication)