# Версионирование и устаревание

> Как изменяются интерфейсы FHIR R4 и REST v1, полезные нагрузки веб-хуков и SDK, а также как объявляются критические изменения.

Source: https://developers.anpheros.com/ru/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/ru/guides/team-sso).

- `PUT /admin/applications/{id}/branding` устанавливает логотип приложения (данные в формате PNG/JPEG/WebP URI, до 64 КБ) и
  акцентный цвет (контрастность не менее 4,5:1 с белым текстом), отображаемый на размещенной странице согласия. `ApplicationOut`
  получает `logo` и `brand_color`. См. [Аутентификация и OAuth](auth-and-oauth.md#your-brand-on-the-consent-page).
- Страница цен и [цены](https://developers.anpheros.com/ru/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`, построенный на основе отчета (ID отчета, название и код в отчете,
  дата, значение, единица измерения); существующие идентификаторы не изменяются, а более ранние результаты распознаются по названию, дате, значению, единице измерения
  и ID отчета. Два результата с разными названиями в отчете, но одинаковым кодом LOINC, датой и значением (например,
  *Glucose* и *Glicemie*) больше не объединяются в один.

### 13 октября 2026 г. (дополнительно, без изменения контракта)
- Согласие применяется ко всем производным представлениям (`/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: localhost (ранее принимался в песочнице, но никогда не доставлялся), частные и зарезервированные адреса, а также имена, разрешающиеся в них, отклоняются при регистрации с ошибкой 400 по адресу `url`; доставки осуществляются только по IP-адресам, которые они только что проверили (DNS-привязка).

## Принудительное соблюдение соответствия (анонсировано 23 сентября 2026 г.)

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