# Wersjonowanie i wycofywanie

> Jak zmieniają się interfejsy FHIR R4 i REST v1, ładunki webhooków i SDK, oraz jak ogłaszane są zmiany łamiące kompatybilność.

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

- **FHIR R4** pod adresem `/fhir/R4` i **REST v1** pod adresem `/v1` to stabilne interfejsy. Zmiany addytywne (nowe pola, nowe typy zasobów, nowe punkty końcowe, nowe typy zdarzeń) są wdrażane bez powiadomienia; SDK i `docs/openapi.json` są regenerowane w tym samym commicie, w przeciwnym razie test zakończy się niepowodzeniem.
- **Zmiany łamiące kompatybilność** otrzymują nowy prefiks (`/v2`) i działają równolegle przez co najmniej **6 miesięcy**; stary prefiks odpowiada w tym okresie kodem `Deprecation` i nagłówkiem `Sunset`.
- **Ładunki webhooków** zawierają `type`; nowe typy są addytywne. Subskrybent `*` musi ignorować nieznane typy.
- **SDK** przestrzegają semver; główna wersja SDK może porzucić prefiks wycofywanej wersji API.
- **Poprawki bezpieczeństwa** mogą zaostrzyć walidację (na przykład zestawy wartości) bez zmiany wersji; takie zaostrzenie jest ogłaszane w dzienniku zmian z 30-dniowym wyprzedzeniem, chyba że zamyka aktywną lukę bezpieczeństwa.

## Rejestr zmian

### 14 października 2026 (dodatkowe: branding strony zgody, logowanie jednokrotne dla zespołu)

- Logowanie jednokrotne dla zespołu: organizacja może zostać powiązana z dostawcą SAML lub OIDC oraz jej domenami e-mail
  (`PUT /admin/organizations/{id}/sso`, administratorzy platformy) i logowanie jednokrotne może być wymagane dla
  członków. `GET /admin/sso/discover?email=` (bez uwierzytelnienia) zwraca dostawcę dla służbowego adresu e-mail. `OrganizationOut`
  zyskuje `sso_provider_id`, `sso_domains` i `sso_required`. Zobacz [Logowanie jednokrotne dla Twojego zespołu](https://developers.anpheros.com/pl/guides/team-sso).

- `PUT /admin/applications/{id}/branding` ustawia logo aplikacji (dane URI w formacie PNG/JPEG/WebP, do 64 KB) i
  kolor akcentu (kontrast co najmniej 4,5:1 z białym tekstem), wyświetlane na hostowanej stronie zgody. `ApplicationOut`
  zyskuje `logo` i `brand_color`. Zobacz [Uwierzytelnianie i OAuth](auth-and-oauth.md#your-brand-on-the-consent-page).
- Strona cenowa i [ceny](https://developers.anpheros.com/pl/guides/pricing): uwaga o wersji prywatnej beta. Produkcja rozpoczyna się po weryfikacji i podpisaniu
  DPA, plany są fakturowane pocztą elektroniczną, a limity nie są jeszcze automatycznie egzekwowane.

### 14 października 2026 (poprawki kształtu błędów i mapowania wyników laboratoryjnych)
- Import wyników laboratoryjnych: *Mocznik* / *Urea* jest mapowany na mocznik (`3091-6`; `22664-7` w mmol/L) zamiast na azot mocznika (`3094-0`), który
  jest zachowywany dla *BUN* / *Urea nitrogen* (`14937-7` w mmol/L). Wartości nie są konwertowane. Żadne dane produkcyjne nie używały starego mapowania.
- Import wyników laboratoryjnych: LDL z metodą w raporcie jest mapowany na obliczone LDL (`13457-7`) lub bezpośrednie LDL (`18262-6`); bez metody pozostaje `2089-1`. *Bezpośredni* jest teraz kwalifikatorem, więc *Bilirubina bezpośrednia* nie jest już mapowana na całkowitą bilirubinę
  (`1975-2`); zachowuje kod laboratorium. Żadne dane produkcyjne nie używały starego mapowania.
- Nieznane punkty końcowe i metody w ramach `/v1` odpowiadają w udokumentowanym kształcie błędu (`404 not-found`, `405 not-supported`)
  zamiast `{"detail": "Not Found"}`; nieprawidłowe parametry zapytania i limit żądań na adres IP w ramach `/v1` używają
  `{"error": …}` zamiast `OperationOutcome` (niezmienione w ramach `/fhir/R4`); nieoczekiwany `500` w ramach `/v1` niesie
  `error.type = "exception"` (nosił `error.code`).
- Import wyników laboratoryjnych: wyniki HL7 v2 z lokalnym lub nie-LOINC systemem kodowania zachowują kod laboratorium w ramach `urn:anpheros:lab-code`
  (wcześniej `urn:hl7:<system>`, na przykład `urn:hl7:l`). Wyniki już zapisane nie są zmieniane.
- Import wyników laboratoryjnych: angielskie nazwy i synonimy LOINC są rozpoznawane (*Hemoglobina A1c*, *Glikowana hemoglobina*, *Cholesterol HDL*,
  *Cholesterol LDL*, *Hemoglobina*); samo *Glukoza* jest mapowane na surowicę lub osocze (2345-7) jak *Glicemie*. Nazwy z kwalifikatorem, którego brakuje w koncepcji (*mocz*, *nie-HDL*…), nie są już dopasowywane do powiązanego badania: przed tą zmianą
  *Cholesterol HDL* i *Cholesterol LDL* wysłane bez kodu LOINC były zapisywane jako całkowity cholesterol (2093-3).
- Import wyników laboratoryjnych: ponowne wysłanie raportu nie powoduje już duplikowania wyników po zmianie mapowania LOINC. Nowe wyniki niosą drugi identyfikator, `urn:anpheros:lab-import:v2`, zbudowany z raportu (identyfikator raportu, nazwa i kod w raporcie,
  data, wartość, jednostka); istniejące identyfikatory pozostają niezmienione, a wcześniejsze wyniki są rozpoznawane po nazwie, dacie, wartości, jednostce
  i identyfikatorze raportu. Dwa wyniki z różnymi nazwami w raporcie, ale tym samym kodem LOINC, datą i wartością (na przykład
  *Glukoza* i *Glicemie*) nie są już łączone w jeden.

### 13 października 2026 (dodatkowe, bez zmian w umowie)
- Zgoda jest egzekwowana na każdym pochodnym widoku (`/v1/context`, `/v1/patients/{id}/timeline`, portal, `$everything`) z jedną
  wspólną regułą; żądana, ale nieobjęta sekcja pojawia się w kontekście `omitted`.
- OpenAPI deklaruje teraz `servers`, `securitySchemes` (`bearer`, `apiKey`, `oauth2`, `firebase`), per-operacyjne `security`
  i schemat odpowiedzi dla każdej operacji; wygenerowane klienty otrzymują typowane odpowiedzi.
- Każdy `401` niesie `WWW-Authenticate: Bearer`.
- CapabilityStatement reklamuje SMART (rozszerzenie `oauth-uris`, usługa `SMART-on-FHIR`) i przewodnik implementacji IPS.
- Przekierowania za proxy zachowują `https://`.
- `python-multipart` 0.0.20 → 0.0.32; `pip-audit` blokuje kompilację przy znanych lukach bezpieczeństwa.
- Adresy URL webhooków muszą być publiczne HTTPS: localhost (wcześniej akceptowany w piaskownicy, ale nigdy nie dostarczany), adresy prywatne i zarezerwowane oraz nazwy do nich rozwiązujące są odrzucane przy rejestracji z kodem 400 na `url`; dostawy łączą się tylko z adresami IP, które właśnie sprawdziły (DNS rebinding).

## Egzekwowanie zgodności (ogłoszone 23 września 2026 r.)

Zapisy niespełniające wymagań laboratoryjnych IPS / HL7 Europe zwracają obecnie `201`/`200` z nagłówkiem `Anpheros-Conformance`. Po okresie obserwacji (planowany: 60–90 dni od niniejszego ogłoszenia) platforma przełączy się w tryb **blokowania**: takie zapisy będą zwracać `422` z nagłówkiem `OperationOutcome` wymieniającym każdą lukę. Integratorzy potrzebujący więcej czasu mogą uzyskać zwolnienie dla poszczególnych projektów w okresie przejściowym. Typy zasobów dodane 23 września 2026 r.: `Procedure`, `DiagnosticReport`, `CarePlan`, `FamilyMemberHistory`, `ServiceRequest`, `Goal` (dodatkowe).