# 버전 관리 및 사용 중단

> FHIR R4 및 REST v1 인터페이스, 웹훅 페이로드 및 SDK가 변경되는 방식과 호환되지 않는 변경 사항이 어떻게 공지되는지에 대한 설명입니다.

Source: https://developers.anpheros.com/ko/guides/versioning

- `/fhir/R4`의 **FHIR R4** 및 `/v1`의 **REST v1**은 안정적인 인터페이스입니다. 추가 변경 사항(새 필드, 새 리소스 유형, 새 엔드포인트, 새 이벤트 유형)은 사전 통지 없이 배포됩니다. SDK 및 `docs/openapi.json`은 동일한 커밋에서 다시 생성되며, 그렇지 않으면 테스트가 실패합니다.
- **호환되지 않는 변경 사항**에는 새 접두사(`/v2`)가 부여되며 **최소 6개월** 동안 병렬로 운영됩니다. 해당 기간 동안 이전 접두사는 `Deprecation` 및 `Sunset` 헤더로 응답합니다.
- **웹훅 페이로드**는 `type`을 포함합니다. 새 유형은 추가적인 것입니다. `*`을 구독하는 경우 알 수 없는 유형은 무시해야 합니다.
- **SDK**는 semver를 따릅니다. 주요 SDK 버전에서는 사용 중단된 API 접두사가 삭제될 수 있습니다.
- **보안 수정 사항**은 버전 업데이트 없이 유효성 검사를 강화할 수 있습니다(예: 값 세트). 이러한 강화는 활성 취약점을 해결하는 경우가 아니라면 30일 전에 변경 로그에 공지됩니다.

## 변경 기록

### 2026년 10월 14일 (추가: 동의 페이지 브랜딩, 팀 SSO)

- 팀 단일 사인온: 조직을 SAML 또는 OIDC 공급업체 및 해당 이메일 도메인(`PUT /admin/organizations/{id}/sso`, 플랫폼 관리자)에 연결하고 구성원에게 단일 사인온을 요구할 수 있습니다. `GET /admin/sso/discover?email=`(인증 없음)은 작업 이메일에 대한 공급업체를 반환합니다. `OrganizationOut`은 `sso_provider_id`, `sso_domains` 및 `sso_required`을 얻습니다. [팀을 위한 단일 사인온](https://developers.anpheros.com/ko/guides/team-sso)을 참조하십시오.

- `PUT /admin/applications/{id}/branding`은 애플리케이션 로고(PNG/JPEG/WebP 데이터 URI, 최대 64KB) 및 강조 색상(흰색 텍스트와 최소 4.5:1 대비)을 설정하며, 이는 호스팅된 동의 페이지에 표시됩니다. `ApplicationOut`은 `logo` 및 `brand_color`을 얻습니다. [인증 및 OAuth](auth-and-oauth.md#your-brand-on-the-consent-page)를 참조하십시오.
- 가격 페이지 및 [가격](https://developers.anpheros.com/ko/guides/pricing): 비공개 베타 알림. 검증 및 DPA 서명 후 프로덕션이 열리고, 요금제는 이메일로 청구되며, 할당량은 아직 자동으로 적용되지 않습니다.

### 2026년 10월 14일 (오류 형식 및 실험실 매핑 수정)
- 실험실 가져오기: *Uree* / *Urea*는 요소 질소(`3094-0`) 대신 요소(`3091-6`; mmol/L 단위의 `22664-7`)에 매핑되며, 이는 *BUN* / *Urea nitrogen*(mmol/L 단위의 `14937-7`)에 대해 유지됩니다. 값은 변환되지 않습니다. 프로덕션 데이터는 이전 매핑을 사용하지 않았습니다.
- 실험실 가져오기: 보고서에 메서드가 있는 LDL은 계산된 LDL(`13457-7`) 또는 직접 LDL(`18262-6`)에 매핑됩니다. 메서드가 없으면 `2089-1`으로 유지됩니다. *Direct*는 이제 한정자이므로 *Bilirubina directa*는 더 이상 총 빌리루빈(`1975-2`)에 매핑되지 않습니다. 실험실의 코드를 유지합니다. 프로덕션 데이터는 이전 매핑을 사용하지 않았습니다.
- `/v1` 아래의 알 수 없는 엔드포인트 및 메서드는 `{"detail": "Not Found"}` 대신 문서화된 오류 형식(`404 not-found`, `405 not-supported`)으로 응답합니다. 잘못된 쿼리 매개변수 및 `/v1` 아래의 IP당 속도 제한은 `/fhir/R4` 아래에서 변경되지 않은 `{"error": …}` 대신 `OperationOutcome`을 사용합니다. `/v1` 아래의 예상치 못한 `500`은 `error.code`을 전달했던 `error.type = "exception"`을 전달합니다.
- 실험실 가져오기: 로컬 또는 비-LOINC 코딩 시스템이 있는 HL7 v2 결과는 `urn:anpheros:lab-code`(이전의 `urn:hl7:<system>`, 예: `urn:hl7:l`) 아래에서 실험실의 코드를 유지합니다. 이미 저장된 결과는 변경되지 않습니다.
- 실험실 가져오기: 영어 LOINC 이름 및 동의어 인식(*Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*, *LDL cholesterol*, *Haemoglobin*). *Glucose*만으로는 혈청 또는 플라즈마(2345-7)에 매핑됩니다. *Glicemie*와 유사합니다. 한정자가 있는 이름(예: *urine*, *non-HDL*…)은 더 이상 관련 테스트에 매핑되지 않습니다. 이 변경 이전에는 LOINC 코드가 없는 *HDL cholesterol* 및 *LDL cholesterol*이 총 콜레스테롤(2093-3)로 저장되었습니다.
- 실험실 가져오기: 보고서를 다시 보내도 LOINC 매핑이 변경될 때 결과가 중복되지 않습니다. 새 결과는 보고서(보고서 ID, 보고서의 이름 및 코드, 날짜, 값, 단위)에서 빌드된 두 번째 식별자 `urn:anpheros:lab-import:v2`를 전달합니다. 기존 식별자는 변경되지 않으며 이전 결과는 이름, 날짜, 값, 단위 및 보고서 ID로 인식됩니다. 보고서에 다른 이름이 있지만 동일한 LOINC 코드, 날짜 및 값을 가진 두 결과(예: *Glucose* 및 *Glicemie*)는 더 이상 하나로 병합되지 않습니다.

### 2026년 10월 13일 (추가, 계약 변경 없음)
- 동의는 모든 파생 뷰(`/v1/context`, `/v1/patients/{id}/timeline`, 포털, `$everything`)에서 하나의 공유 규칙으로 강제 적용됩니다. 요청되었지만 포함되지 않은 섹션은 컨텍스트의 `omitted`에 나타납니다.
- OpenAPI는 이제 `servers`, `securitySchemes`(`bearer`, `apiKey`, `oauth2`, `firebase`), 작업별 `security` 및 모든 작업에 대한 응답 스키마를 선언합니다. 생성된 클라이언트는 형식화된 응답을 얻습니다.
- 모든 `401`은 `WWW-Authenticate: Bearer`을 전달합니다.
- CapabilityStatement는 SMART(`oauth-uris` 확장, `SMART-on-FHIR` 서비스) 및 IPS 구현 가이드를 광고합니다.
- 프록시 뒤의 리디렉션은 `https://`을 유지합니다.
- `python-multipart` 0.0.20 → 0.0.32; `pip-audit`은 알려진 취약점에 대해 빌드를 차단합니다.
- 웹훅 URL은 공개 HTTPS여야 합니다. 로컬호스트(이전에는 샌드박스에서 허용되었지만 전달되지 않음), 개인 및 예약된 주소, 해당 주소로 확인되는 이름은 `url`에서 400으로 등록 시 거부됩니다. 전달은 방금 확인한 IP 주소로만 연결됩니다(DNS 리바인딩).

## 규정 준수 강제 (2026년 9월 23일 발표)

IPS / HL7 Europe 실험실 요구 사항을 누락한 쓰기는 현재 `201`/`200`을 `Anpheros-Conformance` 헤더와 함께 반환합니다. 관찰 기간(계획: 이 공지로부터 60-90일) 후 플랫폼은 **차단** 모드로 전환됩니다. 이러한 쓰기는 `422`를 반환하며 `OperationOutcome`은 모든 누락 항목을 나열합니다. 더 많은 시간이 필요한 통합자는 전환 기간 동안 프로젝트별로 면제받을 수 있습니다. 2026년 9월 23일에 추가된 리소스 유형: `Procedure`, `DiagnosticReport`, `CarePlan`, `FamilyMemberHistory`, `ServiceRequest`, `Goal` (추가).