# SDKs

> Os clientes Dart / Flutter (anpheros_sdk) e TypeScript (@anpheros/sdk): mesma estrutura, criações idempotentes, retentativas, atualização de token e fluxo de consentimento.

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

> Bibliotecas de cliente oficiais para uma API de saúde FHIR R4 com uma sandbox FHIR gratuita: pacientes, observações, resultados de laboratório, condições, medicamentos, International Patient Summary, consentimento do paciente e contexto de IA, em TypeScript e Dart / Flutter.

**Anpheros é uma infraestrutura de dados médicos interoperável para a construção de aplicações de saúde, software médico e serviços de IA.** Cada paciente tem um registo HL7 FHIR R4 que controla; aplicações, clínicas, laboratórios e agentes de IA leem e escrevem através da API da Plataforma Anpheros — com consentimento do paciente (OAuth 2.1 / SMART on FHIR), proveniência em cada escrita e um registo de acesso que o paciente pode ver. Este repositório contém as bibliotecas de cliente oficiais e exemplos executáveis.

| Linguagem | Pacote | Instalar | Código Fonte |
|---|---|---|---|
| Dart / Flutter | [`anpheros_sdk`](https://pub.dev/packages/anpheros_sdk) | `dart pub add anpheros_sdk` | [`dart/anpheros_sdk`](https://github.com/anpheros/anpheros-sdk/tree/main/dart/anpheros_sdk) |
| TypeScript (Node 18+, navegadores, Deno, Bun) | [`@anpheros/sdk`](https://www.npmjs.com/package/@anpheros/sdk) | `npm install @anpheros/sdk` | [`ts`](https://github.com/anpheros/anpheros-sdk/tree/main/ts) |

## Início rápido em 2 minutos

1. **Obtenha uma chave de sandbox gratuita:** inicie sessão no [dashboard](https://platform.anpheros.com/dashboard/) e clique em **Get a sandbox key** (`sk_test_…`). O seu sandbox tem 30 pacientes sintéticos.
2. **Verifique se funciona:**

   ```bash
   curl -H "Authorization: Bearer $ANPHEROS_KEY" "https://platform.anpheros.com/fhir/R4/Patient?_count=3"
   ```

3. **Instale um SDK e leia um registo:** `npm install @anpheros/sdk` ou `dart pub add anpheros_sdk`, depois execute o código em [Connect](#connect), ou clone [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts).

## Para quem se destina

Desenvolvedores que criam aplicações de saúde para pacientes e familiares, backends de aplicações médicas, integrações de clínicas e laboratórios, e assistentes ou agentes de IA que necessitam de contexto médico estruturado de um paciente — sem ter de conceber uma base de dados médica, um sistema de consentimento e um registo de auditoria do zero.

## Obter uma chave de sandbox

O sandbox é gratuito e self-service. Inicie sessão com o Google no [dashboard](https://platform.anpheros.com/dashboard/) e prima **Obter uma chave de sandbox**: obtém um projeto de sandbox e uma chave instantaneamente. Cada projeto de sandbox vem com os seus próprios 30 pacientes sintéticos — seis meses de condições, medicamentos, alergias, resultados de laboratório e sinais vitais — que pode alterar livremente e repor a qualquer momento. As chaves de sandbox (`sk_test_…`) nunca acedem a dados reais de pacientes.

Quando for para produção, a produção destina-se a organizações verificadas com um acordo de processamento de dados, e a produção começa em 99 € por mês com o primeiro mês gratuito ([preços](https://developers.anpheros.com/pt/guides/pricing)).

## Conectar

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });   // sk_test_… in the sandbox
const { data: patients } = await anpheros.patients.list();
const labs = await anpheros.observations.list(patients[0].id, { category: 'laboratory', limit: 10 });
const ctx = await anpheros.context.build({ patient: patients[0].id, task: 'weekly check-in', budget_tokens: 1500, format: 'text' });
```

```dart
import 'package:anpheros_sdk/anpheros_sdk.dart';

final anpheros = Anpheros(auth: AnpherosAuth.apiKey('sk_test_…'));
final patients = await anpheros.patients.list();
final labs = await anpheros.observations.list(patients.data.first.id, category: 'laboratory', limit: 10);
```

As chaves de API pertencem a servidores. Uma aplicação que atua em nome de uma pessoa utiliza OAuth em vez disso: ambos os SDKs implementam o fluxo de consentimento (código de autorização + PKCE) e atualizam tokens automaticamente.

## O que os SDKs cobrem

Ambos cobrem toda a superfície pública (`/v1`, `/fhir/R4`, `/oauth/token`, `/oauth/revoke`) com a
mesma estrutura: `patients`, `observations`, `conditions`, `medications`, `documents`, `timeline`,
`provenance`, `context`, `grants`, `terminology` e `fhir` em bruto. Um teste falha a
compilação quando uma rota pública está em falta em qualquer um dos SDKs ou quando um SDK chama uma rota que o servidor
não possui.

Ambos os SDKs: `Idempotency-Key` automático em criações, novas tentativas com backoff em 429/5xx, uma atualização de token em 401, erros tipados com o ID do pedido, auxiliares PKCE e o fluxo de consentimento.

## Dados médicos e FHIR

O registo é composto por recursos FHIR R4 standard — 26 tipos, incluindo `Observation`, `Condition`, `MedicationStatement`, `DocumentReference`, `Immunization` e `AllergyIntolerance` — codificados com LOINC, ICD-10, ATC e UCUM. A REST API (`/v1`) e a FHIR API (`/fhir/R4`) leem e escrevem os mesmos recursos com os mesmos IDs; `fhir` em ambos os SDKs fornece acesso FHIR bruto (pesquisa, transações, `$everything`, `$summary`, `$validate`).

## Exemplos

| Exemplo | Mostra |
|---|---|
| [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts) | escrever e ler um registo: medições, resultado de laboratório, diagnóstico, medicação, linha cronológica, pesquisa FHIR, IPS, contexto de IA |
| [quickstart-dart](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-dart) | o mesmo a partir de Dart / Flutter |
| [consent-app-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/consent-app-ts) | uma aplicação web que solicita consentimento (OAuth 2.1 + PKCE) e lê o registo da pessoa |
| [ai-context-llm](https://github.com/anpheros/anpheros-sdk/tree/main/examples/ai-context-llm) | uma questão sobre um registo respondida por um modelo à sua escolha (local ou alojado) |
| [fhir-transaction](https://github.com/anpheros/anpheros-sdk/tree/main/examples/fhir-transaction) | um pacote de transação FHIR R4 e o Resumo Internacional do Paciente resultante |

Os exemplos executam-se na sandbox gratuita, onde cada projeto sandbox tem os seus próprios 30 pacientes sintéticos — veja [Obter uma chave de sandbox](#get-a-sandbox-key).

## Repositórios relacionados

| Repositório | O que é |
|---|---|
| [fhir-api-openapi](https://github.com/anpheros/fhir-api-openapi) | Especificação OpenAPI 3.1 e coleção Postman da API |
| [mcp-server](https://github.com/anpheros/mcp-server) | O servidor FHIR MCP alojado para agentes de IA: configurações para Claude, Cursor, VS Code |
| [agent-skills](https://github.com/anpheros/agent-skills) | Skill de Agente, plugin Claude Code, regras do Cursor e AGENTS.md |
| [fhir-synthetic-patients](https://github.com/anpheros/fhir-synthetic-patients) | Os 30 pacientes sintéticos como FHIR R4 Bundles e NDJSON |
| [ips-examples](https://github.com/anpheros/ips-examples) | Documentos International Patient Summary em FHIR R4 |
| [fhir-validate-action](https://github.com/anpheros/fhir-validate-action) | Ação do GitHub que valida FHIR R4 JSON em CI |
| [lab-results-to-fhir](https://github.com/anpheros/lab-results-to-fhir) | CLI: relatórios de laboratório CSV / HL7 v2 → Observações FHIR |
| [healthcare-app-starters](https://github.com/anpheros/healthcare-app-starters) | Modelos de aplicações de saúde Next.js e Flutter |

## Conformidade

Resultados de testes brutos, publicados para que possam ser verificados (resultados de testes, não certificações): [conformance/](https://github.com/anpheros/anpheros-sdk/tree/main/conformance). A 28 de setembro de 2026, o grupo Standalone Launch do kit de testes Inferno SMART App Launch STU2 (v1.0.3) passou 22 de 22 testes contra a plataforma. O lançamento EHR não é suportado.

## Documentação

- [Guias para programadores](https://developers.anpheros.com/guides/)
- [Introdução](https://developers.anpheros.com/pt/guides/getting-started)
- [Sandbox FHIR](https://developers.anpheros.com/pt/guides/fhir-sandbox)
- [API de Saúde](https://developers.anpheros.com/pt/guides/healthcare-api)
- [Plataforma da API de Saúde](https://developers.anpheros.com/pt/guides/healthcare-api-platform)
- [Plataforma FHIR](https://developers.anpheros.com/pt/guides/fhir)
- [Guia do SDK](https://developers.anpheros.com/pt/guides/sdks)
- [Referência da API (OpenAPI)](https://developers.anpheros.com/docs)
- [Para assistentes de IA](https://developers.anpheros.com/llms.txt)
- [Anpheros](https://anpheros.com/)

## Problemas e segurança

Reporte bugs nos problemas deste repositório. Nunca inclua chaves de API, tokens ou dados de pacientes num problema. Relatórios de segurança: contact@anpheros.com.

## Licença

Licença Apache 2.0 — consulte o ficheiro `LICENSE` de cada pacote. Copyright 2026 Anpheros.

## @anpheros/sdk

Cliente TypeScript para a **Anpheros Platform**: um registo de saúde FHIR R4 por paciente, isolamento de projetos, consentimento do paciente (OAuth 2.1 / SMART on FHIR), proveniência em cada escrita e uma API de contexto de IA. Executa em qualquer lugar onde `fetch` exista (Node 18+, navegadores, Deno, Bun).

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });
const { data: patients } = await anpheros.patients.list();
const labs = await anpheros.observations.list(patients[0].id, { category: 'laboratory', limit: 10 });
const ctx = await anpheros.context.build({ patient: patients[0].id, task: 'weekly check-in', budget_tokens: 1500, format: 'text' });
```

Agir em nome de uma pessoa:

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

const flow = new OAuthFlow({ baseUrl: BASE, clientId: 'client_…', redirectUri: 'https://myapp.example/callback' });
const pkce = await generatePkce();
location.href = flow.authorizeUrl({ scopes: ['patient/Observation.rs?category=laboratory', 'offline_access'], state, pkce, lang: 'ro' });
// on the callback:
const tokens = await flow.exchange(code, pkce);
const anpheros = new Anpheros({ auth: new OAuthAuth({ tokens, onRefresh: flow.refresh, onTokens: persist }) });
```

Os erros são `AnpherosError` (`status`, `type`, `message`, `field`, `requestId`). As criações enviam um `Idempotency-Key`; 429/5xx são retentados; tokens expirados são atualizados uma vez e a chamada é retentada.

## anpheros_sdk

Dart / Flutter client para a **Anpheros Platform**: um backend de dados de saúde com um registo FHIR R4
por paciente, isolamento de projetos, consentimento do paciente (OAuth 2.1 / SMART on FHIR), proveniência em cada
escrita e uma API de contexto de IA.

```dart
import 'package:anpheros_sdk/anpheros_sdk.dart';

final anpheros = Anpheros(auth: AnpherosAuth.apiKey('sk_test_…'));      // server / sandbox

final patients = await anpheros.patients.list();
final elena = patients.data.first;
final labs = await anpheros.observations.list(elena.id, category: 'laboratory', limit: 10);
final ctx = await anpheros.context.build(ContextRequest(patient: elena.id, task: 'weekly check-in', budgetTokens: 1500));
```

## Agir em nome de uma pessoa (aplicações)

```dart
final flow = OAuthFlow(baseUrl: 'https://…', clientId: 'client_…', redirectUri: 'myapp://callback');
final pkce = Pkce.generate();
final url = flow.authorizeUrl(scopes: ['patient/Observation.rs?category=laboratory', 'patient/MedicationStatement.r', 'offline_access'],
                              state: 'abc', pkce: pkce, lang: 'ro');
// open `url`; on return with ?code=…:
final tokens = await flow.exchange(code: code, pkce: pkce);
final anpheros = Anpheros(auth: AnpherosAuth.oauth(
  accessToken: tokens.accessToken, refreshToken: tokens.refreshToken, expiresAt: tokens.expiresAt,
  onRefresh: flow.refresh, onTokens: persist));
final meds = await anpheros.medications.listMedications(tokens.patient!);
```

Cada objeto carrega `fhir` (a sua referência `/fhir/R4`); `anpheros.fhir` fornece acesso FHIR bruto
(ler, pesquisar, criar, transação, `$everything`, `$summary`, `$validate`).

Os erros são `AnpherosException` com `status`, `type`, `message`, `field` e `requestId`.
As criações enviam um `Idempotency-Key` automaticamente; 429/5xx são retentadas com backoff; tokens OAuth expirados
são atualizados uma vez e a chamada é retentada.