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

# Zamówienia domowych zestawów testowych

> Jak działają zamówienia domowych zestawów testowych w API Aniva: zamawianie zestawu wysyłkowego, wysyłka, odesłanie próbki i wyniki laboratoryjne.

**Zamówienie domowego zestawu testowego** polega na wysłaniu do pacjenta pocztowego zestawu testowego do samodzielnego wykonania. Aniva wysyła zestaw, pacjent samodzielnie pobiera próbkę w domu i odsyła ją pocztą. Różni się to od [wizyty](https://docs.anivahealth.com/pl/concepts/appointments.md), która oznacza pobranie krwi żylnej w stacjonarnym punkcie badań przez pracownika medycznego.

> [!NOTE]
>
> Endpointy zamówień domowych zestawów testowych wymagają zakresu `home_kit_orders_view` (odczyt)
> lub `home_kit_orders_manage` (zapis). [Aktywuj](https://docs.anivahealth.com/pl/api/home-kit-orders/activate-home-kit.md) akceptuje
> również węższy zakres `home_kit_orders_activate`. [Pobierz wyniki](https://docs.anivahealth.com/pl/api/home-kit-orders/get-results.md)
> i [Wyślij wyniki e-mailem](https://docs.anivahealth.com/pl/api/home-kit-orders/email-results.md) wymagają dodatkowo `results_view` —
> dostęp do wyników laboratoryjnych i dokumentów zawsze jest nim chroniony.

## Pola

**id** `string` *required*

UUID wygenerowany automatycznie przez Aniva. Użyj go, aby zaktualizować zamówienie, zmienić jego
panel, aktywować je, anulować oraz pobrać wyniki.

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

UUID profilu, do którego należy to zamówienie domowego zestawu testowego.

**status** `string` *required*

Bieżący status cyklu życia. Jedna z wartości: `pending`, `dispatched`, `activated` lub `cancelled`.
Zobacz [Cykl życia](#cykl-zycia) poniżej. Szczegółowy stan kompletności wyników laboratoryjnych
(`in_progress` lub `completed`) pochodzi z [Pobierz wyniki](https://docs.anivahealth.com/pl/api/home-kit-orders/get-results.md).

**delivery\_address** `object` *required*

Adres wysyłki zestawu — jedna z dwóch form: `{location_id}` wskazujące na znany punkt badań albo
pola adresu podane bezpośrednio (`name`, `street`, `city`, `postal_code`, `country_code`;
opcjonalnie `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` —
takie samo nazewnictwo jak w API lokalizacji). Podaj dokładnie jedną formę — odwołanie do
lokalizacji albo adres podany bezpośrednio, nie obie naraz.

**adres dostawy**

> [tab] Odwołanie do lokalizacji
>
> **location\_id** `string` *required*
>
> UUID punktu badań, do którego wysyłany jest zestaw.

> [tab] Adres podany bezpośrednio
>
> **name** `string` *required*
>
> Nazwa odbiorcy, firmy lub lokalizacji.
>
> **company\_name** `string`
>
> Firma odbierająca przesyłkę dla odbiorcy — podmiot `c/o` lub dział.
>
> **street** `string` *required*
>
> Nazwa ulicy bez numeru domu (np. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Numer domu (np. `118` lub `12a`).
>
> **address\_line\_2** `string`
>
> Budynek, wejście lub piętro.
>
> **city** `string` *required*
>
> **state** `string`
>
> Stan lub województwo. Opcjonalne.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Kod ISO 3166-1 alpha-2 (dwie litery, np. `DE`).
>
> **phone** `string`
>
> Numer telefonu odbiorcy. Przewoźnik otrzymuje go, aby informować odbiorcę o przesyłce.
>
> **email** `string`
>
> Adres e-mail odbiorcy. Przewoźnik otrzymuje go, aby informować odbiorcę o przesyłce.

> [!NOTE]
>
> **Packstation lub Postfiliale (tylko Niemcy):** ustaw `street` na `Packstation` lub `Postfiliale`,
> `house_number` na trzycyfrowy numer punktu, a `address_line_2` na numer DHL Postnummer odbiorcy
> (6–10 cyfr, dozwolone spacje). Bez numeru Postnummer nie można nadać przesyłki. Skrytka
> Postfach nie jest obsługiwana.

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

Znacznik czasu ISO 8601 utworzenia zamówienia domowego zestawu testowego.

**updated\_at** `string`

Znacznik czasu ISO 8601 ostatniej aktualizacji. Null, jeśli zamówienie domowego zestawu testowego nigdy nie było aktualizowane.

**profile** `object`

Pełny obiekt profilu pacjenta, osadzony w każdej odpowiedzi zamówienia domowego zestawu testowego.

**właściwości**

**id** `string`

UUID powiązanego profilu.

**handle** `string`

Identyfikator profilu lub nazwa użytkownika. Może mieć wartość `null`.

**first\_name** `string`

Imię pacjenta. Może mieć wartość `null`.

**last\_name** `string`

Nazwisko pacjenta. Może mieć wartość `null`.

**email** `string`

Adres e-mail pacjenta. Może mieć wartość `null`.

**phone** `string`

Numer telefonu w formacie E.164. Może mieć wartość `null`.

**sex** `integer`

Płeć biologiczna według ISO/IEC 5218. Może mieć wartość `null`.

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

Data urodzenia w formacie `YYYY-MM-DD`. Może mieć wartość `null`.

**height** `number`

Wzrost w centymetrach. Może mieć wartość `null`.

**weight** `number`

Waga w kilogramach. Może mieć wartość `null`.

**language** `string`

Preferowany język: jeden z 32 kodów w [Utwórz profil](https://docs.anivahealth.com/pl/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Czy ten profil otrzymuje wiadomości e-mail transakcyjne (automatyczne). Może mieć wartość `null`.

**created\_at** `string`

Znacznik czasu ISO 8601 utworzenia profilu.

**updated\_at** `string`

Znacznik czasu ISO 8601 ostatniej aktualizacji profilu. Może mieć wartość `null`.

**panels** `object[]`

Panel przypisany do zamówienia domowego zestawu testowego — zawsze dokładnie jeden wpis
`{ panel_id, added_at }`, ponieważ domowy zestaw testowy odpowiada w relacji 1:1 fizycznemu
zestawowi. Sprawdź `panel_id` w [Wyświetl panele](https://docs.anivahealth.com/pl/api/panels/list-panels.md).

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

Biomarkery przypisane do zamówienia domowego zestawu testowego poza jego panelem. Każdy wpis ma
postać `{ biomarker_id, added_at }`. Sprawdź każde `biomarker_id` w
[Wyświetl biomarkery](https://docs.anivahealth.com/pl/api/biomarkers/list-biomarkers.md) z `home_kit=true`. W zwykłym zamówieniu są
to dodatkowe badania wybrane poza panelem, a w przypadku [zestawu zastępczego](#zestawy-zastepcze)
— badania, które laboratorium powtarza.

**replaces\_home\_kit\_order\_id** `string`

Zamówienie domowego zestawu testowego, które to zamówienie zastępuje, gdy jest to
[zestaw zastępczy](#zestawy-zastepcze). `null` w zwykłym zamówieniu.

**replacement\_reason** `string`

Powód wysłania zestawu zastępczego w jednym zdaniu. `null` w zwykłym zamówieniu.

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

Adresy zapisane małymi literami, z których każdy otrzymuje jeden e-mail, gdy wszystkie wyniki
laboratoryjne są ostateczne. Zawsze obecne — puste, gdy funkcja jest wyłączona. Ustaw je w
[Utwórz](https://docs.anivahealth.com/pl/api/home-kit-orders/create-home-kit.md) lub
[Zaktualizuj](https://docs.anivahealth.com/pl/api/home-kit-orders/update-home-kit.md). Zobacz
[E-maile o gotowych wynikach](https://docs.anivahealth.com/pl/concepts/results.md#e-maile-o-gotowosci-wynikow).

**metadata** `object`

Twoje własne pary klucz/wartość, zwracane bez zmian i nigdy nieinterpretowane przez Aniva. Zawsze
obecne przy odczycie — `{}`, gdy nic nie ustawisz. Maksymalnie 20 kluczy; klucze pasują do
`[A-Za-z0-9_-]` i mają maksymalnie 40 znaków; wartości to ciąg znaków, liczba lub wartość logiczna,
przy czym ciągi znaków mają maksymalnie 500 znaków; łącznie 16 384 bajty po serializacji. Klucze
zaczynające się od `aniva_` są zarezerwowane. W [Zaktualizuj](https://docs.anivahealth.com/pl/api/home-kit-orders/update-home-kit.md)
metadane są **łączone**: pominięte klucze pozostają bez zmian, klucz wysłany jako `null` zostaje
usunięty, a `{}` czyści wszystko. Walidacja działa na zasadzie wszystko albo nic. Nigdy nie
umieszczaj danych osobowych ani klinicznych w `metadata` — to pole nie jest traktowane jak dane
pacjenta.

**lab\_code** `string`

Kod próbki laboratoryjnej. Jeden kod, trzy role: identyfikator, pod którym raportowane są wyniki
laboratoryjne, kod wydrukowany na fizycznym zestawie oraz kod aktywacyjny, który pacjent odczytuje
z pudełka. Przydzielany podczas pakowania zestawu — `null`, dopóki zamówienie ma status `pending`,
z wyjątkiem sytuacji po ponownej wysyłce zestawu przez Aniva (zobacz [Cykl życia](#cykl-zycia)).
Zawsze tylko do odczytu. Dopasuj fizyczny zestaw do jego zamówienia za pomocą
`GET /api/v1/home-kit-orders?lab_code=…`.

**activated\_at** `string`

Znacznik czasu pobrania zgłoszony przez [Aktywuj](https://docs.anivahealth.com/pl/api/home-kit-orders/activate-home-kit.md) —
moment faktycznego pobrania próbki przez pacjenta w czasie UTC. `null`, dopóki zestaw nie zostanie
aktywowany. Ten czas pobrania widnieje na raporcie laboratoryjnym.

**shipments** `object[]`

Przesyłki powiązane z tym zamówieniem, od najstarszej, każda w formacie `{ id, added_at }` —
zestaw w drodze do pacjenta oraz, dla zestawów ze śledzoną przesyłką zwrotną, próbka w drodze
z powrotem do laboratorium; pojawiają się w momencie wydrukowania etykiet. Puste, dopóki
zamówienie ma status `pending`, z wyjątkiem sytuacji po ponownej wysyłce zestawu przez Aniva.
Pobierz pełne dane przesyłek jednym wywołaniem `GET /api/v1/shipments?home_kit_order_id={id}` —
zobacz [Przesyłki](https://docs.anivahealth.com/pl/concepts/shipments.md).

## Cykl życia

Zamówienia domowych zestawów testowych mają cztery stany cyklu życia:

```
pending → dispatched → activated
   │          │
   │          ├──→ pending    (Aniva re-ships a lost kit)
   │          └──→ cancelled  (Aniva: the box came back undelivered)
   │
   └──→ cancelled
```

| Status | Znaczenie |
| - | - |
| `pending` | Zamówienie zostało utworzone, ale zestaw nie został jeszcze spakowany. Można je [zaktualizować](https://docs.anivahealth.com/pl/api/home-kit-orders/update-home-kit.md) (adres, zmiana panelu, metadane) lub [anulować](https://docs.anivahealth.com/pl/api/home-kit-orders/cancel-home-kit.md). |
| `dispatched` | Zestaw jest spakowany i oklejony etykietą — jest w drodze do pacjenta (lub już u niego). Skład jego panelu i biomarkerów jest teraz **zablokowany** i nie możesz już go [anulować](https://docs.anivahealth.com/pl/api/home-kit-orders/cancel-home-kit.md). Aniva może jeszcze zmienić jego status: z powrotem na `pending`, gdy zestaw zaginie i Aniva wyśle nowy, albo na `cancelled`, gdy paczka wróci jako niedoręczona i nie zostanie wysłana ponownie. |
| `activated` | Pacjent pobrał próbkę, co zostało zgłoszone przez [Aktywuj](https://docs.anivahealth.com/pl/api/home-kit-orders/activate-home-kit.md) ze znacznikiem czasu pobrania. Zlecenie laboratoryjne jest składane pod kodem `lab_code` zestawu. Status końcowy — analogicznie do `blood_drawn` dla wizyty. |
| `cancelled` | Zamówienie domowego zestawu testowego zostało anulowane: przez ciebie ze statusu `pending` albo przez Aniva ze statusu `dispatched`, gdy paczka wróciła jako niedoręczona. Status końcowy — bez dalszych zmian, a ponowne anulowanie nic nie zmienia i zwraca zamówienie. |

Gdy Aniva ponownie wysyła zagubiony zestaw, zamówienie wraca do statusu `pending`, ale zachowuje swój `lab_code` oraz
wcześniejsze paczki w `shipments`. Nowy zestaw ma ten sam kod. Do nowego pudełka trafia
nieużyta etykieta zwrotna. Tylko Aniva wykonuje te dwie zmiany; API ich nie udostępnia. Każda z nich wysyła
[webhook](https://docs.anivahealth.com/pl/concepts/webhooks.md) `home_kit_order.pending` lub `home_kit_order.cancelled`.

> [!NOTE]
>
> Statusy zamówienia domowego zestawu testowego są celowo ogólne. Przebieg dostawy do pacjenta i od
> niego śledzisz w [przesyłkach](https://docs.anivahealth.com/pl/concepts/shipments.md) zamówienia — `dispatched` oznacza, że zestaw
> ma etykietę i kod laboratoryjny, a nie że już wyruszył; o tym mówi `status` przesyłki wychodzącej.
> Przetwarzanie wyników w laboratorium odbywa się w ramach zgłoszeń. Stan gotowości wyników (`in_progress`
> lub `completed`) udostępnia [Pobierz wyniki](https://docs.anivahealth.com/pl/api/home-kit-orders/get-results.md) — główne pole
> `status` ma wartość `in_progress`, dopóki wszystkie zgłoszenia nie zostaną zamknięte, a następnie
> `completed` — albo `fault`, gdy wszystkie zgłoszenia zakończyły się bez raportu.

## Śledzenie paczek

```
GET /api/v1/shipments?home_kit_order_id={id}
```

To, co wraca w odpowiedzi, zależy od zestawu. Po spakowaniu przez Aniva zestaw do badania krwi pojawia się jako dwie przesyłki:
paczka od Aniva do pacjenta oraz paczka od
pacjenta do laboratorium (jej `destination` to laboratorium), powiązane przez `paired_with`. Paczka
zwrotna ma status `pending` — z już znanym numerem śledzenia — dopóki pacjent jej nie
nada. Zestaw do badania mikrobiomu jelitowego pojawia się jako jedna przesyłka: zestaw do pacjenta. Jego koperta zwrotna jest
opłacona z góry i nie ma śledzenia, więc na drogę powrotną nic nie jest rejestrowane. Pole `booked_by` mówi, kto zamówił
etykietę: `"aniva"` lub `"external"`. Zmieniać można tutaj tylko paczkę `"aniva"`, a po wydrukowaniu etykiety wyłącznie jej
`notes`. Każda paczka zawiera pełną listę `status_updates` przewoźnika,
w tym `detail_code` firmy DHL dla przekierowania na pocztę.

Pole `home_kit_orders` w przesyłce zawiera tylko zamówienia z twojego kontekstu dostępu. Zobacz
[Dostęp](https://docs.anivahealth.com/pl/concepts/shipments.md#dostep).

> [!WARNING]
>
> Skład zamówienia domowego zestawu testowego można zmieniać tylko w statusie `pending`. Gdy zamówienie ma status
> `dispatched` (lub późniejszy — `activated`/`cancelled`), zmiana panelu i endpointy `/biomarkers`
> zwracają `409 Conflict`: fizyczny zestaw jest pakowany na podstawie wybranego panelu, więc jego zawartość jest
> zamrożona w chwili wysyłki do pacjenta. Jeśli musisz zmienić badania w zamówieniu, które jest
> już zablokowane, skontaktuj się bezpośrednio z Aniva — zwykle jest to nadal możliwe i wprowadzimy
> zmianę za ciebie, aby zachować spójność zawartości zestawu. Jeśli zestaw został już użyty i nie mógł
> dostarczyć wyników, zamów zamiast tego [zestaw zastępczy](#zestawy-zastepcze).

## Lista zamówień domowych zestawów testowych

Pobierz wszystkie zamówienia domowych zestawów testowych dostępne dla twojego klucza API:

```
GET /api/v1/home-kit-orders
```

Opcjonalnie przekaż `?profile_id={uuid}`, aby filtrować po konkretnym profilu, lub `?lab_code={code}`, aby
powiązać fizyczny zestaw z jego zamówieniem — to naturalny pierwszy krok procesu aktywacji.

## Tworzenie zamówienia domowego zestawu testowego

Złóż zamówienie domowego zestawu testowego dla profilu pacjenta:

```
POST /api/v1/home-kit-orders
```

Przekaż `profile_id`, `delivery_address` oraz pojedyncze `panel_id`. Zamówienie powstaje ze statusem `pending`.

Przekaż opcjonalny nagłówek `Idempotency-Key`, aby ponowienie żądania nie zamówiło drugiego zestawu — zobacz [Idempotentność](https://docs.anivahealth.com/pl/concepts/idempotency.md).

Dokładnie jeden panel, ponieważ domowy zestaw testowy odpowiada 1:1 fizycznemu produktowi — panel to zestaw. Zamówić można tylko panele skonfigurowane przez Aniva jako domowe zestawy testowe; każdy inny panel zostanie odrzucony z kodem `422`. Jest wymagany przy tworzeniu, ponieważ zamówienie od razu trafia do kolejki pakowania i pakowanie może ruszyć natychmiast. Dopóki zamówienie ma status `pending`, możesz zmienić panel przez [Aktualizuj](https://docs.anivahealth.com/pl/api/home-kit-orders/update-home-kit.md).

Aby wysłać drugi zestaw w miejsce tego, który nie mógł dostarczyć wyników, przekaż `replaces_home_kit_order_id` zamiast wybierać panel — zobacz [Zestawy zastępcze](#zestawy-zastepcze).

## Zestawy zastępcze

Czasem zestaw nie może dostarczyć wyników: pacjent nie zdołał napełnić probówki, w próbce było za mało materiału, laboratorium nie mogło przeanalizować części badania. Zamów dla niego **zestaw zastępczy**:

```
POST /api/v1/home-kit-orders
{
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delivery_address": { "...": "..." },
  "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "replacement_reason": "Too little material, HbA1c could not be analysed",
  "biomarker_ids": [103]
}
```

Zestaw zastępczy to **nowe zamówienie z nowym kodem laboratoryjnym**, nawet jeśli pierwszy zestaw nigdy nie został aktywowany: laboratorium potrzebuje nowego zlecenia, a dwóch próbek pod jednym kodem nie da się rozróżnić. Oba zamówienia pozostają dostępne do odczytu i są powiązane przez `replaces_home_kit_order_id`.

**Zastępowane zamówienie pozostaje bez zmian.** Zachowuje swój status, kod laboratoryjny oraz wszystkie już zapisane wyniki, więc pacjent, który mimo wszystko wyśle pierwszy zestaw, otrzyma wszystko, co laboratorium zdoła z niego odczytać.

**Panel jest dziedziczony.** Pomiń `panel_id`, a zestaw zastępczy przejmie panel z zastępowanego zamówienia — to kupił pacjent i taki branding ma pudełko. Przekaż inny panel tylko przy wymianie całego panelu; podanie panelu razem z podzbiorem markerów zostanie odrzucone z kodem `422`, ponieważ podzbiór ma znaczenie tylko w ramach panelu, z którego pochodzi. Panelu zestawu zastępczego nie można też później zmienić.

**To ty wybierasz, co powtórzyć.** Przekaż `biomarker_ids` z markerami, które się nie udały, a laboratorium powtórzy tylko je, dzięki czemu zestaw zawiera wyłącznie potrzebne probówki. Pomiń to pole, aby powtórzyć cały panel — to właściwy wybór, gdy nic nie udało się przeanalizować. Nie wymaga to dodatkowego scope'u: powtórzenie markerów, za które pacjent już zapłacił, nie jest wyborem à la carte. Tych markerów nie można później usunąć, ponieważ stanowią całe zlecenie.

> [!NOTE]
>
> Markery są powtarzane w ramach **grup** panelu, a nie pojedynczo. Wskazanie jednego markera z grupy powtarza
> całą tę grupę, ponieważ nie można złożyć zlecenia laboratoryjnego, które raportuje więcej, niż zamówiono.
> Zestaw zastępczy dla pojedynczego markera może więc wrócić z więcej niż jednym wynikiem, a
> liczba probówek może być większa, niż sugeruje lista markerów.

W drodze może być jednocześnie tylko jeden zestaw zastępczy na zestaw — dopóki zestaw zastępczy ma status `pending` lub `dispatched`, kolejna próba utworzenia dla tego samego zamówienia zwraca `409` ze wskazaniem istniejącego zestawu. Wyniki spływają pod własnym `lab_code` zestawu zastępczego, przez jego własny [Pobierz wyniki](https://docs.anivahealth.com/pl/api/home-kit-orders/get-results.md).

Zestaw zastępczy nie służy do obsługi paczki, która nigdy nie dotarła. Zamiast tego daj znać Aniva: to ponowna wysyłka tego samego zamówienia pod tym samym kodem laboratoryjnym, a nie nowe zamówienie.

## Aktualizacja zamówienia domowego zestawu testowego

Zmień adres dostawy, zamień panel, zaktualizuj metadane lub zastąp adresy e-mail powiadomień o gotowych wynikach:

```
PATCH /api/v1/home-kit-orders/{id}
```

Przekaż tylko pola, które chcesz zmienić. `panel_id` **zastępuje** przypisany panel — przy dokładnie jednym panelu na zestaw podmiana to jedyna sensowna operacja, dlatego nie ma endpointów dodawania i usuwania panelu. Adres i panel można zmieniać tylko w statusie `pending`; `metadata` można zapisywać przez cały okres życia zamówienia. `results_ready_emails` można zapisywać, dopóki zamówienie nie ma statusu `cancelled`.

## Anulowanie zamówienia domowego zestawu testowego

Anuluj zamówienie domowego zestawu testowego, które nie jest już potrzebne:

```
DELETE /api/v1/home-kit-orders/{id}
```

Ustawia to status zamówienia domowego zestawu testowego na `cancelled`. Anulowane zamówienie domowego zestawu testowego jest zwracane w odpowiedzi.

Anulować można tylko zamówienie ze statusem `pending`. Od statusu `dispatched` zestaw jest już spakowany i oklejony etykietą — nie ma automatycznego cofnięcia — a żądanie zwraca `409`. Jeśli trzeba wstrzymać już wysłany zestaw, skontaktuj się bezpośrednio z Aniva.

Anulowanie zamówienia `pending`, którego zestaw został już zlecony do realizacji w centrum logistycznym, anuluje je także tam, a wywołanie powiedzie się tylko wtedy, gdy centrum logistyczne to zaakceptuje:

* `409` — zestaw został już spakowany i oklejony etykietą, więc nie można go już wycofać, mimo że zamówienie wciąż ma status `pending`.
* `502` — centrum logistyczne odrzuciło anulowanie (błąd zawiera podany powód) lub było nieosiągalne. **Nic się nie zmieniło** — zamówienie nadal jest aktywne i można spróbować anulować je ponownie.

Anulowanie, które zwraca błąd, pozostawia zamówienie bez zmian, więc dopiero `200` potwierdza, że żaden zestaw nie zostanie wysłany.

Anulowanie zamówienia, które ma już status `cancelled`, zwraca to samo `200`, niezależnie od tego, z jakiego statusu zostało anulowane.

## Aktywacja zamówienia domowego zestawu testowego

Gdy pacjent pobierze próbkę, zgłoś to:

```
POST /api/v1/home-kit-orders/{id}/activate
```

Przekaż `activated_at` — moment faktycznego pobrania próbki przez pacjenta jako znacznik czasu UTC. Ten czas pobrania znajdzie się na raporcie laboratoryjnym, więc przekaż rzeczywisty moment pobrania, a nie czas przetworzenia żądania. Aktywacja jest operacją końcową: zamówienie przechodzi w status `activated` i nie można go już anulować ani zmienić. To odpowiednik [Potwierdź pobranie krwi](https://docs.anivahealth.com/pl/api/appointments/confirm-blood-draw.md) dla domowego zestawu testowego, bez kodu kreskowego — kod zestawu jest nanoszony podczas pakowania, więc nigdy nie musisz go znać. Do tego czasu zamówienie musi już mieć `lab_code`; zamówienie bez niego zwraca `409`.

Aktywacja składa także zlecenie laboratoryjne: panel zestawu jest zlecany w laboratorium pod jego `lab_code`, więc laboratorium oczekuje odesłanej próbki i podpina wyniki w miarę ich raportowania. Dzieje się to po wysłaniu odpowiedzi, a ewentualny problem po stronie laboratorium obsługuje Aniva, więc nie pojawi się on w odpowiedzi na twoje żądanie.

## Pojedyncze biomarkery

Do zamówienia domowego zestawu testowego możesz dodać pojedyncze biomarkery jako badania à la carte, poza panelem. Przydaje się to, gdy chcesz dopasować zestaw dodatkowych badań. Dodane biomarkery pojawiają się w odpowiedzi zamówienia domowego zestawu testowego jako tablica `individual_biomarkers` (na tym samym poziomie co `panels`).

Oba endpointy biomarkerów wymagają zakresu uprawnień `home_kit_orders_individual_biomarker_selection` oprócz `home_kit_orders_manage` — domowe zestawy testowe zamawia się według paneli, więc pojedyncze markery są włączane osobno dla każdego partnera. Zapytaj Aniva, jeśli twoja integracja tego potrzebuje.

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

```
PATCH /api/v1/home-kit-orders/{id}/biomarkers
```

Usuń biomarkery (operacja idempotentna — nieprzypisane ID jest ignorowane):

```
DELETE /api/v1/home-kit-orders/{id}/biomarkers
```

Oba endpointy przyjmują tablicę `biomarker_ids`. Użyj [Pobierz listę biomarkerów](https://docs.anivahealth.com/pl/api/biomarkers/list-biomarkers.md) z `home_kit=true`, aby znaleźć ID biomarkerów. Biomarkery można zmieniać tylko wtedy, gdy zestaw ma status `pending` (zobacz [Cykl życia](#cykl-zycia)).

## Pobieranie wyników laboratoryjnych

Gdy laboratorium przetworzy odesłaną próbkę, pobierz wyniki kliniczne i genetyczne:

```
GET /api/v1/home-kit-orders/{id}/results
```

Odpowiedź zawiera zaplanowane badania (status `planned`) obok otrzymanych wyników, więc możesz śledzić, co wciąż oczekuje. Wyniki trafiają pod `lab_code` zamówienia i spływają marker po markerze w miarę ich analizy przez laboratorium, dlatego częściowe odpowiedzi są normalne. Główne pole `status` ma wartość `in_progress` do czasu raportu końcowego, a potem `completed` (lub `fault`, gdy każde zlecenie laboratoryjne zakończyło się błędem bez raportu) — na tej podstawie sprawdzisz, czy analiza laboratoryjna dla zamówienia domowego zestawu testowego jest zakończona. O tym momencie informuje [webhook](https://docs.anivahealth.com/pl/concepts/webhooks.md) `home_kit_order.results.completed`, więc nie musisz odpytywać API. Odniesienia do plików PDF z raportami laboratoryjnymi znajdują się w tablicy `documents` — użyj `GET /api/v1/documents/{id}`, aby je pobrać.

## Przykładowe zamówienie domowego zestawu testowego

```json theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "dispatched",
  "delivery_address": {
    "name": "Jane Doe",
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "jane.doe@example.com"
  },
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-02T08:00:00Z",
  "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": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:30: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"
    }
  ],
  "metadata": { "your_order_ref": "ORD-10482" },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": "7642000123",
  "activated_at": null,
  "shipments": [
    { "id": "K2604021FQ7", "added_at": "2026-04-02T08:00:00Z" },
    { "id": "K260402P3XD", "added_at": "2026-04-02T08:00:00Z" }
  ]
}
```


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