# 始めに

> APIキーから、サンドボックスでの患者のFHIR R4レコードの読み書きまで：キー、最初の呼び出し、プロビナンスを伴う書き込み、ドキュメント、AIコンテキスト、IPS、同意、Webhook、および検査レポート。

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

Anpheros Platformはヘルスデータバックエンドです。患者ごとのFHIR R4レコード、プロジェクト分離、
すべての書き込みにおけるプロビナンス、そして同じデータの上に構築されたシンプルなREST APIを提供します。このガイドでは、
何も無い状態からサンドボックスでの患者レコードの読み書きまでを説明します。

ベースURL（サンドボックスと本番環境で共有されます。キーがデータプレーンを決定します）：

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

インタラクティブリファレンス：`/docs` (OpenAPI) および `/fhir/R4/metadata` (CapabilityStatement)。

## 1. キーの取得（1分）

サンドボックスはセルフサービスです。ダッシュボード（`https://platform.anpheros.com/dashboard/`）にGoogleでサインインし、「サンドボックスキーを取得」を
押してください。組織、独自の合成患者を持つサンドボックスプロジェクト、そして一度だけ表示されるキーが取得できます。
Firebaseユーザー トークンを使用してAdmin API経由でも同様です。

```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": {…}}
```

または、ステップバイステップで：

```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"]}'
```

`sk_test_…` を取得します。サンドボックスキーはサンドボックスデータのみを参照します。
本番環境キー（`sk_live_…`）は、署名付きDPAを持つ検証済み組織に発行されます。
platform@anpheros.com までご連絡ください。サンドボックスは無料です。
本番環境は月額€99からで、最初の月は無料です（[料金](https://developers.anpheros.com/ja/guides/pricing)を参照）。

## 2. 最初の呼び出し（1分）

サンドボックスプロジェクトには、プロジェクト作成日までの6ヶ月間の履歴を持つ30人の合成患者のコピーがすでに用意されています。EU全域の成人、子供、高齢者で、病状（ICD-10）、薬剤（ATC）、アレルギー、検査結果、バイタルサイン（LOINC）が含まれています。このコピーはプロジェクト固有のものであり、変更または削除しても他のプロジェクトには影響しません。ダッシュボードの**テスト患者のリセット**（または`POST /admin/projects/{id}/sandbox/reset`）で、新しいIDとともに元の状態に戻すことができます。自分で作成した患者は変更されません。各合成患者はリセット後も安定した識別子を保持します。`Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02` は常に 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}
```

サンドボックスの制限は寛大ですが有限です。プロジェクトあたり1日10,000件のリソース書き込み、合成患者以外に自分で作成できる患者は50人、ドキュメントは250MB（[制限](https://developers.anpheros.com/ja/guides/limits)を参照）です。

## 3. レコードの読み込み

```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"
```

IDは`/v1`と`/fhir/R4`で同一です。すべてのv1オブジェクトは、その`fhir`参照を保持しています。
`_summary=count`は合計のみを返し、`_elements=code,effectiveDateTime`は`SUBSETTED`でタグ付けされたスリムリソースを返します。

## 4. 書き込み

作成者を指定します。`author_type` は `patient`、`practitioner`、`device`、`import`、または `ai` です。
省略した場合、プラットフォームは `import` を記録し、デフォルトで `patient` になることはありません。
`author_type` `ai` を使用した書き込みは、[HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/) に従います。
リソースは `AIAST` セキュリティラベル（*Artificial Intelligence asserted*）を保持し、その Provenance は理由 `AIAST`、エージェントロール `Artificial-Intelligence`、および `AI-Provenance` プロファイルを持ちます。モデルに名前を付けるには、それを `Device`（タイプ `Artificial-Intelligence`、名前、バージョン、製造元）として登録し、`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"
}'
```

レスポンスは、`id`、`fhir`、および `updated_at` を持つ保存された Observation です。同じ `Idempotency-Key` で全く同じリクエストを繰り返しても、同じレスポンスが返され、何も作成されません。

## 5. ドキュメント

```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
```

オリジナルはその後変更されることはありません。`sha256` および `size` が記録され、後で抽出する値は `derived_from` を介してドキュメントを参照します。

## 6. プロビナンス

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

バージョンごとに1つのエントリ：誰が（作成者のタイプとプロジェクト）、いつ、どのソースシステムから。

## 知っておくべきルール

- **分離**: プロジェクトは、自身が作成した患者（共有サンドボックスの患者を含む）のみを参照できます。他のプロジェクトの患者は、あなたからは見えません。`404`、決して`403`ではありません。
- **ペアワイズID**: あなたが見る患者IDはあなた固有のものです。別のプロジェクトでは、同じ人物が異なるIDで表示されます。私たちのIDは自由に保存してください。それらを相関させようとしないでください。
- **来歴**: すべての書き込みはProvenanceリソースを残します。何もサイレントに上書きされることはありません。履歴は`/fhir/R4/{Type}/{id}/_history`で利用可能です。
- **エラー**: FHIRエンドポイントは`OperationOutcome`を返します。`/v1`および`/admin`は`{"error": {"type", "message", "field"}}`を返します。すべてのレスポンスには`Anpheros-Request-Id`が含まれています。私たちに問い合わせる際は、それを引用してください。
- **制限**: デフォルトで1キーあたり600リクエスト/分、1ページあたり200アイテム、1ドキュメントあたり25 MBです。

## 7. AIモデルのためのコンテキスト

生のレコードを取得してプロンプトに適合するものを決定するのではなく、プラットフォームにコンテキストを要求します。

```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"
}'
```

セクション（サマリーカード、病状、投薬、アレルギー、検査結果、週ごとの傾向と治療前後のマーカーを含むバイタルサイン、症状、タイムライン、ドキュメント）を取得します。各項目は`author_type`と`source`でラベル付けされ、予算に合わせるために省略されたもののリスト、警告、および監査ログへの呼び出しを結び付ける`manifest_id`が含まれます。AIによって生成された値は事実と混同されることはありません。それらは`ai_notes`の下にのみ表示されます。明示的なニーズも受け入れられます。
`"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`。

## 8. 標準

- `GET /fhir/R4/Patient/{id}/$summary` は、International Patient Summary ドキュメントの Bundle を返します。
- `POST /fhir/R4/Observation/$validate?profile=eu-lab` は、検査結果が HL7 Europe Laboratory Report 2.1.0 の結果プロファイルにどの程度適合するかを報告します（エラー、警告、情報）：カテゴリ、コード（LOINC が推奨）、被験者、有効日時、実施者、および結果が登録またはキャンセルされただけの場合は値。
- `GET /v1/terminology/loinc?q=hba1c` は、バンドルされた LOINC サブセットを検索し、`GET /v1/search?q=metformin` は症状、病状、および医薬品のカタログを検索します。表示名なしで作成された観察結果には、LOINC 名が自動的に付与されます。

## 9. 患者の同意 (OAuth 2.1 + SMART on FHIR)

APIキーは、プロジェクトが作成した患者を参照します。個人の既存の記録にアクセスするには、次のように要求します。

1. アプリケーションを登録します: リダイレクト URI を指定して `POST /admin/projects/{id}/applications`
   (PKCE を使用するモバイル/Web アプリの場合は `public`、サーバーの場合は `confidential`。シークレットは一度だけ表示されます)。
2. 同意ページにユーザーを誘導します:
   `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`
   ユーザーは Anpheros にサインインし、要求内容を平易な言葉で確認し、記録 (自身の記録、
   扶養家族の記録、またはアプリがユーザーのために作成した記録) とアクセス期間を選択します。
3. コードを交換します: `POST /oauth/token` (`authorization_code` + `code_verifier`)。アクセス トークン (30 分)、
   リフレッシュ トークン (30 日、使用時にローテーション) および患者 ID を受け取ります。
4. `Authorization: Bearer at_…` を使用して API を呼び出します。その患者のみ、スコープ内のリソース
   タイプとアクションのみが表示されます。スコープ外の読み取りは `403` で応答し、検索はフィルタリングされます。

ユーザーはいつでも Anpheros から同意を取り消すことができます。次の呼び出しは `401` で応答します。すべての付与は、FHIR `Consent` リソースとしてミラーリングされ、その下でのすべてのアクセスはログに記録され、ユーザーに表示されます。ディスカバリ: `/.well-known/smart-configuration`。

## 10. Webhooks

プラットフォームからポーリングするのではなく、呼び出してもらいましょう。

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

レスポンスから`secret`を保持し、すべての配信で`Anpheros-Signature`を検証してください（SDKでは両方とも`verifyWebhookSignature`）。イベントにはIDとバージョンが含まれ、臨床データは含まれません。詳細、リトライ、例については、[webhooks.md](https://developers.anpheros.com/ja/guides/webhooks) を参照してください。

## 11. 組織と担当者

クリニック、検査機関、およびそこで働く人々は、ファーストクラスのリソースです: `Organization`、`Practitioner`、`PractitionerRole`。これらは**ディレクトリ**リソースであり、患者データではなく、同じ環境内のすべてのプロジェクトで読み取り可能で、作成したプロジェクトのみが変更できます。

```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."]}]}'
```

担当者を書き込みの背後に指定するには、`X-Anpheros-Author-Ref: Practitioner/<id>` (または `PractitionerRole`、`Organization`、`Device`) を使用します。サーバー生成の Provenance には `agent.who.reference` が含まれ、`GET /fhir/R4/Provenance?agent=Practitioner/<id>` にはその人が記録したすべてのものがリストされます。検索: `Organization?name=`、`?identifier=`、`?type=`、`Practitioner?name=`、`?family=`、`?given=`、`PractitionerRole?practitioner=`、`?organization=`、`?role=`、`?specialty=`、`?active=`。

あなたのアプリの背後にいるのは誰ですか？ プロジェクトキーを使用して行われた `/v1` または `/fhir/R4` リクエストに `X-Anpheros-Acting-As: PractitionerRole/<id>` (または `Practitioner/<id>`) を送信してください。担当者はディレクトリに存在し、アクティブである必要があります。この参照はアクセスログに書き込まれ、そのリクエストの書き込みの作成者となります (`X-Anpheros-Author-Ref` を設定しない限り)。また、接続先の患者には名前で表示されます ("Dr. Ana Popescu · Clinica Dente があなたの検査結果を読み取りました")。

## 12. ラボレポートを一括送信

ラボレポート（CSV、HL7 v2 ORU^R01、またはJSON）を一括で送信し、LOINCおよび参照範囲付きの検査結果を取得します。再送信は安全です。詳細：[lab-connector.md](https://developers.anpheros.com/ja/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
```

## 書き込み時の適合性フィードバック

臨床リソースの `POST`/`PUT` ごとに、そのセクションの IPS プロファイル、および検査結果の観察については、HL7 Europe の検査レポート規則に対してチェックが行われます。書き込みはプロファイル上の理由で拒否されることはありません（構造的な FHIR エラーは引き続き拒否されます）。何かが欠落している場合、レスポンスには以下の情報が含まれます。

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

名前が示すものを修正すると、リソースは患者の `$summary` に含まれます。2026年9月22日に追加されたリソースタイプ：`Immunization`、`MedicationAdministration`（検索 `statement=MedicationStatement/{id}`）、`RelatedPerson`、`QuestionnaireResponse`、`Basic`。他のプロジェクトがレコードに対して行った書き込みは、`data.external = true` を持つWebhookイベントとして到着するのを確認できます — [`docs/webhooks.md`](https://developers.anpheros.com/ja/guides/webhooks) を参照してください。