# Começar

> De uma chave de API à leitura e escrita do registo FHIR R4 de um paciente na sandbox: chaves, primeiras chamadas, escritas com proveniência, documentos, contexto de IA, IPS, consentimento, webhooks e relatórios de laboratório.

Source: https://developers.anpheros.com/pt/guides/getting-started

A Plataforma Anpheros é um backend de dados de saúde: um registo FHIR R4 por paciente, isolamento de projetos,
proveniência em cada escrita e uma API REST simples sobre os mesmos dados. Este guia leva-o
do zero à leitura e escrita do registo de um paciente na sandbox.

URL base (sandbox e produção partilham-no; a chave decide o plano de dados):

```
https://platform.anpheros.com
```

Referência interativa: `/docs` (OpenAPI) e `/fhir/R4/metadata` (CapabilityStatement).

## 1. Obter uma chave (1 minuto)

O sandbox é self-service. Inicie sessão no dashboard (`https://platform.anpheros.com/dashboard/`)
com o Google e prima **Obter uma chave de sandbox**: obtém uma organização, um projeto de sandbox com os seus próprios
pacientes sintéticos e uma chave — mostrada uma vez. O mesmo através da Admin API, com o seu token de utilizador Firebase:

```bash
curl -X POST $BASE/admin/sandbox/quickstart -H "Authorization: Bearer $FIREBASE_ID_TOKEN"
# {"organization": {…}, "project": {"id": "proj_…", "environment": "sandbox", …}, "key": {"key": "sk_test_…", …}, "sandbox": {…}}
```

Ou passo a passo:

```bash
# 1. an organization (you become its owner)
curl -X POST $BASE/admin/organizations -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI SRL","kind":"developer","country":"RO"}'
# 2. a sandbox project (it comes with its own synthetic patients)
curl -X POST $BASE/admin/organizations/org_…/projects -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI dev","environment":"sandbox"}'
# 3. a key — the plain key is returned exactly once
curl -X POST $BASE/admin/projects/proj_…/keys -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"local dev","scopes":["read","write"]}'
```

Obtém `sk_test_…`. As chaves de sandbox apenas veem dados de sandbox. As chaves de produção (`sk_live_…`) são
emitidas a organizações verificadas com um DPA assinado — escreva para platform@anpheros.com. O sandbox é gratuito;
a produção começa em 99 € por mês e o primeiro mês é gratuito (ver [Preços](https://developers.anpheros.com/pt/guides/pricing)).

## 2. Primeira chamada (1 minuto)

O seu projeto sandbox já tem a sua própria cópia de 30 pacientes sintéticos, com seis meses de histórico
até ao dia em que o projeto foi criado: adultos, crianças e idosos de toda a UE, com
condições (ICD-10), medicamentos (ATC), alergias, resultados de laboratório e sinais vitais (LOINC). A cópia
pertence ao seu projeto: altere ou elimine qualquer coisa — nenhum outro projeto a vê. **Repor pacientes de teste**
no dashboard (ou `POST /admin/projects/{id}/sandbox/reset`) devolve-os ao estado original,
com novos IDs; os pacientes que criou pessoalmente não são afetados. Cada paciente sintético mantém um
identificador estável entre reposições: `Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02`
é sempre Elena Ionescu.

```bash
export KEY=sk_test_…
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"
```

```json
{"data":[{"id":"…","given":"Elena","family":"Ionescu","birth_date":"1985-09-03","gender":"female",…,"fhir":"Patient/…"}, …],"total":30,"next_cursor":null}
```

Os limites do sandbox são generosos mas finitos: 10 000 escritas de recursos por dia por projeto, 50 pacientes seus
além dos sintéticos, 250 MB de documentos (ver [limites](https://developers.anpheros.com/pt/guides/limits)).

## 3. Ler um registo

```bash
# lab results, newest first
curl "$BASE/v1/patients/$PID/observations?category=laboratory&limit=10" -H "Authorization: Bearer $KEY"
# active medications
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
# everything on one timeline
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
# the same data, strict FHIR
curl "$BASE/fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date" -H "Authorization: Bearer $KEY"
```

Os IDs são idênticos em `/v1` e `/fhir/R4`; cada objeto v1 carrega a sua referência `fhir`.
`_summary=count` retorna apenas o total; `_elements=code,effectiveDateTime` retorna recursos *slim* marcados com `SUBSETTED`.

## 4. Escrever

Indique quem é o autor. `author_type` é `patient`, `practitioner`, `device`, `import` ou `ai`;
se omitir, a plataforma regista `import`, nunca `patient` por defeito.
Escrever com `author_type` `ai` segue a [HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/):
o recurso transporta o rótulo de segurança `AIAST` (*Artificial Intelligence asserted*) e a sua Provenance tem a razão
`AIAST`, o papel do agente `Artificial-Intelligence` e o perfil `AI-Provenance`. Para nomear o modelo, registe-o como um
`Device` (tipo `Artificial-Intelligence`, nome, versão, fabricante) e envie `X-Anpheros-Author-Ref: Device/<id>`.

```bash
curl -X POST "$BASE/v1/patients/$PID/observations" -H "Authorization: Bearer $KEY" \
     -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "2339-0", "display": "Glucose", "category": "laboratory",
  "value": 112, "unit": "mg/dL", "effective_at": "2026-09-19T08:10:00Z",
  "author_type": "device"
}'
```

A resposta é a observação armazenada com `id`, `fhir` e `updated_at`. Repetir o exato
mesmo pedido com o mesmo `Idempotency-Key` retorna a mesma resposta e não cria nada.

## 5. Documentos

```bash
# 1. create the document → upload target
curl -X POST "$BASE/v1/patients/$PID/documents" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"title":"Analize 2026-09-14","kind":"lab_report","content_type":"application/pdf","date":"2026-09-14"}'
# 2. upload the bytes to the returned url (direct to storage, or through the platform)
curl -X PUT "$BASE/v1/documents/$DOC/content" -H "Authorization: Bearer $KEY" -H 'content-type: application/pdf' --data-binary @analize.pdf
```

O original nunca é modificado após isso; `sha256` e `size` são registados, e quaisquer valores que
posteriormente extraia apontam de volta para o documento através de `derived_from`.

## 6. Proveniência

```bash
curl "$BASE/v1/patients/$PID/provenance/Observation/$OBS" -H "Authorization: Bearer $KEY"
```

Uma entrada por versão: quem (tipo de autor e projeto), quando, de que sistema de origem.

## Regras a saber

- **Isolamento**: um projeto vê os pacientes que criou (mais os pacientes da sandbox partilhada). Pacientes de outra pessoa não existem para si: `404`, nunca `403`.
- **IDs par a par**: o ID do paciente que vê é o seu. Outro projeto vê a mesma pessoa sob um ID diferente. Armazene os nossos IDs livremente; nunca tente correlacioná-los.
- **Proveniência**: cada escrita deixa um recurso Provenance. Nada é substituído silenciosamente; o histórico está disponível em `/fhir/R4/{Type}/{id}/_history`.
- **Erros**: os endpoints FHIR retornam `OperationOutcome`; `/v1` e `/admin` retornam `{"error": {"type", "message", "field"}}`. Cada resposta carrega `Anpheros-Request-Id`; cite-o quando nos escrever.
- **Limites**: 600 pedidos/minuto por chave por defeito, 200 itens por página, 25 MB por documento.

## 7. Contexto para um modelo de IA

Em vez de extrair registos brutos e decidir o que se adequa a um prompt, peça à plataforma um contexto:

```bash
curl -X POST "$BASE/v1/context" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -d '{
  "patient": "'$PID'",
  "task": "medication review before a cardiology visit",
  "question": "How did blood pressure evolve over the last 3 months?",
  "budget_tokens": 1500,
  "format": "text"
}'
```

Obtém secções (cartão de resumo, condições, medicamentos, alergias, exames laboratoriais, sinais vitais com tendências semanais e marcadores antes/depois do tratamento, sintomas, linha cronológica, documentos), cada item rotulado com `author_type` e `source`, uma lista do que foi omitido para caber no orçamento, avisos e um `manifest_id` que liga a chamada ao registo de auditoria. Os valores produzidos pela IA nunca são misturados com factos: aparecem apenas em `ai_notes`. Necessidades explícitas também são aceites: `"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. Normas

- `GET /fhir/R4/Patient/{id}/$summary` devolve um Bundle de documento International Patient Summary.
- `POST /fhir/R4/Observation/$validate?profile=eu-lab` reporta como um resultado de laboratório se compara ao perfil de resultado do HL7 Europe Laboratory Report 2.1.0 (erros, avisos, informações): categoria, código (LOINC preferido), sujeito, tempo efetivo, um executante e um valor, a menos que o resultado seja apenas registado ou cancelado.
- `GET /v1/terminology/loinc?q=hba1c` pesquisa o subconjunto LOINC agrupado e `GET /v1/search?q=metformin` o catálogo de sintomas, condições e medicamentos; observações criadas sem um nome de exibição recebem automaticamente o nome LOINC.

## 9. Consentimento do Paciente (OAuth 2.1 + SMART on FHIR)

As chaves de API veem os pacientes que o seu projeto criou. Para aceder ao registo existente de uma pessoa, peça-lhe:

1. Registe uma aplicação: `POST /admin/projects/{id}/applications` com o seu URI de redirecionamento
   (`public` para aplicações móveis/web com PKCE, `confidential` para servidores; o segredo é mostrado uma vez).
2. Envie a pessoa para a página de consentimento:
   `GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256&scope=patient/Observation.rs?category=laboratory patient/MedicationStatement.r offline_access&purpose=treatment&lang=ro`
   Ela inicia sessão no Anpheros, vê o que pede em linguagem clara, escolhe o registo (o seu próprio,
   o de um dependente ou o que a sua aplicação criou para ela) e por quanto tempo o acesso dura.
3. Troque o código: `POST /oauth/token` (`authorization_code` + `code_verifier`). Recebe um
   token de acesso (30 min), um token de atualização (30 dias, rotacionado a cada utilização) e o ID do paciente.
4. Chame a API com `Authorization: Bearer at_…`. Vê apenas esse paciente, apenas os tipos de recursos
   e ações nos escopos; leituras fora do escopo respondem com `403`, as pesquisas são filtradas.

A pessoa pode revogar a qualquer momento a partir do Anpheros; a próxima chamada responderá com `401`. Cada concessão é
refletida como um recurso FHIR `Consent`, e cada acesso sob ela é registado e visível para a
pessoa. Descoberta: `/.well-known/smart-configuration`.

## 10. Webhooks

Deixe a plataforma chamá-lo em vez de fazer polling:

```bash
curl -X POST $BASE/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://your.app/anpheros/hook", "events": ["*"]}'
```

Mantenha o `secret` da resposta e verifique `Anpheros-Signature` em cada entrega
(`verifyWebhookSignature` em ambos os SDKs). Os eventos transportam IDs e versões, não dados clínicos.
Detalhes, retentativas e exemplos: [webhooks.md](https://developers.anpheros.com/pt/guides/webhooks).

## 11. Organizações e Praticantes

Clínicas, laboratórios e as pessoas que trabalham neles são recursos de primeira classe: `Organization`,
`Practitioner`, `PractitionerRole`. São recursos de **diretório**: nenhum paciente, legível por
cada projeto no mesmo ambiente, alterável apenas pelo projeto que os criou.

```bash
curl -X POST $BASE/fhir/R4/Practitioner -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Practitioner","active":true,"name":[{"family":"Popescu","given":["Ana"],"prefix":["Dr."]}]}'
```

Nomeie o praticante por trás de uma escrita com `X-Anpheros-Author-Ref: Practitioner/<id>` (ou um
`PractitionerRole`, `Organization`, `Device`): a Provenance gerada pelo servidor então carrega
`agent.who.reference`, e `GET /fhir/R4/Provenance?agent=Practitioner/<id>` lista tudo
que essa pessoa registou. Pesquisa: `Organization?name=`, `?identifier=`, `?type=`, `Practitioner?name=`,
`?family=`, `?given=`, `PractitionerRole?practitioner=`, `?organization=`, `?role=`, `?specialty=`, `?active=`.

Quem está a trabalhar por trás da sua aplicação? Envie `X-Anpheros-Acting-As: PractitionerRole/<id>` (ou
`Practitioner/<id>`) em qualquer pedido `/v1` ou `/fhir/R4` feito com uma chave de projeto. A pessoa deve
existir no diretório e estar ativa. A referência é escrita no log de acesso, torna-se o
autor das escritas desse pedido (a menos que defina `X-Anpheros-Author-Ref`) e é mostrada ao
paciente pelo nome nas suas conexões ("Dr. Ana Popescu · Clínica Dente leu os seus resultados de laboratório").

## 12. Relatórios de laboratório numa única chamada

Envie um relatório de laboratório completo (CSV, HL7 v2 ORU^R01 ou JSON) e obtenha Observações laboratoriais com LOINC
e intervalos de referência; reenviar é seguro. Detalhes: [lab-connector.md](https://developers.anpheros.com/pt/guides/lab-connector).

```bash
curl -X POST "$BASE/v1/patients/$PATIENT/labs/import" -H "Authorization: Bearer $KEY" -H "Content-Type: text/csv" --data-binary @report.csv
```

## Feedback de Conformidade em Escritas

Cada `POST`/`PUT` de um recurso clínico é verificado em relação ao perfil IPS da sua secção e, para
observações de laboratório, às regras de relatório de laboratório da HL7 Europe. A escrita nunca é rejeitada por
motivos de perfil (erros estruturais FHIR ainda o são); quando algo está em falta, a resposta transporta

```
Anpheros-Conformance: warnings=2; IPS Condition: Condition without code | ...
```

Corrija o que é nomeado e o recurso será incluído no `$summary` do paciente. Tipos de recursos adicionados
em 22 de setembro de 2026: `Immunization`, `MedicationAdministration` (pesquisa `statement=MedicationStatement/{id}`),
`RelatedPerson`, `QuestionnaireResponse`, `Basic`. Escritas feitas por outros projetos num registo que pode
ver chegam como eventos webhook com `data.external = true` — consulte [`docs/webhooks.md`](https://developers.anpheros.com/pt/guides/webhooks).