# Plataforma de consentimento do paciente para aplicações de saúde

> Consentimento integrado na camada de dados: OAuth 2.1 e âmbitos SMART, propósito e expiração escolhidos pela pessoa, um registo de acesso que pode ver, revogação no próximo pedido e o que a sua aplicação ainda possui.

Source: https://developers.anpheros.com/pt/guides/patient-consent-platform

**Uma plataforma de consentimento do paciente permite que uma pessoa decida quais aplicações podem ler ou alterar o seu registo de saúde, para que propósito e por quanto tempo, e permite-lhes ver e revogar esse acesso a qualquer momento.** A Anpheros integra o consentimento na camada de dados: uma aplicação acede ao registo FHIR R4 de um paciente apenas através de uma autorização que a pessoa aprovou na página de consentimento da Anpheros, cada leitura e escrita sob essa autorização é registada onde a pessoa pode vê-la, e a revogação entra em vigor no próximo pedido. Esta página mostra como isso funciona, o que a sua aplicação tem de fazer e o que não precisa de construir.

<!-- visual:consent-flow -->

## Porquê o consentimento pertence à camada de dados

A maioria das aplicações de saúde regista o consentimento como uma caixa de seleção na sua própria base de dados e, em seguida, impõe-no no código da aplicação. Isto funciona até que uma segunda aplicação, uma integração clínica ou uma funcionalidade de IA necessite dos mesmos dados: cada uma tem de reimplementar as regras, e a pessoa não tem um único local para ver quem tem acesso. Quando a plataforma que armazena o registo também impõe o consentimento, cada cliente obtém as mesmas regras e a pessoa obtém uma lista de aplicações para rever.

| | Consentimento como um indicador na sua aplicação | Consentimento na camada de dados (Anpheros) |
|---|---|---|
| Onde é imposto | No código de cada aplicação | Em cada pedido de API, pela plataforma |
| Âmbito de acesso | Tudo o que a aplicação decide ler | Apenas os tipos de recursos e categorias concedidos |
| Expiração | Raramente implementado | Escolhido pela pessoa: 30, 90, 180 ou 365 dias |
| O que a pessoa vê | Depende da aplicação | Cada aplicação, os seus âmbitos e expiração, e um registo de acesso |
| Revogação | Tem de ser propagada manualmente | O próximo pedido falha; o token de atualização deixa de funcionar |

## O que o paciente controla

<!-- visual:consent-controls -->

## Como a sua aplicação pede consentimento

Anpheros utiliza OAuth 2.1 com PKCE e âmbitos SMART on FHIR v2. A sua aplicação envia a pessoa para a página de consentimento com os âmbitos de que necessita e um propósito opcional; após aprovação, recebe um token de acesso (30 minutos) e um token de atualização rotativo (30 dias) para um paciente específico.

```ts
import { OAuthFlow, generatePkce } from '@anpheros/sdk';

const flow = new OAuthFlow({
  baseUrl: 'https://platform.anpheros.com',
  clientId: process.env.ANPHEROS_CLIENT_ID!,
  redirectUri: 'https://your.app/callback',
});
const pkce = await generatePkce();
const url = flow.authorizeUrl({
  scopes: ['patient/Observation.rs?category=laboratory', 'patient/Condition.rs', 'offline_access'],
  purpose: 'treatment',
  state: crypto.randomUUID(),
  pkce,
  lang: 'en',
});
// redirect the person to `url`; on the callback exchange the code (see the authentication guide)
```

Um âmbito como `patient/Observation.rs?category=laboratory` limita a leitura a resultados de laboratório; o filtro de categoria é aplicado pelo servidor. Um tipo de recurso fora da concessão retorna `403`; um paciente fora da concessão retorna `404`, pelo que os IDs não podem ser sondados.

## Reagir à revogação

Quando a pessoa termina uma autorização, o próximo pedido com esse token falha e o token de atualização não consegue restabelecer o acesso. Para limpar imediatamente, subscreva o webhook `consent.revoked`, que transporta o `grant_id`, o ID do paciente que vê, os escopos e o `revoked_at`.

```ts
await anpheros.webhooks.create('https://your.app/anpheros/hook', { events: ['consent.granted', 'consent.revoked'] });
```

## O que o Anpheros não faz

- Não recolhe consentimento para fins que vão além do acesso a dados, como marketing ou participação em investigação.
- Não decide a sua base legal. O consentimento para acesso é um controlo; o seu aviso de privacidade, contratos e registos de processamento continuam a ser seus.
- A chave API de um projeto vê os pacientes que esse projeto criou, sem uma concessão. O consentimento rege o acesso por outras aplicações.

## Perguntas Frequentes

### O que é uma plataforma de consentimento do paciente?
Software que regista quais as aplicações que uma pessoa permite aceder aos seus dados de saúde, impõe essas escolhas em cada pedido, mostra à pessoa quem acedeu ao quê e permite-lhe retirar o acesso. No Anpheros, o consentimento faz parte do registo FHIR R4 em si, em vez de ser um serviço separado.

### Quais os padrões que o Anpheros utiliza para o consentimento do paciente?
OAuth 2.1 com PKCE para o fluxo de autorização e os âmbitos de paciente SMART on FHIR v2 (`patient/<Type>.<cruds>` com um filtro `?category=` opcional) para o que uma aplicação pode ler ou escrever. OpenID Connect adiciona um ID token quando solicita `openid fhirUser`.

### Pode um paciente limitar o acesso a apenas alguns dos seus dados?
Sim. O acesso é limitado aos tipos de recursos e categorias nos âmbitos concedidos, por exemplo, apenas Observações de laboratório. Todo o resto devolve um erro.

### Quanto tempo dura o consentimento?
A pessoa escolhe 30, 90, 180 ou 365 dias na página de consentimento. Após esse período, a concessão expira e a aplicação tem de pedir novamente.

### Pode o paciente ver o que uma aplicação fez com o acesso?
Sim. A pessoa vê cada aplicação com acesso, os seus âmbitos e data de expiração, e um registo de acesso listando o que cada aplicação leu ou escreveu.

### O que acontece quando o consentimento é revogado?
O próximo pedido com esse token de acesso falha, o token de atualização não pode ser utilizado para obter um novo, e o seu servidor recebe um webhook `consent.revoked` se estiver subscrito.

<!-- visual:cta-consent -->

## Relacionado

- [Modelo de consentimento e acesso](https://developers.anpheros.com/pt/guides/consent): as regras na íntegra
- [Autenticação e OAuth](https://developers.anpheros.com/pt/guides/authentication): tokens, scopes e a troca de código
- [Como implementar o consentimento do paciente com SMART on FHIR](https://developers.anpheros.com/pt/guides/smart-on-fhir-backend)
- [Webhooks](https://developers.anpheros.com/pt/guides/webhooks): `consent.granted` e `consent.revoked`
- [Proveniência de dados médicos explicada](https://developers.anpheros.com/pt/guides/medical-data-provenance)
- [API de dados longitudinais do paciente](https://developers.anpheros.com/pt/guides/longitudinal-patient-data-api)