# Modelo de consentimento e acesso

> Quem vê o quê: isolamento de projetos, IDs par a par, concessões, propriedade de escrita, proveniência e o que o paciente vê sobre cada aplicação com acesso.

Source: https://developers.anpheros.com/pt/guides/consent

**Regra:** com o consentimento do paciente, uma organização vê o registo completo — incluindo o que outras clínicas escreveram — mas só pode alterar ou eliminar o que escreveu. Cada versão de cada recurso regista o projeto que o escreveu e a organização em nome da qual foi escrito.

## Quem vê o quê
- Um **projeto** (chave API) vê os pacientes que criou. Sob uma **concessão** (token OAuth), uma aplicação vê exatamente um paciente, em todos os escritores, limitado aos âmbitos concedidos e filtros de categoria. Todo o resto retorna 404, nunca 403, para que os IDs não possam ser sondados.
- **IDs par-a-par:** cada projeto recebe o seu próprio ID para a mesma pessoa; os IDs internos nunca saem da plataforma. Referências a pacientes fora do seu âmbito são mascaradas com um token opaco, por projeto.
- **Diretório** (Organização, Praticante, Papel de Praticante): legível por ID em todo o plano para que as referências se resolvam; pesquisável apenas dentro do seu projeto; utilizável como `X-Anpheros-Acting-As` / `X-Anpheros-On-Behalf-Of` apenas quando é seu.
- **Sandbox e produção** são bases de dados diferentes. Uma chave de sandbox fisicamente não consegue aceder a pacientes reais.

## Escritas e propriedade
- `project_id` em cada versão de recurso = o autor. Atualizar/eliminar por outro projeto → 403 com uma explicação; escreva o seu próprio recurso em vez disso.
- `Provenance.agent.onBehalfOf` = a clínica/organização no momento da escrita: `X-Anpheros-On-Behalf-Of`, caso contrário, a organização do PractitionerRole em exercício, caso contrário, a organização do projeto.
- Cada escrita produz um recurso Provenance e uma linha de auditoria (quem, o quê, quando, sob qual concessão, qual aplicação, a partir de qual impressão digital de origem).

## O que o paciente vê
`/me/patients/{id}/grants` lista todas as aplicações com acesso, os seus escopos e validade; `…/access-log` lista o que cada uma leu ou escreveu — sob o consentimento **e** com a chave própria do projeto. A revogação tem efeito no próximo pedido; a aplicação não pode voltar a ser atualizada.
Com `format=fhir`, o registo de acesso retorna como um Bundle de recursos FHIR R4 `AuditEvent`, moldado segundo os Padrões Básicos de Registo de Auditoria IHE (tipo `rest`, a interação como subtipo, a aplicação e a pessoa a agir através dela como agentes, o paciente e o recurso como entidades, sem dados clínicos), para que outro sistema possa fundi-lo na vista da pessoa sobre quem acedeu ao seu registo.

O que cada recurso Provenance regista e como configurá-lo: [Proveniência de dados médicos explicada](https://developers.anpheros.com/pt/guides/medical-data-provenance).

## SMART Health Links (partilha por QR ou link)

Uma pessoa pode partilhar o seu registo sem uma aplicação intermediária: `POST /me/patients/{id}/shl` cria um
[SMART Health Link](https://hl7.org/fhir/uv/smart-health-cards-and-links/) para o subconjunto de **emergência** (alergias,
medicamentos, problemas, imunizações — sem resultados ou histórico) ou o Resumo Internacional do Paciente **completo**, com um
código de acesso e validade opcionais. A resposta transporta o URI `shlink:/…` (para um código QR) e um endereço de visualização em
`/shl/view`, que o abre em qualquer navegador. Quem o digitalizar publica no URL do manifesto e recebe o resumo como um
JWE (`dir` + `A256GCM`) encriptado com a chave dentro do link; qualquer leitor SMART Health Link funciona.

- O conteúdo é gerado a cada abertura (flag `L`, status `can-change`), pelo que um cartão guardado no telemóvel permanece atualizado.
- Um código de acesso (flag `P`) é verificado no servidor; após 10 tentativas erradas, o link deixa de funcionar.
- `GET /me/patients/{id}/shl` lista os links com a frequência e a data de cada abertura; `…/shl/{link}/revoke` desativa
  um de cada vez. Cada abertura fica registada no log de acesso.
- O ID interno da pessoa nunca sai da plataforma: o documento identifica-a através de um pseudónimo do link.

## Agentes de IA propõem, a pessoa decide

Sob consentimento da pessoa, uma escrita por um agente de IA (uma aplicação registada como agente, por exemplo, um assistente ligado através do MCP) ou qualquer escrita com `author_type` `ai` não é aplicada de imediato. A plataforma valida-a e responde `202 Accepted` com o ID da proposta (cabeçalho `Anpheros-Proposal`); nada muda no registo. A pessoa vê-a em `GET /me/patients/{id}/proposals` — o que é, que aplicação a enviou — e aceita-a ou rejeita-a (`…/proposals/{proposal}/accept` ou `…/reject`). Uma proposta aceite é escrita exatamente como enviada, marcada como escrita por IA (HL7 AI Transparency). Projetos que podem ver o registo recebem um webhook `proposal.created`. Escritas feitas com a chave própria de um projeto, em registos que o projeto criou, não são retidas.