# 시작하기

> API 키부터 샌드박스에서 환자의 FHIR R4 레코드를 읽고 쓰는 것까지: 키, 첫 번째 호출, 출처가 포함된 쓰기, 문서, AI 컨텍스트, IPS, 동의, 웹훅 및 검사 보고서.

Source: https://developers.anpheros.com/ko/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/ko/guides/pricing) 참조).

## 2. 첫 번째 호출 (1분)

샌드박스 프로젝트에는 이미 30명의 합성 환자에 대한 자체 복사본이 있으며, 프로젝트 생성일까지 6개월간의 기록이 있습니다. 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}
```

샌드박스 제한은 넉넉하지만 유한합니다. 프로젝트당 하루 10,000개의 리소스 쓰기, 합성 환자 외에 직접 생성 가능한 환자 50명, 250MB의 문서 (제한 사항 [링크](https://developers.anpheros.com/ko/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"
```

Ids는 `/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`을 포함하는 저장된 관찰 결과입니다. 동일한 `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. Provenance

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

버전별 항목: 누가(작성자 유형 및 프로젝트), 언제, 어떤 소스 시스템에서.

## 알아두면 좋은 규칙

- **격리**: 프로젝트는 자신이 생성한 환자(공유 샌드박스 환자 포함)만 볼 수 있습니다. 다른 사용자의 환자는 사용자에게 보이지 않습니다: `404`, 절대 `403`.
- **쌍별 ID**: 사용자가 보는 환자 ID는 사용자 고유의 ID입니다. 다른 프로젝트는 동일한 사람을 다른 ID로 봅니다. 당사의 ID는 자유롭게 저장하십시오. 절대 상호 연관시키려 하지 마십시오.
- **출처**: 모든 쓰기 작업은 Provenance 리소스를 남깁니다. 아무것도 조용히 덮어쓰이지 않습니다. 기록은 `/fhir/R4/{Type}/{id}/_history`에서 확인할 수 있습니다.
- **오류**: FHIR 엔드포인트는 `OperationOutcome`를 반환합니다. `/v1` 및 `/admin`은 `{"error": {"type", "message", "field"}}`을 반환합니다. 모든 응답에는 `Anpheros-Request-Id`가 포함되어 있습니다. 당사에 문의할 때 이를 인용하십시오.
- **제한**: 기본적으로 키당 분당 600개 요청, 페이지당 200개 항목, 문서당 25MB.

## 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 문서 번들을 반환합니다.
- `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를 사용하는 모바일/웹 앱의 경우 `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. 웹훅

폴링 대신 플랫폼이 사용자를 호출하도록 하세요:

```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`을 확인하세요
(`verifyWebhookSignature`은 두 SDK 모두에 있습니다). 이벤트는 ID와 버전을 전달하며, 임상 데이터는 전달하지 않습니다.
자세한 내용, 재시도 및 예시는 [webhooks.md](https://developers.anpheros.com/ko/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/ko/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`을(를) 사용하여 웹훅 이벤트로 도착하는 것을 볼 수 있습니다. [`docs/webhooks.md`](https://developers.anpheros.com/ko/guides/webhooks)를 참조하십시오.