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

# Vytvořit objednávku domácí testovací sady

> Objednat domácí testovací sadu zasílanou poštou pro profil

Zadej objednávku domácí testovací sady pro profil pacienta. Objednávka domácí testovací sady odešle sadu pro domácí odběr poštou – Aniva ji pošle na doručovací adresu, pacient si doma sám odebere vzorek a pošle ho zpět. Liší se od [termínu](https://docs.anivahealth.com/cs/api/appointments/create-appointment.md), což je žilní odběr krve na odběrovém místě.

**Je potřeba přesně jeden panel.** Domácí testovací sada odpovídá 1:1 fyzické sadě – panel je samotná sada – a objednávka se hned po vytvoření zařadí do fronty k balení, takže složení musí být finální hned od začátku. Dokud je objednávka ve stavu `pending`, můžeš panel ještě vyměnit přes [Aktualizovat objednávku domácí testovací sady](https://docs.anivahealth.com/cs/api/home-kit-orders/update-home-kit.md).

## Náhradní sady

Když sada nemůže dodat výsledky – pacient nedokázal naplnit zkumavku, vzorek dorazil s příliš malým množstvím materiálu, laboratoř ho nemohla analyzovat – objednej **náhradu** odesláním `replaces_home_kit_order_id`.

Náhrada je nová objednávka s novým laboratorním kódem, a to i v případě, že první sada nebyla nikdy aktivována: laboratoř potřebuje novou žádanku a dva vzorky pod jedním kódem od sebe nejde rozlišit. Nahrazovaná objednávka zůstává beze změny – ponechá si svůj stav, vlastní laboratorní kód i všechny výsledky, které už k ní byly přiřazeny.

Z toho plynou dvě věci:

* **Panel se dědí.** Vynech `panel_id` a náhrada převezme panel nahrazované objednávky, což odpovídá tomu, co si pacient koupil a jak je krabička označená.
* **Zvolíš si, co se znovu otestuje.** Pošli `biomarker_ids` s markery, které selhaly, a laboratoř znovu otestuje jen ty, takže se v sadě odešlou jen potřebné zkumavky. Když pole vynecháš, znovu se otestuje celý panel.

Markery se znovu testují po skupinách v rámci panelu, ne jeden po druhém. Když uvedeš jeden marker ze skupiny, znovu se otestuje celá skupina, protože nelze zadat laboratorní objednávku, která by vyhodnotila víc, než bylo požadováno. Náhrada pro jeden marker proto může dorazit s více než jedním výsledkem a počet zkumavek může být větší, než by seznam markerů napovídal.

Pro jednu sadu může být na cestě vždy jen jedna náhrada.

> [!NOTE]
>
> Pokud máš integraci z doby, kdy tato pole ještě neexistovala, Aniva při vytváření čte také
> `metadata.original_kit_id` a `metadata.replacement_reason` a zpracuje objednávku jako náhradu.
> Je to jediné místo, kde se metadata interpretují – slouží jen pro zachování této starší integrace
> a výše uvedená pole mají vždy přednost. Posílej tato pole.

Stav `201` znamená, že objednávka je závazně přijata a bude předána k expedici – pro zabalení a odeslání sady už nemusíš dělat nic dalšího.

Vyžaduje scope `home_kit_orders_manage`.

Odešli volitelnou hlavičku `Idempotency-Key`, aby šlo toto vytvoření bezpečně zopakovat — opakované použití stejného klíče vrátí původní odpověď místo vytvoření dalšího záznamu. Viz [Idempotence](https://docs.anivahealth.com/cs/concepts/idempotency.md).

## Požadavek

### Parametry těla

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

UUID profilu pacienta, pro který se má objednávka domácí testovací sady vytvořit.

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

UUID panelu z katalogu k objednání. Přesně jeden – domácí testovací sada odpovídá 1:1 fyzické
sadě, takže panel je samotná sada. ID panelů poskytuje Aniva pro tvůj partnerský účet; viz
[Seznam panelů](https://docs.anivahealth.com/cs/api/panels/list-panels.md). U náhrady je pole volitelné a výchozí hodnotou je panel
nahrazované objednávky.

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

UUID objednávky domácí testovací sady, kterou tato nahrazuje. Jeho odesláním se z objednávky
stane náhradní sada – viz [Náhradní sady](#nahradni-sady) výše. Objednávka musí patřit ke
stejnému profilu a nesmí už pro ni být na cestě jiná náhrada.

**replacement\_reason** `string`

Důvod, proč je náhrada potřeba, v jedné větě (například `Zu wenig Material, HbA1c nicht
    auswertbar`). Povinné při odeslání `replaces_home_kit_order_id`, jinak se ignoruje. Maximálně
500 znaků.

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

U náhrady markery, které laboratoř znovu otestuje – obvykle ty, které první sada nedokázala
dodat. Každý musí být součástí toho, co požadovala nahrazovaná objednávka; ověř si je přes
[Seznam biomarkerů](https://docs.anivahealth.com/cs/api/biomarkers/list-biomarkers.md) s parametrem `home_kit=true`. Vynech pole,
pokud chceš znovu otestovat celý panel. Přijímá se jen spolu s `replaces_home_kit_order_id` a ne
spolu s jiným `panel_id`. Nevyžaduje žádný další scope: opakované otestování markerů, které už
pacient zaplatil, není individuální výběr.

**metadata** `object`

Tvoje vlastní dvojice klíč/hodnota, které se při každém čtení vrací beze změny a Aniva je nikdy
neinterpretuje. Použij je pro vlastní referenci objednávky, ať můžeš data spárovat bez ukládání
našich ID. Maximálně 20 klíčů; klíče odpovídají `[A-Za-z0-9_-]` a mají nejvýše 40 znaků; hodnoty
jsou řetězec, číslo nebo boolean, u řetězců nejvýše 500 znaků; celkem nejvýše 16 384 bajtů po
serializaci. Klíče začínající na `aniva_` jsou vyhrazené. Nikdy do `metadata` nedávej osobní ani
klinické údaje – nezpracovávají se jako data pacienta.

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

Až 5 adres, z nichž každá dostane jeden e-mail, jakmile budou všechny laboratorní výsledky konečné.
E-mail odkazuje na stránku s výsledky v administračním panelu Aniva. Tvůj klíč potřebuje oprávnění
`results_view` k pacientovi, jinak `403`. Vynech ho, pokud chceš použít výchozí adresy nastavené
pro skupinu pacienta. Prázdný seznam e-maily vypne. Viz [E-maily o připravených
výsledcích](https://docs.anivahealth.com/cs/concepts/results.md#e-maily-o-pripravenych-vysledcich).

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

Adresa pro doručení sady – má jednu ze dvou podob: buď `{ location_id }` s odkazem na známé odběrové místo, nebo přímo uvedená pole adresy (`name`, `street`, `city`, `postal_code`, `country_code`; volitelně `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` – stejná struktura polí jako v API odběrových míst). Uveď přesně jednu z možností – odkaz na odběrové místo, nebo přímou adresu, ne obojí.

**doručovací adresa**

> [tab] Odkaz na odběrové místo
>
> **location\_id** `string` *required*
>
> UUID známého odběrového místa, kam se má sada poslat. Spáruj se [Seznamem
> odběrových míst](https://docs.anivahealth.com/cs/api/locations/list-locations.md).

> [tab] Přímá adresa
>
> **name** `string` *required*
>
> Jméno příjemce, název firmy nebo odběrového místa.
>
> **company\_name** `string`
>
> Firma, která zásilku pro příjemce přebírá – kontakt `c/o` nebo oddělení.
>
> **street** `string` *required*
>
> Název ulice bez čísla domu (např. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Číslo domu (např. `118` nebo `12a`).
>
> **address\_line\_2** `string`
>
> Budova, vchod nebo patro.
>
> **city** `string` *required*
>
> **state** `string`
>
> Stát nebo provincie. Volitelné.
>
> **postal\_code** `string` *required*
>
> PSČ. Německá adresa (`country_code` `DE`) vyžaduje přesně 5 číslic, např. `10117`.
>
> **country\_code** `string` *required*
>
> Kód ISO 3166-1 alpha-2 (dvě písmena, např. `DE`). Přijímají se i malá písmena a ukládají se
> jako velká.
>
> **phone** `string`
>
> Telefonní číslo příjemce s předvolbou země (např. `+4791234567`). Dopravce ho používá
> k informování příjemce o zásilce, například že čeká na výdejním místě. Když pole vynecháš,
> dopravce žádné telefonní číslo nedostane.
>
> **email** `string`
>
> E-mail příjemce. Dopravce ho používá stejně jako `phone`. Když pole vynecháš, dopravce žádný
> e-mail nedostane.

> [!NOTE]
>
> **Packstation nebo Postfiliale (pouze Německo):** nastav `street` na `Packstation` nebo
> `Postfiliale`, `house_number` na trojmístné číslo stanice a `address_line_2` na DHL Postnummer
> příjemce (6–10 číslic, mezery jsou povoleny). Bez Postnummer nelze zásilku objednat.
> Postfach není podporován.

## Odpověď

Při úspěchu API vrátí `201 Created` s novou objednávkou domácí testovací sady.

**id** `string` *required*

Jedinečný identifikátor objednávky domácí testovací sady (UUID).

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

UUID profilu, ke kterému tato objednávka domácí testovací sady patří.

**status** `string` *required*

Aktuální stav objednávky domácí testovací sady. Jedna z hodnot `pending`, `dispatched`, `activated`
nebo `cancelled`. Nově vytvořená objednávka začíná ve stavu `pending`.

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

Adresa pro doručení sady — jedna ze dvou podob: buď `{ location_id }` s odkazem na známé testovací místo, nebo přímo vložená pole adresy (`name`, `street`, `city`, `postal_code`, `country_code`; nepovinně `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` — stejný slovník jako v locations API). Uveď přesně jednu variantu — odkaz na místo, nebo přímou adresu, ne obojí.

**doručovací adresa**

> [tab] Odkaz na místo
>
> **location\_id** `string` *required*
>
> UUID testovacího místa, kam se sada zasílá.

> [tab] Přímá adresa
>
> **name** `string` *required*
>
> Jméno příjemce, název firmy nebo místa.
>
> **company\_name** `string`
>
> Firma přebírající zásilku za příjemce — strana `c/o` nebo oddělení.
>
> **street** `string` *required*
>
> Název ulice bez čísla domu (např. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Číslo domu (např. `118` nebo `12a`).
>
> **address\_line\_2** `string`
>
> Budova, vchod nebo patro.
>
> **city** `string` *required*
>
> **state** `string`
>
> Stát nebo provincie. Nepovinné.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Kód ISO 3166-1 alpha-2 (dvě písmena, např. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Zadané dvojice klíč/hodnota. Vždy přítomné – pokud žádné nenastavíš, obsahuje `{}`.

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

Objednávka domácí testovací sady, kterou tato nahrazuje. U běžné objednávky má hodnotu `null`.

**replacement\_reason** `string`

Zadaný důvod. U běžné objednávky má hodnotu `null`.

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

Adresy malými písmeny, z nichž každá dostane jeden e-mail, jakmile jsou všechny laboratorní výsledky
konečné. Prázdné, když je vypnuto. Viz [E-maily o připravených výsledcích](https://docs.anivahealth.com/cs/concepts/results.md#e-maily-o-pripravenych-vysledcich).

**lab\_code** `string`

Laboratorní kód vzorku, pod kterým se hlásí výsledky — je vytištěný na fyzické sadě a pacient
ho přečte z krabičky jako aktivační kód. `null`, dokud není sada zabalená.
Pouze pro čtení.

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

Časové razítko odběru nahlášené přes [Aktivovat](https://docs.anivahealth.com/cs/api/home-kit-orders/activate-home-kit.md). Do
aktivace sady má hodnotu `null`.

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

Časové razítko ve formátu ISO 8601, kdy byla objednávka domácí testovací sady vytvořena.

**updated\_at** `string`

Časové razítko ISO 8601 poslední aktualizace. Může být `null`.

**profile** `object` *required*

Profil pacienta spojený s touto objednávkou domácí testovací sady.

**profil**

**id** `string`

Jedinečný identifikátor profilu (UUID).

**handle** `string`

Přezdívka profilu nebo uživatelské jméno. Může být `null`.

**first\_name** `string`

Křestní jméno. Může být `null`.

**last\_name** `string`

Příjmení. Může být `null`.

**email** `string`

E-mailová adresa. Může být `null`.

**phone** `string`

Telefonní číslo ve formátu E.164. Může být `null`.

**sex** `integer`

Biologické pohlaví podle normy ISO/IEC 5218. Může být `null`.

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

Datum narození ve formátu `YYYY-MM-DD`. Může být `null`.

**height** `number`

Výška v centimetrech. Může být `null`.

**weight** `number`

Hmotnost v kilogramech. Může být `null`.

**language** `string`

Preferovaný jazyk: jeden ze 32 kódů ve [Vytvořit profil](https://docs.anivahealth.com/cs/api/profiles/create-profile.md).

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

Zda tento profil přijímá transakční (automatické) e-maily. Může být `null`.

**created\_at** `string`

Časové razítko ISO 8601 vytvoření profilu.

**updated\_at** `string`

Časové razítko ISO 8601 poslední aktualizace profilu. Může být `null`.

**panels** `HomeKitOrderPanel[]` *required*

Panel přiřazený k této objednávce domácí testovací sady – ten zadaný jako `panel_id`, s časovým
razítkem vytvoření objednávky. Vždy přesně jeden. Podrobnosti panelu (název, biomarkery) najdeš
přes [Seznam panelů](https://docs.anivahealth.com/cs/api/panels/list-panels.md).

**Pole přiřazení panelu**

**panel\_id** `string`

UUID panelu — dohledáš přes [Seznam panelů](https://docs.anivahealth.com/cs/api/panels/list-panels.md).

**added\_at** `string`

Časové razítko ve formátu ISO 8601, kdy byl panel poprvé přiřazen k této objednávce domácí testovací sady.

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

Biomarkery přiřazené mimo panel. Při běžném vytvoření je seznam prázdný – domácí testovací sady
se objednávají podle panelu a pozdější úprava tohoto seznamu vyžaduje scope oprávnění
`home_kit_orders_individual_biomarker_selection`. U náhrady obsahuje odeslaná `biomarker_ids`,
tedy markery, které laboratoř znovu otestuje.

**Pole jednotlivých biomarkerů**

**biomarker\_id** `integer`

Identifikátor biomarkeru — dohledáš přes
[Seznam biomarkerů](https://docs.anivahealth.com/cs/api/biomarkers/list-biomarkers.md) s `home_kit=true`.

**added\_at** `string`

Časové razítko ve formátu ISO 8601, kdy byl biomarker poprvé přiřazen k této objednávce domácí testovací sady.

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

Zásilky propojené s touto objednávkou domácí testovací sady, seřazené od nejstaršího propojení.
Při vytvoření vždy prázdné – kompletní údaje o zásilkách načteš přes
[Seznam zásilek](https://docs.anivahealth.com/cs/api/shipments/list-shipments.md) s parametrem `?home_kit_order_id=`.

**Pole propojení zásilky**

**id** `string`

Reference zásilky — dohledáš přes [Získání zásilky](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md).

**added\_at** `string`

Časové razítko ve formátu ISO 8601, kdy byla zásilka propojena s touto objednávkou domácí testovací sady.

## Chybové odpovědi

| Stav | Popis |
| - | - |
| `400` | Chyba validace – např. v `delivery_address` chybí pole nebo má německé PSČ, které nemá 5 číslic, `panel_id` není platné UUID nebo u náhrady chybí `replacement_reason`. |
| `403` | Přístup odepřen – tvůj API klíč nemá přístup k této operaci, profil je mimo rozsah tvých oprávnění, nebo nastavuješ `results_ready_emails` bez přístupu `results_view` k pacientovi. |
| `404` | Profil, panel nebo nahrazovaná objednávka domácí testovací sady nebyly nalezeny. |
| `409` | Konflikt – `Idempotency-Key` už byl použit s jiným tělem požadavku, původní požadavek ještě neskončil nebo už je pro nahrazovanou sadu na cestě jiná náhrada. |
| `422` | Panel nelze objednat jako domácí testovací sadu – nemá nakonfigurovaný žádný expediční produkt sady. U náhrady: nahrazovaná objednávka patří jinému profilu, některá položka v `biomarker_ids` nebyla součástí původního požadavku nebo posíláš markery spolu s jiným `panel_id`. |
| `500` | Interní chyba serveru. |

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