> ## 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.

# Wizyty

> Jak działają wizyty na pobranie krwi w API Aniva do badań laboratoryjnych: rezerwacja, panele, biomarkery, zmiany statusu i anulowanie.

Wizyta to zaplanowane pobranie krwi dla profilu pacjenta w stacjonarnym punkcie pobrań, wykonywane przez personel medyczny. Zestawy wysyłane pocztą do pacjenta nie są wizytami — zobacz [Zamówienia domowych zestawów testowych](https://docs.anivahealth.com/pl/concepts/home-kit-orders.md).

## Pola

**id** `string` *required*

UUID generowany automatycznie przez Aniva. Użyj go, aby dodać panele, potwierdzić pobranie krwi i pobrać wyniki.

**profile\_id** `string` *required*

UUID profilu, do którego należy ta wizyta.

**location\_id** `string`

UUID punktu pobrań, w którym odbędzie się pobranie krwi. Domowe zestawy testowe nie są wizytami — zobacz
[Zamówienia domowych zestawów testowych](https://docs.anivahealth.com/pl/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Zaplanowana data i godzina pobrania krwi w formacie ISO 8601. Zawsze zwracana jako czas UTC z
przyrostkiem `Z` (np. `2026-04-15T08:30:00Z`). Podczas tworzenia / aktualizacji wartość **musi
zawierać oznaczenie strefy czasowej** (`Z` lub jawne przesunięcie, np. `+02:00`) — daty bez strefy
czasowej są odrzucane. Musi być w przyszłości, a w lokalizacjach prowadzonych przez Aniva co
najmniej 12 godzin naprzód ([minimalne
wyprzedzenie](https://docs.anivahealth.com/pl/api/appointments/create-appointment.md#minimalne-wyprzedzenie)).

**status** `string` *required*

Aktualny status cyklu życia. Jedna z wartości: `pending`, `confirmed`, `blood_drawn` lub `cancelled`.
Zobacz [Cykl życia](#cykl-zycia) poniżej. Szczegółowy stan realizacji wyników laboratoryjnych
(`in_progress` lub `completed`) pochodzi z [Pobierz wyniki](https://docs.anivahealth.com/pl/api/appointments/get-results.md); dokładniejszy
postęp przesyłki (w drodze, dostarczona itp.) sprawdzisz, przechodząc z każdego wpisu w osadzonej
tablicy `shipments` do [Pobierz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Dowolny tekst powodu zapisany przy anulowaniu wizyty (np. nieobecność, późne anulowanie,
„Nieudane. Wymagane powtórzenie”). Ma wartość `null`, chyba że `status` to `cancelled`.

**results\_ready\_emails** `string[]` *required*

Adresy zapisane małymi literami, z których każdy otrzymuje jednego e-maila, gdy wszystkie wyniki
laboratoryjne będą ostateczne. Puste, gdy wyłączone. Zobacz
[E-maile o gotowych wynikach](https://docs.anivahealth.com/pl/concepts/results.md#e-maile-o-gotowosci-wynikow).

**draw\_method** `string` *required*

Sposób pobrania krwi: `capillary` (z opuszka palca lub ramienia, do mikroprobówek) lub `venous` (z żyły,
do probówek). Jest to metoda ustawiona dla wizyty, a w przeciwnym razie `default_draw_method` jej
[lokalizacji](https://docs.anivahealth.com/pl/concepts/locations.md). Po pobraniu krwi jest to metoda, której użyto.

**created\_at** `string` *required*

Znacznik czasu ISO 8601 utworzenia wizyty.

**updated\_at** `string`

Znacznik czasu ostatniej aktualizacji w formacie ISO 8601. Wartość null, jeśli wizyta nigdy nie była aktualizowana.

**lab\_codes** `string[]` *required*

Kody laboratoryjne (kody kreskowe probówek) zapisane w [Potwierdź pobranie krwi](https://docs.anivahealth.com/pl/api/appointments/confirm-blood-draw.md),
w kolejności skanowania. Puste do czasu potwierdzenia pobrania krwi. Pobranie żylne ma jeden kod
wydrukowany na każdej probówce; pobranie kapilarne ma jeden kod na mikroprobówkę. Wyniki i dokumenty
odwołują się do nich przez `lab_code`.

**panels** `object[]` *required*

Panele przypisane do tej wizyty jako wpisy `{ panel_id, added_at }`. Zobacz
[Dodawanie paneli](#dodawanie-paneli).

**individual\_biomarkers** `object[]` *required*

Pojedyncze biomarkery przypisane do tej wizyty jako wpisy `{ biomarker_id, added_at }`. Zobacz
[Pojedyncze biomarkery](#pojedyncze-biomarkery).

**shipments** `object[]` *required*

Przesyłki powiązane z tą wizytą jako wpisy `{ id, added_at }`, od najstarszego powiązania. Zobacz
[Łączenie przesyłek](#laczenie-przesylek).

**profile** `object` *required*

Pełny obiekt profilu pacjenta, osadzony w każdej odpowiedzi dotyczącej wizyty. Poniższe pola
stanowią jego część. [Pobierz wizytę](https://docs.anivahealth.com/pl/api/appointments/get-appointment.md) zawiera ich pełną listę.

**właściwości**

**id** `string`

UUID powiązanego profilu.

**first\_name** `string`

Imię pacjenta.

**last\_name** `string`

Nazwisko pacjenta.

**email** `string`

Adres e-mail pacjenta.

**date\_of\_birth** `string`

Data urodzenia w formacie `YYYY-MM-DD`.

**sex** `integer`

Płeć biologiczna według ISO/IEC 5218.

## Cykl życia

Wizyty mają cztery stany cyklu życia:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Status | Znaczenie |
| - | - |
| `pending` | Wizyta jest zaplanowana i czeka na potwierdzenie. Można ją [zaktualizować](https://docs.anivahealth.com/pl/api/appointments/update-appointment.md) lub [anulować](https://docs.anivahealth.com/pl/api/appointments/cancel-appointment.md). |
| `confirmed` | Termin został potwierdzony (np. przez gabinet), ale krew nie została jeszcze pobrana. Wizytę nadal można zaktualizować lub anulować. |
| `blood_drawn` | Kody laboratoryjne zostały przesłane przez [Potwierdź pobranie krwi](https://docs.anivahealth.com/pl/api/appointments/confirm-blood-draw.md) i uruchomiono proces zlecenia laboratoryjnego. Panele są zablokowane, a wizyty nie można przełożyć ani anulować. |
| `cancelled` | Wizyta została anulowana. Stan końcowy — brak dalszych przejść. |

> [!NOTE]
>
> Status wizyty jest celowo ogólny — bardziej szczegółowy postęp jest dostępny
> przez dedykowane endpointy:
>
> * **Realizacja wyników laboratoryjnych** →
>   [Pobierz wyniki](https://docs.anivahealth.com/pl/api/appointments/get-results.md) — główne pole `status` ma wartość `in_progress` lub
>   `completed`.
> * **Postęp przesyłki** (w drodze, dostarczona itp.) → przejdź z każdego wpisu w osadzonej
>   tablicy `shipments` w wizycie do [Pobierz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md) — każda
>   przesyłka ma własny `status` oraz dziennik zdarzeń `status_updates`.
>
> Każda zmiana statusu wysyła [webhook](https://docs.anivahealth.com/pl/concepts/webhooks.md) `appointment.*`, na przykład
> `appointment.confirmed`. Nowy termin lub lokalizacja wysyła `appointment.rescheduled`.

> [!WARNING]
>
> Potwierdzenie wizyty (zmiana jej statusu na `blood_drawn`) jest **nieodwracalne**. Po przesłaniu
> kodu lub kodów laboratoryjnych uruchamiany jest proces zlecenia laboratoryjnego i nie można go cofnąć. Aktualizacje i anulowania
> są dozwolone tylko wtedy, gdy wizyta ma status `pending` lub `confirmed`.

## Lista wizyt

Pobierz wszystkie wizyty dostępne dla twojego klucza API:

```
GET /api/v1/appointments
```

Opcjonalnie przekaż `?profile_id={uuid}`, aby filtrować według konkretnego profilu. Bez tego parametru stosowane jest domyślne okno czasowe (od 2 miesięcy wstecz do 1 miesiąca w przód).

## Aktualizacja wizyty

Przed potwierdzeniem pobrania krwi możesz zmienić termin lub punkt pobrań:

```
PATCH /api/v1/appointments/{id}
```

Przekaż dowolną kombinację pól `scheduled_at`, `location_id`, `draw_method` i `results_ready_emails`, aby zaktualizować wizytę. Uwzględnij tylko te pola, które chcesz zmienić.

## Metoda pobrania krwi

Każda wizyta ma pole `draw_method`: `capillary` (z opuszka palca lub ramienia, do mikroprobówek) albo
`venous` (z żyły, do probówek). Dotyczy to wyłącznie pobrania krwi. Mocz, wymazy i pozostałe
próbki inne niż krew pobiera się tak samo przy obu metodach.

Domyślnie jest to `default_draw_method` danej lokalizacji. Ustaw `draw_method` przy tworzeniu lub aktualizacji,
aby użyć innej metody, albo ustaw `null`, aby wrócić do wartości domyślnej lokalizacji. Lokalizacja musi mieć
tę metodę na swojej liście `draw_methods`, a zarezerwowane badania muszą być z nią możliwe, w przeciwnym razie
żądanie zwróci `400`. Po pobraniu krwi nie możesz jej zmienić. Po pobraniu krwi `draw_method` to
metoda, której użyto.

## Jedna wizyta na profil, lokalizację i termin

Profil może mieć najwyżej jedną nieanulowaną wizytę na parę `(location_id, scheduled_at)` — jednej
osobie nie można pobrać krwi dwa razy w tym samym miejscu i czasie, niezależnie od tego, ile równoległych rezerwacji
przyjmuje lokalizacja.

Zarówno [Utwórz wizytę](https://docs.anivahealth.com/pl/api/appointments/create-appointment.md), jak i
[Zaktualizuj wizytę](https://docs.anivahealth.com/pl/api/appointments/update-appointment.md) egzekwują tę zasadę, zwracając `409` z polem
`appointment_id` wskazującym na istniejącą już wizytę. Traktuj tę odpowiedź jako informację, że wizyta jest już
zarezerwowana, a nie jako błąd do ponowienia: pobierz, przełóż lub anuluj wskazaną wizytę.

W praktyce oznacza to, że powtórne żądania utworzenia są bezpieczne. Żądanie utworzenia wysłane ponownie po przekroczeniu limitu czasu sieci
lub wywołane dwukrotnie przez użytkownika prowadzi do jednej wizyty zamiast dwóch — dzięki temu
nigdy nie musisz później porządkować zduplikowanych rezerwacji dla tego samego pacjenta.

> [!NOTE]
>
> Aktualizacje są dozwolone tylko przed pobraniem krwi — tj. gdy wizyta ma status `pending` lub
> `confirmed`. Gdy wizyta przejdzie do statusu `blood_drawn` lub ma status `cancelled`, nie można jej
> modyfikować. Jedynym wyjątkiem jest `results_ready_emails`: nadal możesz zmienić samo to pole po
> pobraniu krwi.

## Anulowanie wizyty

Anuluj wizytę, która nie jest już potrzebna:

```
DELETE /api/v1/appointments/{id}
```

Ustawia to status wizyty na `cancelled`. Anulowana wizyta jest zwracana w odpowiedzi.

Opcjonalnie wyślij `cancellation_reason` (do 500 znaków) w treści żądania, aby zapisać powód. Zostanie on
zapisany przy wizycie i zwracany jako `cancellation_reason` przy kolejnych odczytach.

> [!NOTE]
>
> Anulowanie jest dozwolone tylko przed pobraniem krwi — tj. gdy wizyta ma status `pending` lub
> `confirmed`. Wizyt, które przeszły już do statusu `blood_drawn`, nie można anulować.

## Dodawanie paneli

Przed potwierdzeniem pobrania krwi dodaj panele badań krwi, które chcesz wykonać, wywołując:

```
POST /api/v1/appointments/{id}/panels
```

Przekaż tablicę identyfikatorów UUID paneli w polu `panel_ids`. Identyfikatory paneli dostarcza Aniva dla twojego konta partnerskiego.

> [!NOTE]
>
> Panele trzeba dodać przed pobraniem krwi — tj. gdy wizyta ma status `pending` lub
> `confirmed`. Nie możesz dodawać ani zmieniać paneli, gdy wizyta przejdzie do statusu
> `blood_drawn`.

## Usuwanie paneli

Jeśli musisz usunąć panele przed pobraniem krwi, wywołaj:

```
DELETE /api/v1/appointments/{id}/panels
```

Przekaż tablicę identyfikatorów UUID paneli w polu `panel_ids`. Usuwanie jest idempotentne: panel, który nie jest przypisany, jest pomijany.

> [!NOTE]
>
> Podobnie jak dodawanie paneli, usuwanie jest dozwolone tylko przed pobraniem krwi — tj. gdy wizyta
> ma status `pending` lub `confirmed`. Paneli nie można usunąć, gdy wizyta przejdzie do statusu
> `blood_drawn`.

## Pojedyncze biomarkery

Możesz przypisać do wizyty pojedyncze biomarkery jako badania dobierane indywidualnie, poza gotowym panelem. Przydaje się to, gdy specjalista chce dopasowanego zestawu zamiast gotowego pakietu. Przypisane biomarkery pojawiają się w odpowiedzi dla wizyty jako tablica `individual_biomarkers` (obok `panels`). Decyzje o kierowaniu zleceń zapadają dalej w potoku logistyki zleceń na podstawie mapowań każdego biomarkera w poszczególnych laboratoriach.

Dodaj biomarkery (operacja idempotentna — już przypisane biomarkery zostają zachowane):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Usuń biomarkery (operacja idempotentna — biomarkery, które nie są przypisane, są pomijane):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

Oba endpointy przyjmują tablicę `biomarker_ids` i sprawdzają wynikowy zestaw pod kątem reguł domknięcia każdego laboratorium — zlecenie, którego nie da się poprawnie złożyć (np. wskaźnik CRP/HDL bez CRP i HDL), zwraca `400` z biomarkerami, które musisz dodać, i niczego nie zapisuje. Użyj [Wyświetl biomarkery](https://docs.anivahealth.com/pl/api/biomarkers/list-biomarkers.md), aby znaleźć identyfikatory biomarkerów.

> [!NOTE]
>
> Podobnie jak w przypadku zmian w panelach, pojedyncze biomarkery można dodawać lub usuwać tylko przed pobraniem krwi
> — tj. gdy wizyta ma status `pending` lub `confirmed`. Gdy wizyta przejdzie do statusu
> `blood_drawn`, niestandardowa migawka zostaje zamrożona.

## Podgląd wymaganych pojemników

Po dodaniu paneli lub pojedynczych biomarkerów wyświetl podgląd fizycznych pojemników na materiał, które będą potrzebne do pobrania próbki:

```
GET /api/v1/appointments/{id}/preview
```

Tablica `containers` w odpowiedzi zawiera typ, nazwę, kolor korka, objętość, numer katalogowy producenta i liczbę każdego wymaganego pojemnika. Pomaga to specjalistom przygotować odpowiednie materiały przed pobraniem krwi. Odpowiedź zawiera też obiekt `pricing` — pełne rozliczenie koszyka wizyty (naliczone pozycje, przypisane panele oraz po jednym wierszu na każdy dostarczony biomarker, wycenione według twojego cennika, z ceną detaliczną obok; zobacz [Cennik](https://docs.anivahealth.com/pl/concepts/pricing.md)), wypełniony, gdy wizyta ma przypisane badania, a twój klucz ma zakres `prices_view`, w przeciwnym razie `null`. `routing` celowo nigdy nie jest udostępniane i zawsze ma wartość `null`.

> [!NOTE]
>
> Podgląd odzwierciedla aktualnie przypisane panele i biomarkery. Jeśli dodasz lub usuniesz panele
> po wywołaniu podglądu, wywołaj ten endpoint ponownie, aby pobrać zaktualizowane wymagania dotyczące pojemników.

## Potwierdzanie pobrania krwi

Po pobraniu krwi prześlij kody laboratoryjne (kody kreskowe probówek), aby uruchomić potok zleceń laboratoryjnych:

```
POST /api/v1/appointments/{id}/confirm
```

Wyślij `lab_code`, gdy jeden kod jest wydrukowany na każdej probówce (pobranie żylne), lub `lab_codes` z jednym wpisem
na kod — każdy z `panel_ids`, które obejmuje — gdy każdy panel jest pobierany do własnych probówek z
własnym kodem (pobranie włośniczkowe). Każdy panel jest wtedy osobnym zleceniem laboratoryjnym pod swoim kodem. Kody
są zwracane jako `lab_codes` przy wizycie.

Podczas pobrania włośniczkowego pobrana krew trafia do mikroprobówek. Najpierw umieszczane są panele, w kolejności rezerwacji. Pojedyncze
biomarkery wypełniają następnie wolne miejsce w mikroprobówkach paneli. Gdy potrzebują więcej miejsca, otwierają
nowe mikroprobówki. Rozkładamy je równomiernie. Każda mikroprobówka mieści maksymalnie 150 µl pojedynczych
biomarkerów. Wywołania zmieniające panele lub biomarkery zwracają `400`, gdy wynikowy zestaw narusza
tę regułę.

Zmienia to status wizyty na `blood_drawn` i uruchamia przetwarzanie w laboratorium. Ta operacja jest nieodwracalna.

## Odbiór przesyłki

> [!WARNING]
>
> `POST /api/v1/appointments/pickup` został **usunięty** wraz ze statusem wizyty
> `shipment_picked_up`. Zwraca teraz `405 Method Not Allowed`, ponieważ ścieżka przechodzi do
> trasy wizyty według ID. W ostatniej fazie endpoint ten działał jako no-op — przyjmował wywołanie i
> nic nie robił, więc jego usunięcie nie zmienia żadnego zachowania, na którym polegasz.

Aby śledzić postęp po pobraniu krwi, przejdź dla każdego wpisu w osadzonej tablicy `shipments` wizyty
do [Pobierz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md) — każda przesyłka ma własny `status`
oraz historię `status_updates`.

## Łączenie przesyłek

Wizyta może być powiązana z jedną lub wieloma przesyłkami (i odwrotnie — relacja jest
typu wiele-do-wielu). Aktualny zestaw powiązań pojawia się bezpośrednio po obu stronach:

* w wizycie, jako tablica `shipments` z wpisami `{ id, added_at }`;
* w przesyłce, jako tablica `appointments` z wpisami `{ id, added_at }`.

Obie tablice są posortowane od najstarszego powiązania. Każde `id` odsyła do kanonicznego endpointu szczegółów
([Pobierz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md) /
[Pobierz wizytę](https://docs.anivahealth.com/pl/api/appointments/get-appointment.md)) w celu pobrania pełnych danych.

Przesyłki są łączone podczas tworzenia za pomocą pola `appointment_id` w
[Utwórz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/create-shipment.md). Po utworzeniu zarządzaj powiązaniami z poziomu przesyłki
za pomocą [Dołącz wizyty do przesyłki](https://docs.anivahealth.com/pl/api/shipments/attach-appointments-to-shipment.md) oraz
[Odłącz wizyty od przesyłki](https://docs.anivahealth.com/pl/api/shipments/detach-appointments-from-shipment.md); każdy z nich zwraca
listę wizyt dla tej przesyłki po zmianie. Aby odczytać pełne dane paczek wizyty,
użyj [Wyświetl przesyłki](https://docs.anivahealth.com/pl/api/shipments/list-shipments.md) z `?appointment_id=`.

Reguła modyfikacji jest taka: powiązania można tworzyć lub usuwać, gdy ALBO

* wizyta jest już po pobraniu krwi (`blood_drawn`), albo
* przesyłka została utworzona mniej niż 24 godziny temu.

Poza tym oknem powiązanie jest zablokowane, aby zapisy historyczne pozostały niezmienne.

## Pobieranie wyników laboratoryjnych

Gdy laboratorium przetworzy próbki krwi, pobierz wyniki kliniczne i genetyczne:

```
GET /api/v1/appointments/{id}/results
```

Odpowiedź zawiera zaplanowane badania (status `planned`) obok otrzymanych wyników, więc możesz
śledzić, co wciąż oczekuje. Pole `status` na najwyższym poziomie ma wartość `in_progress`, dopóki
wszystkie zlecenia się nie zamkną, a następnie `completed` (lub `fault`, gdy żadne nie zwróciło
wyników) — użyj go, aby ustalić, czy badania laboratoryjne z wizyty zostały zakończone.
[Webhook](https://docs.anivahealth.com/pl/concepts/webhooks.md) `appointment.results.completed` informuje cię, gdy to nastąpi, więc
nie musisz cyklicznie odpytywać. Tablica `submissions` rozbija to na poszczególne zlecenia
laboratoryjne, każde z własnym `lab_code`. Każdy otrzymany wynik i dokument zawiera `lab_code`,
pod którym został zarejestrowany. Odwołania do plików PDF z raportami laboratoryjnymi znajdują się
w tablicy `documents` — użyj `GET /api/v1/documents/{id}`, aby je pobrać.

## Przykładowa wizyta

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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