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

# Utwórz zamówienie domowego zestawu testowego

> Zamów wysyłkowy domowy zestaw testowy dla profilu

Złóż zamówienie na domowy zestaw testowy dla profilu pacjenta. Zamówienie domowego zestawu testowego dotyczy zestawu wysyłkowego do samodzielnego użycia — Aniva wysyła zestaw na adres dostawy, pacjent samodzielnie pobiera próbkę w domu i odsyła ją pocztą. Różni się to od [wizyty](https://docs.anivahealth.com/pl/api/appointments/create-appointment.md), która polega na pobraniu krwi z żyły w punkcie pobrań.

**Wymagany jest dokładnie jeden panel.** Domowy zestaw testowy odpowiada w relacji 1:1 fizycznemu produktowi — panel to zestaw — a zamówienie trafia do kolejki pakowania od razu po utworzeniu, więc jego skład musi być ustalony z góry. Nadal możesz zmienić panel przez [Zaktualizuj zamówienie domowego zestawu testowego](https://docs.anivahealth.com/pl/api/home-kit-orders/update-home-kit.md), dopóki zamówienie ma status `pending`.

## Zestawy zastępcze

Gdy zestaw nie może dostarczyć wyników — pacjent nie był w stanie napełnić probówki, próbka dotarła ze zbyt małą ilością materiału lub laboratorium nie mogło jej przeanalizować — zamów **zestaw zastępczy**, wysyłając `replaces_home_kit_order_id`.

Zestaw zastępczy to nowe zamówienie z nowym kodem laboratoryjnym, także wtedy, gdy pierwszy zestaw nigdy nie został aktywowany: laboratorium potrzebuje nowego zlecenia, a dwóch próbek pod jednym kodem nie da się odróżnić. Zastępowane zamówienie pozostaje bez zmian — zachowuje swój status, swój kod laboratoryjny oraz wszelkie wyniki już do niego przypisane.

Wynikają z tego dwie rzeczy:

* **Panel jest dziedziczony.** Pomiń `panel_id`, a zestaw zastępczy przejmie panel z zastępowanego zamówienia, czyli to, co kupił pacjent i jak oznakowane jest pudełko.
* **Wybierasz, co powtórzyć.** Wyślij `biomarker_ids` z markerami, których nie udało się oznaczyć, a laboratorium powtórzy tylko te badania, dzięki czemu zestaw zawiera wyłącznie potrzebne probówki. Pomiń to pole, aby powtórzyć cały panel.

Markery są powtarzane w ramach grup panelu, a nie pojedynczo. Wskazanie jednego markera z grupy powoduje powtórzenie całej tej grupy, ponieważ nie można złożyć zlecenia laboratoryjnego, które raportuje więcej, niż zlecono. Zestaw zastępczy dla jednego markera może więc przynieść więcej niż jeden wynik, a liczba probówek może być większa, niż sugeruje lista markerów.

Jednocześnie dla jednego zestawu może być w drodze tylko jeden zestaw zastępczy.

> [!NOTE]
>
> Jeśli integracja powstała przed wprowadzeniem tych pól, Aniva odczytuje także `metadata.original_kit_id` i
> `metadata.replacement_reason` przy tworzeniu zamówienia i traktuje je jako zestaw zastępczy. To jedyne
> miejsce, w którym metadane są interpretowane — istnieje wyłącznie dla zachowania zgodności z tą wcześniejszą integracją, a powyższe
> pola zawsze mają pierwszeństwo. Wysyłaj te pola.

Kod `201` oznacza, że zamówienie zostało zatwierdzone i trafi do realizacji — nie musisz robić nic więcej, aby zestaw został spakowany i wysłany.

Wymaga zakresu `home_kit_orders_manage`.

Wyślij opcjonalny nagłówek `Idempotency-Key`, aby ponawianie tego żądania utworzenia było bezpieczne — powtórzenie tego samego klucza zwraca pierwotną odpowiedź zamiast tworzyć kolejną wizytę. Zobacz [Idempotentność](https://docs.anivahealth.com/pl/concepts/idempotency.md).

## Żądanie

### Parametry treści

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

UUID profilu pacjenta, dla którego tworzone jest zamówienie domowego zestawu testowego.

**panel\_id** `string` *required*

UUID panelu z katalogu do zamówienia. Dokładnie jeden — domowy zestaw testowy odpowiada w relacji 1:1 fizycznemu produktowi,
więc panel to zestaw. Identyfikatory paneli udostępnia Aniva dla twojego konta partnerskiego; zobacz [Lista
paneli](https://docs.anivahealth.com/pl/api/panels/list-panels.md). Opcjonalne w przypadku zestawu zastępczego — domyślnie przyjmuje panel z
zastępowanego zamówienia.

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

UUID zamówienia domowego zestawu testowego, które to zamówienie zastępuje. Jego wysłanie tworzy zestaw zastępczy — zobacz
[Zestawy zastępcze](#zestawy-zastepcze) powyżej. Zamówienie musi należeć do tego samego profilu i nie może
mieć już zestawu zastępczego w drodze.

**replacement\_reason** `string`

Powód zamówienia zestawu zastępczego w jednym zdaniu (na przykład `Zu wenig Material, HbA1c nicht
    auswertbar`). Wymagane, gdy wysyłasz `replaces_home_kit_order_id`, w przeciwnym razie ignorowane. Maksymalnie
500 znaków.

**biomarker\_ids** `integer[]`

W zestawie zastępczym są to markery, które laboratorium powtarza — zazwyczaj te, których nie udało się uzyskać z pierwszego zestawu.
Każdy musi należeć do zakresu zastępowanego zamówienia; sprawdź w [Lista
biomarkerów](https://docs.anivahealth.com/pl/api/biomarkers/list-biomarkers.md) z parametrem `home_kit=true`. Pomiń, aby powtórzyć cały panel.
Akceptowane wyłącznie razem z `replaces_home_kit_order_id` i nie razem z innym `panel_id`.
Nie wymaga to dodatkowego zakresu uprawnień: powtórzenie markerów, za które pacjent już zapłacił, nie jest wyborem à la carte.

**metadata** `object`

Twoje własne pary klucz/wartość, zwracane bez zmian przy każdym odczycie i nigdy nieinterpretowane przez Aniva. Użyj
tego pola do przekazania własnego numeru referencyjnego zamówienia, aby powiązać dane bez przechowywania naszych ID. Maksymalnie 20 kluczy;
klucze muszą pasować do `[A-Za-z0-9_-]` i mieć maksymalnie 40 znaków; wartości mogą być ciągiem znaków, liczbą lub wartością logiczną,
przy czym ciągi znaków mogą mieć maksymalnie 500 znaków; łącznie maksymalnie 16 384 bajtów po serializacji. Klucze zaczynające się od `aniva_` są
zarezerwowane. Nigdy nie umieszczaj danych osobowych ani klinicznych w `metadata` — to pole nie jest traktowane jak dane pacjenta.

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

Do 5 adresów, z których każdy otrzyma jednego e-maila, gdy wszystkie wyniki laboratoryjne będą
ostateczne. E-mail zawiera link do strony z wynikami w panelu administracyjnym Aniva. Twój klucz
wymaga uprawnienia `results_view` dla tego pacjenta, w przeciwnym razie otrzymasz `403`. Pomiń to
pole, aby użyć domyślnych adresów ustawionych dla grupy pacjenta. Pusta lista wyłącza wysyłanie
e-maili. Zobacz [E-maile o gotowych wynikach](https://docs.anivahealth.com/pl/concepts/results.md#e-maile-o-gotowosci-wynikow).

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

Adres wysyłki zestawu — w jednej z dwóch form: `{ location_id }` wskazujące znany punkt pobrań albo bezpośrednie pola adresu (`name`, `street`, `city`, `postal_code`, `country_code`; opcjonalnie `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` — te same nazwy pól co w API lokalizacji). Podaj dokładnie jedną z nich — odniesienie do lokalizacji albo adres bezpośredni, nie obie.

**adres dostawy**

> [tab] Odniesienie do lokalizacji
>
> **location\_id** `string` *required*
>
> UUID znanego punktu pobrań, do którego ma zostać wysłany zestaw. Powiąż z [Lista
> lokalizacji](https://docs.anivahealth.com/pl/api/locations/list-locations.md).

> [tab] Adres bezpośredni
>
> **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 prowincja. Opcjonalne.
>
> **postal\_code** `string` *required*
>
> Kod pocztowy. Niemiecki adres (`country_code` `DE`) wymaga dokładnie 5 cyfr, np. `10117`.
>
> **country\_code** `string` *required*
>
> Kod ISO 3166-1 alpha-2 (dwie litery, np. `DE`). Małe litery są akceptowane i zapisywane jako wielkie
> litery.
>
> **phone** `string`
>
> Numer telefonu odbiorcy z numerem kierunkowym kraju (np. `+4791234567`). Przewoźnik używa go, aby
> powiadomić odbiorcę o przesyłce, na przykład że czeka w punkcie odbioru. Jeśli go
> pominiesz, przewoźnik nie otrzyma numeru telefonu.
>
> **email** `string`
>
> Adres e-mail odbiorcy. Przewoźnik używa go tak samo jak `phone`. Jeśli go pominiesz, przewoźnik nie otrzyma
> adresu e-mail.

> [!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, spacje dozwolone). Bez numeru Postnummer przesyłki nie można nadać.
> Postfach nie jest obsługiwany.

## Odpowiedź

W przypadku powodzenia API zwraca `201 Created` wraz z nowym zamówieniem domowego zestawu testowego.

**id** `string` *required*

Unikalny identyfikator zamówienia domowego zestawu testowego (UUID).

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

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

**status** `string` *required*

Aktualny status zamówienia domowego zestawu testowego. Jedna z wartości: `pending`, `dispatched`, `activated` lub `cancelled`. Nowo
utworzone zamówienie ma początkowo status `pending`.

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

Adres, na który ma zostać wysłany zestaw — w jednej z dwóch postaci: albo `{ location_id }` wskazujące znaną lokalizację badań, albo pola adresu wpisane bezpośrednio (`name`, `street`, `city`, `postal_code`, `country_code`; pola `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` są opcjonalne — takie samo nazewnictwo jak w API lokalizacji). Podaj dokładnie jedną opcję — odniesienie do lokalizacji albo adres wpisany bezpośrednio, nie obie naraz.

**adres dostawy**

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

> [tab] Adres wpisany bezpośrednio
>
> **name** `string` *required*
>
> Nazwa odbiorcy, firmy lub lokalizacji.
>
> **company\_name** `string`
>
> Firma przechowująca przesyłkę dla odbiorcy — podmiot typu `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. Pole opcjonalne.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Kod ISO 3166-1 alpha-2 (dwie litery, np. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Przekazane przez ciebie pary klucz/wartość. Zawsze obecne — `{}`, jeśli żadnych nie ustawisz.

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

Zamówienie domowego zestawu testowego, które to zamówienie zastępuje. `null` w przypadku zwykłego zamówienia.

**replacement\_reason** `string`

Podany przez ciebie powód. `null` w przypadku zwykłego zamówienia.

**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).

**lab\_code** `string`

Kod próbki w laboratorium, pod którym raportowane są wyniki — wydrukowany na fizycznym zestawie i odczytywany
przez pacjenta z pudełka jako kod aktywacyjny. `null` do czasu spakowania zestawu.
Tylko do odczytu.

**activated\_at** `string` *required*

Znacznik czasu pobrania zgłoszony przez [Aktywuj](https://docs.anivahealth.com/pl/api/home-kit-orders/activate-home-kit.md). `null` do czasu
aktywacji zestawu.

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

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

**updated\_at** `string`

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

**profile** `object` *required*

Profil pacjenta powiązany z tym zamówieniem domowego zestawu testowego.

**profil**

**id** `string`

Unikalny identyfikator profilu (UUID).

**handle** `string`

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

**first\_name** `string`

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

**last\_name** `string`

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

**email** `string`

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

**phone** `string`

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

**sex** `integer`

Płeć biologiczna wg 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 e-maile transakcyjne (wysyłane automatycznie). 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** `HomeKitOrderPanel[]` *required*

Panel przypisany do tego zamówienia domowego zestawu testowego — ten przekazany jako `panel_id`, opatrzony
czasem utworzenia zamówienia. Zawsze dokładnie jeden. Szczegóły panelu (nazwę, biomarkery) sprawdzisz w
[Lista paneli](https://docs.anivahealth.com/pl/api/panels/list-panels.md).

**Pola dołączonego panelu**

**panel\_id** `string`

UUID panelu — sprawdź w [Wyświetl panele](https://docs.anivahealth.com/pl/api/panels/list-panels.md).

**added\_at** `string`

Znacznik czasu ISO 8601 pierwszego dołączenia panelu do tego zamówienia domowego zestawu testowego.

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

Biomarkery dodane poza panelem. Puste przy zwykłym utworzeniu — domowe zestawy testowe zamawia się według
panelu, a późniejsza zmiana tej listy wymaga zakresu uprawnień
`home_kit_orders_individual_biomarker_selection`. W zestawie zastępczym zawiera wysłane
`biomarker_ids`, czyli markery powtarzane przez laboratorium.

**Pola pojedynczego biomarkera**

**biomarker\_id** `integer`

Identyfikator biomarkera — sprawdź w
[Wyświetl biomarkery](https://docs.anivahealth.com/pl/api/biomarkers/list-biomarkers.md) z `home_kit=true`.

**added\_at** `string`

Znacznik czasu ISO 8601 pierwszego dołączenia biomarkera do tego zamówienia domowego zestawu testowego.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Przesyłki powiązane z tym zamówieniem domowego zestawu testowego, od najstarszego powiązania. Zawsze puste przy utworzeniu — pełne dane
przesyłek odczytasz przez [Lista przesyłek](https://docs.anivahealth.com/pl/api/shipments/list-shipments.md) z parametrem `?home_kit_order_id=`.

**Pola powiązania przesyłki**

**id** `string`

Identyfikator przesyłki — sprawdź w [Pobierz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/get-shipment.md).

**added\_at** `string`

Znacznik czasu ISO 8601 powiązania przesyłki z tym zamówieniem domowego zestawu testowego.

## Odpowiedzi z błędami

| Status | Opis |
| - | - |
| `400` | Błąd walidacji — np. w `delivery_address` brakuje pola lub niemiecki kod pocztowy nie ma 5 cyfr, `panel_id` nie jest prawidłowym UUID lub w zestawie zastępczym brakuje `replacement_reason`. |
| `403` | Brak dostępu — twój klucz API nie ma uprawnień do tej operacji, profil znajduje się poza twoim zakresem uprawnień lub ustawiasz `results_ready_emails` bez dostępu `results_view` do pacjenta. |
| `404` | Nie znaleziono profilu, panelu lub zastępowanego zamówienia domowego zestawu testowego. |
| `409` | Konflikt — nagłówek `Idempotency-Key` został już użyty z inną treścią żądania, pierwotne żądanie jeszcze się nie zakończyło lub zastępowany zestaw ma już zestaw zastępczy w drodze. |
| `422` | Panelu nie można zamówić jako domowego zestawu testowego — nie skonfigurowano dla niego produktu zestawu do realizacji. W przypadku zestawu zastępczego: zastępowane zamówienie należy do innego profilu, pozycja z `biomarker_ids` nie należy do zakresu tego zamówienia lub wysyłasz markery razem z innym `panel_id`. |
| `500` | Wewnętrzny błąd serwera. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```bash Replacement kit theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

```json 404 theme={null}
{
  "error": "Profile not found"
}
```

```json 409 theme={null}
{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}
```


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