> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wyniki

> Jak działają wyniki laboratoryjne i dokumenty w API Aniva: wartości biomarkerów, zakresy referencyjne, raporty laboratoryjne i webhooki z wynikami.

Po potwierdzeniu pobrania krwi i przetworzeniu próbek przez laboratorium wyniki stają się dostępne dla wizyty. Pobierzesz je przez `GET /api/v1/appointments/{id}/results` — zawierają wyniki biomarkerów klinicznych, wyniki biomarkerów genetycznych oraz dokumenty raportów laboratoryjnych do pobrania.

## Status wyników

Główne pole `status` w odpowiedzi z wynikami wskazuje ogólny postęp przetwarzania:

| Status | Znaczenie |
| - | - |
| `in_progress` | Część zleceń jest nadal przetwarzana przez laboratorium. |
| `completed` | Wszystkie zlecenia zostały zamknięte i co najmniej jedno zwróciło wyniki. |
| `fault` | Każde zlecenie zakończyło się błędem bez zwrócenia wyników. Nie oczekuje się już żadnych wyników. |

Poszczególne wyniki w odpowiedzi mają własny status (zobacz niżej), dzięki czemu możesz wyświetlać wyniki częściowe, gdy ogólny status to nadal `in_progress`.

Aby dowiedzieć się o zmianach wyników, zasubskrybuj [webhooki](https://docs.anivahealth.com/pl/concepts/webhooks.md). Zdarzenie `appointment.results.updated` uruchamia się przy każdej zmianie treści wyników, a `appointment.results.completed` — gdy główny status zmieni się na `completed`. Zamówienia domowych zestawów testowych wysyłają te same zdarzenia z prefiksem `home_kit_order.`. Każde zdarzenie zawiera adres URL wyników do pobrania. Nadal możesz odpytywać ten endpoint, aby uzgadniać dane.

Tablica `submissions` rozbija główny status na poszczególne zlecenia laboratoryjne. Pobranie krwi obejmujące kilka probówek lub kilka laboratoriów ma kilka wpisów, każdy z kodem `lab_code` (kodem kreskowym probówki), pod którym został zarejestrowany, oraz własnym statusem `in_progress` / `completed` / `fault`. Wpis ze statusem `fault` został odrzucony lub porzucony w laboratorium i nigdy nie zwróci wyników: próbka często trafiła do innego laboratorium, które następnie tworzy własny wpis. Główny status ma wartość `completed`, gdy każdy wpis został zamknięty i co najmniej jeden zwrócił wyniki. Każdy otrzymany wynik i każdy dokument ma ten sam `lab_code`, dzięki czemu wiesz, z której probówki pochodzi dana wartość.

## Wyniki kliniczne

Wyniki kliniczne to standardowe pomiary biomarkerów krwi — na przykład poziom witaminy D, cholesterol, hormony tarczycy i tym podobne.

Każdy wynik kliniczny zawiera:

* **`id`** — identyfikator wiersza wyniku laboratoryjnego. Pozostaje taki sam, gdy laboratorium koryguje ten wiersz, więc używaj go do operacji upsert. `null` dla wyniku `planned`.
* **`biomarker_name`** i **`category`** — co zostało zmierzone i jego grupa (np. Witaminy, Hormony).
* **`lab_code`** — kod laboratoryjny (kod kreskowy probówki), pod którym zarejestrowano wynik, jeden z kodów laboratoryjnych zamówienia. `null` dla wyniku `planned` oraz dla wyników zaraportowanych przez laboratorium bez kodu.
* **`value`** i **`value_operator`** — właściwy pomiar. Operator ma wartość `eq` (równa się) dla dokładnych wartości albo `lt`/`gt`, gdy laboratorium raportuje wartość poniżej lub powyżej zakresu pomiarowego.
* **`unit`** — jednostka miary (np. ng/mL, µIU/mL).
* **`reference_range_lab`** — granice min/max zakresu normalnego i optymalnego podane przez laboratorium dla tego wyniku, przeliczone na tę samą skalę co `value`. Granica pozostawiona przez laboratorium jako otwarta ma wartość `null`, więc przedział jednostronny, taki jak `< 50`, przychodzi jako `normal_min: null, normal_max: 50`. Każdy wynik zawiera przedział, względem którego został zmierzony, więc pacjent z wynikami z kilku pobrań krwi lub laboratoriów otrzymuje właściwy zakres dla każdego wyniku.
* **`reference_range_lab_absent_reason`** — powód, dla którego `reference_range_lab` ma wartość `null`. Ma wartość `null`, gdy zakres jest obecny, oraz przy wyniku `planned`. Zobacz [Gdy brakuje zakresu laboratoryjnego](#gdy-brakuje-zakresu-laboratoryjnego).
* **`aniva_range`** — wartości porównawcze opracowane przez Aniva w tej samej skali co `value`. Różnią się w zależności od wieku, płci i tygodnia ciąży. `normal_*` to zakres ogólny. `optimal_*` to zakres węższy. Wartości mają charakter wyłącznie informacyjny. Nie stanowią porady medycznej, diagnozy ani oceny wyniku. Aniva nie ustawia na ich podstawie żadnej flagi. Jako standard dla wyniku stosuj `reference_range_lab`. Ma wartość `null`, gdy twój klucz nie ma uprawnienia `aniva_ranges_view` lub gdy Aniva nie ma wartości dla tego biomarkera.
* **`tested_at`** — data wykonania badania.
* **`comment`** — dowolna adnotacja tekstowa z laboratorium do tego konkretnego wyniku (np. wskazówki dotyczące zakresu referencyjnego, ostrzeżenia o jakości próbki). `null`, gdy laboratorium jej nie dołączyło.
* **`status_reason`** — powód, dla którego wynik `likely_wrong` jest wątpliwy lub wynik `fault` albo `undeliverable` jest bezużyteczny. `null` dla każdego innego statusu. Odrębne od pola `comment`, które jest własną notatką laboratorium i często bywa puste w przypadku błędnych wyników.
* **`origin`** — kto dostarczył dokument, z którego pochodzi wartość; te same wartości co dla pola `origin` dokumentu poniżej. Wartość z przesłanego dokumentu (`member_upload`, `staff_upload`, `partner_upload`) pochodzi z odczytu pliku przez Aniva, a nie z raportu laboratoryjnego: przed użyciem klinicznym zweryfikuj ją z plikiem. `null` dla wyniku `planned`.
* **`lab_reported`** — dosłowny i nieprzeliczony wiersz z raportu laboratorium wykonującego badanie. Zobacz niżej.

### Zakresy Aniva

`aniva_range` zawiera wartości porównawcze opracowane przez Aniva na podstawie opublikowanych źródeł oraz
własnej selekcji. Zakresy różnią się w zależności od wieku, płci i tygodnia ciąży.
`sources` wymienia opublikowane źródła, które Aniva zapisała dla tych wartości. Lista może być pusta.

> [!WARNING]
>
> Wartości mają charakter ogólnej informacji. Nie stanowią porady medycznej, diagnozy,
> stwierdzenia medycznego ani oceny wyniku. Aniva nie udostępnia ich jako wyrobu
> medycznego. Aniva nie porównuje z nimi wyniku i nie ustawia na ich podstawie żadnej flagi.
> Standardem dla wyniku pozostają `reference_range_lab` oraz ocena lekarza.

Zasady dla twojego produktu:

* Wyświetlaj zakres Aniva wyłącznie jako uzupełnienie zakresu laboratorium, nigdy zamiast niego.
* Jeśli na podstawie zakresu Aniva tworzysz flagę, ostrzeżenie lub zalecenie, robisz to we
  własnym imieniu i na własną odpowiedzialność.
* Wyświetlaj komunikat z twojej umowy z Aniva wszędzie tam, gdzie wyświetlasz zakres Aniva.

Aby uzyskać dostęp, podpisz krótką umowę dotyczącą zakresów Aniva. Następnie dodamy
uprawnienie `aniva_ranges_view` do twojego klucza. Wartości mogą ulec zmianie bez uprzedzenia.

### Wartości znormalizowane a oryginalny wiersz laboratorium

`value`, `unit` i `reference_range_lab` są znormalizowane: każdy pomiar przeliczamy na kanoniczną jednostkę biomarkera i raportujemy pod naszą własną nazwą biomarkera, dzięki czemu ten sam analit można porównywać między laboratoriami i w czasie. Tego właśnie potrzebujesz do analizy trendów i porównań między laboratoriami, a nie jest to widok z pliku PDF laboratorium, który przegląda lekarz — fosfataza alkaliczna wydrukowana jako `48 U/l (40 - 129)` trafia do ciebie jako `0.8 µkat/L`.

`lab_reported` przekazuje równolegle ten wydrukowany wiersz: nazwę i kod analitu z laboratorium, wartość i jednostkę w formie z wydruku, przedział referencyjny zarówno jako tekst (`< 50`, `> 55`, `40 - 129`), jak i oryginalne, nieprzeliczone granice z laboratorium, a także flagę nieprawidłowości, status wyniku i notatkę.

Używaj `lab_reported`, gdy człowiek uzgadnia twoje dane z raportem laboratorium, a pól kanonicznych — do wszelkich obliczeń. Wypełnione są wyłącznie pola faktycznie przesłane przez laboratorium; nic w `lab_reported` nie jest wnioskowane, uzupełniane domyślnie ani przeliczane, a cały obiekt ma wartość `null`, gdy nie mamy surowego zapisu dla wyniku.

### Gdy brakuje zakresu laboratoryjnego

Gdy `reference_range_lab` ma wartość `null`, pole `reference_range_lab_absent_reason` wyjaśnia dlaczego:

| Wartość | Znaczenie | Wyświetl |
| - | - | - |
| `not_provided` | Zakres nie istnieje. Laboratorium żadnego nie przesłało. | „Nie dotyczy” |
| `lab_text_only` | Laboratorium wydrukowało wyłącznie tekst, np. wartość docelową, poziom ryzyka lub zakres zależny od etapu życia. | Tekst z `lab_reported.reference_range` |
| `not_measured` | Wynik ma status `undeliverable`, więc nie ma wartości do porównania. | Wartość `status_reason` |

Niektóre laboratoria drukują wartość docelową lub poziom ryzyka zamiast zakresu referencyjnego, na przykład
`Ziel: <200. >240 hoch` albo `<5.7 neg >=6.5 pos`. Nie trafiają one do `reference_range_lab`, więc jego
granice mają wartość `null`, a powód to `lab_text_only`. Wyświetlaj wydrukowany tekst dosłownie.

Zakres jednostronny, taki jak `< 20`, jest zakresem. Przychodzi w `reference_range_lab` z jedną granicą
`null`, a powód ma wartość `null`. Wyświetlając go, pozostaw otwartą stronę otwartą.

### Statusy wyników klinicznych

| Status | Znaczenie |
| - | - |
| `planned` | Badanie jest zlecone, ale wyniki z laboratorium jeszcze nie dotarły. |
| `received` | Laboratorium zwróciło wynik. |
| `corrected` | Osoba weryfikująca poprawiła wartość przekazaną przez laboratorium. |
| `likely_wrong` | Automatyczna kontrola Aniva lub członek podaje wartość w wątpliwość. Niepotwierdzone: nie pokazuj tego jako wyniku badania bez weryfikacji. Zobacz `status_reason`. |
| `fault` | Laboratorium dostarczyło wynik potwierdzony jako błędny — **nie używaj go klinicznie**. Pole `value` nadal zawiera błędną liczbę; zobacz `status_reason`. |
| `undeliverable` | Laboratorium nie mogło wyznaczyć wartości. `value` ma wartość `null`; zobacz `status_reason`. |

> [!TIP]
>
> Wyświetlając wyniki pacjentom, używaj bezpośrednio pola `value` — zawiera ono już
> skorygowaną wartość, jeśli taka istnieje.

> [!WARNING]
>
> Nigdy nie prezentuj wyniku `fault` jako wyniku badania — jego `value` jest wypełnione, ale potwierdzone jako błędne.

## Wyniki genetyczne

Wyniki genetyczne przedstawiają ustalenia na poziomie genów z analizy DNA. Każdy wynik odpowiada jednemu genowi (np. APOE, MTHFR) i zawiera:

* **`id`** — identyfikator wiersza wyniku laboratoryjnego. Pozostaje taki sam, gdy laboratorium koryguje ten wiersz, więc używaj go do operacji upsert. `null` dla wyniku `planned`.
* **`gene`** — symbol genu.
* **`lab_code`** — kod laboratoryjny (kod kreskowy probówki), pod którym zarejestrowano wynik. `null` dla wyniku `planned` oraz dla wyników zaraportowanych przez laboratorium bez kodu.
* **`genotype`** — wykryty genotyp (np. E3/E4).
* **`clinical_significance`** — klasyfikacja wyniku oparta na ACMG.
* **`risk_description`** — zrozumiałe dla człowieka wyjaśnienie, co oznacza ten genotyp.
* **`comment`** — dowolna adnotacja tekstowa z laboratorium do tego konkretnego wyniku. `null`, gdy laboratorium jej nie dołączyło.
* **`status_reason`** — powód, dla którego wynik `likely_wrong` jest wątpliwy lub wynik `fault` albo `undeliverable` jest bezużyteczny. `null` dla każdego innego statusu.
* **`origin`** — kto dostarczył dokument, z którego pochodzi wartość, tak jak w wynikach klinicznych.
* **`variants`** — konkretne wykryte warianty genetyczne, każdy ze szczegółami na poziomie SNV.

### Wartości znaczenia klinicznego

| Wartość | Kategoria |
| - | - |
| `pathogenic`, `likely_pathogenic` | Chorobotwórczy lub prawdopodobnie chorobotwórczy |
| `uncertain` | Wariant o niepewnym znaczeniu (VUS) |
| `likely_benign`, `benign` | Niechorobotwórczy |
| `high_risk`, `moderate_risk`, `low_risk` | Klasyfikacja poziomu ryzyka |
| `protective` | Wariant ochronny |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Wyniki farmakogenomiczne |

### Statusy wyników genetycznych

| Status | Znaczenie |
| - | - |
| `planned` | Badanie zostało zlecone, ale wyniki jeszcze nie dotarły. |
| `received` | Laboratorium przekazało wynik. |
| `likely_wrong` | Automatyczna kontrola Aniva lub członek ma wątpliwości co do genotypu. Niepotwierdzone. Zobacz `status_reason`. |
| `fault` | Laboratorium dostarczyło wynik potwierdzony jako błędny — **nie używaj go klinicznie**. Zobacz `status_reason`. |
| `undeliverable` | Laboratorium nie było w stanie wygenerować genotypu. Zobacz `status_reason`. |

### Struktura wariantu

Każdy wynik genetyczny zawiera tablicę `variants`. Każdy wariant obejmuje:

* **`name`** — nazwa zwyczajowa (np. APOE E4).
* **`clinical_significance`** — znaczenie na poziomie wariantu (może różnić się od znaczenia na poziomie genu).
* **`conditions`** — powiązane choroby lub schorzenia wraz z opisami.
* **`snvs`** — bazowe warianty pojedynczego nukleotydu, każdy z polami `rs_id`, `allele`, `reference_allele` i opcjonalną notacją HGVS.

## Dokumenty

Tablica `documents` w odpowiedzi z wynikami zawiera odniesienia do plików raportów laboratoryjnych do pobrania. Każdy dokument ma:

* **`id`** — UUID pliku. Przekaż go do `GET /api/v1/documents/{id}`, aby pobrać plik.
* **`file_name`** — nazwa pliku, taka sama jak przy pobieraniu (np. `20260405 - Quade Befund - 7642001234.pdf`).
* **`original_file_name`** — dokładna nazwa pliku dostarczona przez laboratorium lub osobę przesyłającą (np. `7642001234_B0012_FA_E.pdf`).
* **`origin`** — kto dostarczył plik: `lab`, `member_upload`, `staff_upload` lub `partner_upload` (przesłany przez ciebie za pomocą [Prześlij dokument](https://docs.anivahealth.com/pl/api/documents/upload-document.md)).
* **`content_type`** — typ mediów pliku (np. `application/pdf`). Większość raportów to pliki PDF. Przesłane skany mogą być obrazami lub plikami CSV.
* **`etag`** — wersja zawartości pliku; zmienia się przy każdej zmianie bajtów. Zapisz ją i pobieraj ponownie tylko wtedy, gdy się zmieni. To standardowy znacznik encji HTTP, stosowany w S3 lub Google Cloud Storage.
* **`size_bytes`** — rozmiar pliku w bajtach.
* **`lab_code`** — kod laboratoryjny (kod kreskowy probówki), do którego należy raport; `null`, jeśli laboratorium żadnego nie podało.

> [!NOTE]
>
> Dostęp do dokumentów jest weryfikowany względem profilu będącego właścicielem dokumentu.

## Wysyłanie wyników e-mailem do klienta

Możesz powiadomić klienta e-mailem, że jego wyniki są gotowe. Wywołaj
[Wyślij wyniki e-mailem](https://docs.anivahealth.com/pl/api/appointments/email-results.md) dla wizyty lub
[Wyślij wyniki e-mailem](https://docs.anivahealth.com/pl/api/home-kit-orders/email-results.md) dla zamówienia domowego zestawu testowego. Każde wywołanie wysyła jedną wiadomość e-mail.
Wywołania nie są deduplikowane.

* E-mail trafia na adres `email` profilu. Zastępczy adres `@aniva.email` jest odrzucany.
* E-mail wyświetla nazwę i logo głównej grupy profili tego profilu.
* E-mail jest w języku `language` profilu, domyślnie po angielsku.
* Ustaw `with_reports` na `true`, aby dołączyć raporty laboratoryjne.
* Dodaj `note`, aby wyświetlić w e-mailu osobistą notatkę, maksymalnie 1 000 znaków.

Jeśli profil ma wyłączone e-maile transakcyjne, wywołanie zwraca `409` z powodem
`unsubscribed`. Aby włączyć je ponownie, ustaw `transactional_emails_enabled` na `true` za pomocą
[Zaktualizuj profil](https://docs.anivahealth.com/pl/api/profiles/update-profile.md).

## E-maile o gotowości wyników

Możesz otrzymać e-mail, gdy wyniki rezerwacji będą gotowe. Ustaw `results_ready_emails` (do 5
adresów) w [Utwórz wizytę](https://docs.anivahealth.com/pl/api/appointments/create-appointment.md) lub
[Utwórz zamówienie domowego zestawu testowego](https://docs.anivahealth.com/pl/api/home-kit-orders/create-home-kit.md). Listę możesz później zmienić w
[Zaktualizuj wizytę](https://docs.anivahealth.com/pl/api/appointments/update-appointment.md) lub
[Zaktualizuj zamówienie domowego zestawu testowego](https://docs.anivahealth.com/pl/api/home-kit-orders/update-home-kit.md); `[]` wyłącza e-maile.

* Poproś nas o ustawienie domyślnych adresów e-mail dla twojej grupy profili. Rezerwacja utworzona bez
  `results_ready_emails` otrzymuje je automatycznie. Podanie listy zastępuje je dla tej rezerwacji, więc dopisz
  domyślny adres e-mail, jeśli chcesz go zachować. `[]` nie wysyła żadnych e-maili.
* Każdy adres otrzymuje jeden e-mail, gdy wszystkie wyniki laboratoryjne z rezerwacji będą ostateczne.
* Adres dodany po uzyskaniu ostatecznych wyników otrzymuje e-mail od razu.
* Wiadomość zawiera link do strony z wynikami w panelu administracyjnym Aniva. Klient jej nie otrzymuje.
* Twój klucz wymaga dostępu `results_view` do pacjenta. Bez niego żądanie zwraca `403`.

## Pokaż wyniki w swojej aplikacji

[Utwórz sesję osadzania](https://docs.anivahealth.com/pl/api/profiles/create-embed-session.md) zwraca jednorazowy adres URL do strony wyników
tylko do odczytu. Otwórz go w WebView w swojej aplikacji, aby pacjent zobaczył wyniki bez logowania.

* Twój klucz wymaga zakresów `embed` i `results_view` dla pacjenta. Poproś Aniva o zakres
  `embed`.
* Wywołuj go ze swojego serwera za każdym razem, gdy pacjent otwiera wyniki. Adres URL działa raz przez
  5 minut, a strona utrzymuje następnie 60-minutową sesję.
* `route` otwiera jedną z udostępnianych stron: listę biomarkerów, pojedynczy biomarker lub Twin 3D.
* `appearance` ustawia motyw, kolor przycisków i linków oraz widoczność twojego logo.
* `report` ogranicza stronę do jednej wizyty, jednego zamówienia domowego zestawu testowego lub jednego raportu laboratoryjnego
  przesłanego za pomocą `POST /api/v1/documents`. Pacjent widzi wtedy tylko wyniki tego raportu.
* Strona pokazuje wyłącznie wyniki laboratoryjne, tak jak to API. Nie zawiera plików, czatu ani ustawień.

## Przykładowa odpowiedź z wynikami

```json theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "3f2b8c1e-5d4a-4e7b-9a6c-2d1f0e8b7a54",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "aniva_range": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": 30,
        "optimal_max": 60,
        "sources": [
          {
            "title": "Example source title",
            "url": "https://example.com/source"
          }
        ]
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "aniva_range": null,
      "tested_at": null,
      "comment": null,
      "origin": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "b7e41d09-2c6f-4a83-8f15-6e9d3a0c4b21",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.