# Версіонування та застарівання

> Як змінюються інтерфейси FHIR R4 та REST v1, корисне навантаження вебхуків та SDK, а також як оголошуються критичні зміни.

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

- **FHIR R4** за адресою `/fhir/R4` та **REST v1** за адресою `/v1` є стабільними інтерфейсами. Додаткові зміни (нові поля, нові типи ресурсів, нові кінцеві точки, нові типи подій) випускаються без попередження; SDK та `docs/openapi.json` перегенеруються в тому ж коміті, інакше тест не пройде.
- **Критичні зміни** отримують новий префікс (`/v2`) та щонайменше **6 місяців** паралельної роботи; старий префікс відповідає з заголовками `Deprecation` та `Sunset` протягом цього періоду.
- **Корисне навантаження вебхуків** містить `type`; нові типи є додатковими. Підписник `*` повинен ігнорувати невідомі типи.
- **SDK** дотримуються semver; основна версія SDK може відмовитися від застарілого префікса API.
- **Виправлення безпеки** можуть посилити валідацію (наприклад, набори значень) без зміни версії; таке посилення оголошується в журналі змін з попередженням за 30 днів, якщо воно не усуває активну вразливість.

## Журнал змін

### 14 жовтня 2026 року (додатково: брендинг сторінки згоди, єдиний вхід для команди)

- Єдиний вхід для команди: організацію можна пов'язати з її SAML або OIDC провайдером та її доменами електронної пошти
  (`PUT /admin/organizations/{id}/sso`, адміністратори платформи), і єдиний вхід може бути обов'язковим для
  учасників. `GET /admin/sso/discover?email=` (без автентифікації) повертає провайдера для робочої електронної пошти. `OrganizationOut`
  отримує `sso_provider_id`, `sso_domains` та `sso_required`. Див. [Єдиний вхід для вашої команди](https://developers.anpheros.com/uk/guides/team-sso).

- `PUT /admin/applications/{id}/branding` встановлює логотип програми (дані URI у форматі PNG/JPEG/WebP, до 64 КБ) та
  акцентний колір (контрастність щонайменше 4.5:1 з білим текстом), що відображається на розміщеній сторінці згоди. `ApplicationOut`
  отримує `logo` та `brand_color`. Див. [Автентифікація та OAuth](auth-and-oauth.md#your-brand-on-the-consent-page).
- Сторінка цін та [ціни](https://developers.anpheros.com/uk/guides/pricing): примітка про приватну бета-версію. Запуск у продакшені відбувається після перевірки та підписання
  DPA, плани виставляються за рахунком електронною поштою, а ліміти поки що не застосовуються автоматично.

### 14 жовтня 2026 року (виправлення форми помилок та зіставлення лабораторних даних)
- Імпорт лабораторних даних: *Uree* / *Urea* зіставляється з сечовиною (`3091-6`; `22664-7` в ммоль/л) замість азоту сечовини (`3094-0`), який
  зберігається для *BUN* / *Urea nitrogen* (`14937-7` в ммоль/л). Значення не конвертуються. Жодні виробничі дані не використовували старе зіставлення.
- Імпорт лабораторних даних: ЛПНЩ з методом у звіті зіставляється з розрахованим ЛПНЩ (`13457-7`) або прямим ЛПНЩ (`18262-6`); без методу він залишається `2089-1`. *Direct* тепер є кваліфікатором, тому *Bilirubina directa* більше не зіставляється з загальним білірубіном
  (`1975-2`); він зберігає код лабораторії. Жодні виробничі дані не використовували старе зіставлення.
- Невідомі кінцеві точки та методи в `/v1` відповідають у задокументованій формі помилок (`404 not-found`, `405 not-supported`)
  замість `{"detail": "Not Found"}`; недійсні параметри запиту та обмеження швидкості на IP-адресу в `/v1` використовують
  `{"error": …}` замість `OperationOutcome` (незмінно в `/fhir/R4`); несподіваний `500` в `/v1` несе
  `error.type = "exception"` (він ніс `error.code`).
- Імпорт лабораторних даних: результати HL7 v2 з локальною або не-LOINC системою кодування зберігають код лабораторії в `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*…), більше не зіставляються з пов'язаним тестом: до цієї зміни
  *HDL cholesterol* та *LDL cholesterol*, надіслані без коду LOINC, зберігалися як загальний холестерин (2093-3).
- Імпорт лабораторних даних: повторне надсилання звіту більше не дублює результати при зміні зіставлення LOINC. Нові результати несуть другий ідентифікатор, `urn:anpheros:lab-import:v2`, побудований зі звіту (ідентифікатор звіту, назва та код у звіті,
  дата, значення, одиниця вимірювання); існуючі ідентифікатори не змінюються, а попередні результати розпізнаються за назвою, датою, значенням, одиницею вимірювання
  та ідентифікатором звіту. Два результати з різними назвами у звіті, але однаковим кодом LOINC, датою та значенням (наприклад
  *Glucose* та *Glicemie*) більше не об'єднуються в один.

### 13 жовтня 2026 року (додатково, без зміни контракту)
- Згода застосовується до кожного похідного представлення (`/v1/context`, `/v1/patients/{id}/timeline`, портал, `$everything`) з одним
  спільним правилом; запитувана, але не покрита секція з'являється в `omitted` контексту.
- OpenAPI тепер оголошує `servers`, `securitySchemes` (`bearer`, `apiKey`, `oauth2`, `firebase`), per-operation `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: localhost (раніше приймався в пісочниці, але ніколи не доставлявся), приватні та зарезервовані адреси, а також імена, що на них розв'язуються, відхиляються при реєстрації з помилкою 400 на `url`; доставки з'єднуються лише з IP-адресами, які вони щойно перевірили (DNS rebinding).

## Enforcement of Conformance (оголошено 23 вересня 2026 року)

Записи, які не відповідають вимогам IPS / HL7 Europe до лабораторних даних, наразі повертають `201`/`200` з заголовком `Anpheros-Conformance`. Після періоду спостереження (планується: 60–90 днів з моменту цього повідомлення) платформа перейде в режим **блокування**: такі записи відповідатимуть `422` із заголовком `OperationOutcome`, що перелічує кожну невідповідність. Інтегратори, яким потрібен додатковий час, можуть отримати виняток для кожного проєкту під час перехідного періоду. Типи ресурсів, додані 23 вересня 2026 року: `Procedure`, `DiagnosticReport`, `CarePlan`, `FamilyMemberHistory`, `ServiceRequest`, `Goal` (додатково).