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

# Creează o comandă de kit de testare la domiciliu

> Solicită un kit de testare la domiciliu trimis prin poștă pentru un profil

Solicită o comandă de kit de testare la domiciliu pentru un profil de pacient. O comandă de kit de testare la domiciliu trimite un kit de autotestare prin poștă — Aniva expediază kitul la adresa de livrare, pacientul își recoltează singur proba acasă și o trimite înapoi prin poștă. Aceasta diferă de o [programare](https://docs.anivahealth.com/ro/api/appointments/create-appointment.md), care este o recoltare venoasă de sânge într-o locație de testare.

**Este necesar exact un panel.** Un kit de testare la domiciliu corespunde 1:1 unui produs fizic — panelul este kitul — iar comanda intră în coada de ambalare imediat ce este creată, așa că compoziția trebuie să fie finală de la început. Poți totuși să schimbi panelul prin [Actualizează comanda de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/update-home-kit.md) cât timp comanda este `pending`.

## Kituri de înlocuire

Când un kit nu poate oferi rezultatele — pacientul nu a putut umple tubul, proba a ajuns cu prea puțin material, laboratorul nu a putut să o analizeze — comandă un **kit de înlocuire** trimițând `replaces_home_kit_order_id`.

Un kit de înlocuire este o comandă nouă cu un cod de laborator nou, chiar și atunci când primul kit nu a fost activat niciodată: laboratorul are nevoie de o cerere nouă, iar două probe cu același cod nu pot fi diferențiate. Comanda pe care o înlocuiești rămâne neatinsă — își păstrează propriul status, propriul cod de laborator și toate rezultatele deja înregistrate pentru ea.

De aici decurg două lucruri:

* **Panelul este moștenit.** Omite `panel_id` și kitul de înlocuire preia panelul comenzii pe care o înlocuiește, adică ceea ce a cumpărat pacientul și modul în care este personalizată cutia.
* **Tu alegi ce se reanalizează.** Trimite `biomarker_ids` cu markerii care au eșuat, iar laboratorul îi reanalizează doar pe aceia, astfel încât kitul este expediat doar cu tuburile necesare. Omite-l pentru a reanaliza întregul panel.

Markerii sunt reanalizați pe grupurile panelului, nu unul câte unul. Indicarea unui singur marker dintr-un grup duce la reanalizarea întregului grup, deoarece nu poate fi plasată o comandă de laborator care raportează mai mult decât s-a cerut. Prin urmare, un kit de înlocuire pentru un singur marker poate sosi cu mai mult de un rezultat, iar numărul de tuburi poate fi mai mare decât sugerează lista de markeri.

Pentru fiecare kit poate fi pe drum un singur kit de înlocuire la un moment dat.

> [!NOTE]
>
> Dacă ai făcut integrarea înainte să existe aceste câmpuri, Aniva citește și `metadata.original_kit_id` și
> `metadata.replacement_reason` la creare și tratează comanda ca pe un kit de înlocuire. Acesta este singurul
> loc în care metadatele sunt interpretate, există doar pentru a susține acea integrare anterioară, iar câmpurile
> de mai sus au întotdeauna prioritate. Trimite câmpurile.

Un `201` înseamnă că s-a confirmat comanda și că va fi predată către logistică — nu trebuie să mai faci nimic altceva pentru ca kitul să fie ambalat și expediat.

Necesită scope-ul `home_kit_orders_manage`.

Trimite un antet opțional `Idempotency-Key` pentru ca această creare să poată fi reîncercată în siguranță — repetarea aceleiași chei returnează răspunsul inițial în loc să creeze încă una. Vezi [Idempotență](https://docs.anivahealth.com/ro/concepts/idempotency.md).

## Cerere

### Parametri de corp

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

UUID-ul profilului de pacient pentru care creezi comanda de kit de testare la domiciliu.

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

UUID-ul panelului din catalog pe care îl comanzi. Exact unul — un kit de testare la domiciliu corespunde 1:1 unui produs fizic,
așa că panelul este kitul. ID-urile panelurilor sunt oferite de Aniva pentru contul tău de partener; vezi [Listează
panelurile](https://docs.anivahealth.com/ro/api/panels/list-panels.md). Opțional pentru un kit de înlocuire, unde folosește implicit panelul
comenzii pe care o înlocuiești.

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

UUID-ul comenzii de kit de testare la domiciliu pe care o înlocuiește aceasta. Trimiterea lui transformă comanda într-un kit de înlocuire — vezi
[Kituri de înlocuire](#kituri-de-inlocuire) mai sus. Comanda trebuie să aparțină aceluiași profil și să nu
aibă deja un kit de înlocuire pe drum.

**replacement\_reason** `string`

Motivul pentru care este necesară înlocuirea, într-o singură propoziție (de exemplu `Zu wenig Material, HbA1c nicht
    auswertbar`). Obligatoriu când trimiți `replaces_home_kit_order_id` și ignorat în rest. Cel mult
500 de caractere.

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

La un kit de înlocuire, markerii pe care laboratorul îi reanalizează — de obicei cei pe care primul kit nu i-a putut
oferi. Fiecare trebuie să facă parte din ce a solicitat comanda pe care o înlocuiești; verifică în [Listează
biomarkerii](https://docs.anivahealth.com/ro/api/biomarkers/list-biomarkers.md) cu `home_kit=true`. Omite-l pentru a reanaliza întregul panel. Este
acceptat doar împreună cu `replaces_home_kit_order_id` și nu împreună cu un alt `panel_id`.
Nu necesită un scope suplimentar: reanalizarea markerilor pe care pacientul i-a plătit deja nu este o selecție
à-la-carte.

**metadata** `object`

Propriile tale perechi cheie/valoare, returnate identic la fiecare citire și niciodată interpretate de Aniva. Folosește acest câmp
pentru a transmite referința comenzii tale, astfel încât să poți face corelarea fără să stochezi ID-urile noastre. Cel mult 20 de chei;
cheile respectă `[A-Za-z0-9_-]` și au cel mult 40 de caractere; valorile sunt șir de caractere, număr sau valoare booleană,
cu șiruri de cel mult 500 de caractere; 16.384 de bytes serializați în total. Cheile care încep cu `aniva_` sunt
rezervate. Nu pune niciodată date personale sau clinice în `metadata` — nu este tratat ca date ale pacientului.

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

Până la 5 adrese care primesc fiecare câte un email odată ce toate rezultatele de laborator sunt finale. Emailul conține un link către
pagina de rezultate din panoul de administrare Aniva. Cheia ta are nevoie de acces `results_view` pentru pacient, altfel returnează
`403`. Omite câmpul pentru a folosi adresele implicite setate pentru grupul pacientului. O listă goală dezactivează
emailurile. Vezi [Emailuri când rezultatele sunt gata](https://docs.anivahealth.com/ro/concepts/results.md#e-mailuri-cand-rezultatele-sunt-gata).

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

Adresa la care se trimite kitul prin poștă — una dintre două forme: fie `{ location_id }` care face referire la o locație de testare cunoscută, fie câmpurile de adresă inline (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opționale — același vocabular ca în API-ul de locații). Trimite exact una dintre ele — o referință la o locație sau o adresă inline, nu ambele.

**adresa de livrare**

> [tab] Referință la o locație
>
> **location\_id** `string` *required*
>
> UUID-ul unei locații de testare cunoscute la care se expediază kitul. Corelează cu [Listează
> locațiile](https://docs.anivahealth.com/ro/api/locations/list-locations.md).

> [tab] Adresă inline
>
> **name** `string` *required*
>
> Numele destinatarului, al companiei sau al locației.
>
> **company\_name** `string`
>
> Compania care preia coletul pentru destinatar — un intermediar `c/o` sau un departament.
>
> **street** `string` *required*
>
> Numele străzii, fără numărul imobilului (de ex. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Numărul imobilului (de ex. `118` sau `12a`).
>
> **address\_line\_2** `string`
>
> Clădire, scară sau etaj.
>
> **city** `string` *required*
>
> **state** `string`
>
> Stat sau provincie. Opțional.
>
> **postal\_code** `string` *required*
>
> Cod poștal. O adresă din Germania (`country_code` `DE`) necesită exact 5 cifre, de ex. `10117`.
>
> **country\_code** `string` *required*
>
> Cod ISO 3166-1 alpha-2 (două litere, de ex. `DE`). Literele mici sunt acceptate și stocate ca
> majuscule.
>
> **phone** `string`
>
> Numărul de telefon al destinatarului, cu prefix de țară (de ex. `+4791234567`). Curierul îl folosește pentru a
> anunța destinatarul despre colet, de exemplu că îl așteaptă la un punct de ridicare. Omite-l
> și curierul nu primește niciun număr de telefon.
>
> **email** `string`
>
> Adresa de e-mail a destinatarului. Curierul o folosește la fel ca `phone`. Omite-o și curierul nu primește nicio
> adresă de e-mail.

> [!NOTE]
>
> **Packstation sau Postfiliale (doar în Germania):** setează `street` la `Packstation` sau `Postfiliale`,
> `house_number` la numărul de trei cifre al stației și `address_line_2` la DHL
> Postnummer al destinatarului (6–10 cifre, spațiile sunt permise). Fără Postnummer, expedierea coletului nu poate fi înregistrată.
> Postfach nu este acceptat.

## Răspuns

În caz de succes, API-ul returnează `201 Created` cu noua comandă de kit de testare la domiciliu.

**id** `string` *required*

Identificatorul unic (UUID) al comenzii de kit de testare la domiciliu.

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

UUID-ul profilului căruia îi aparține această comandă de kit de testare la domiciliu.

**status** `string` *required*

Statusul actual al comenzii de kit de testare la domiciliu. Una dintre valorile `pending`, `dispatched`, `activated` sau `cancelled`. O
comandă nou creată pornește cu statusul `pending`.

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

Adresa la care se trimite kitul — în una dintre două forme: fie `{ location_id }` cu referire la o locație de testare cunoscută, fie câmpurile de adresă inline (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opționale — același vocabular ca în API-ul de locații). Furnizează exact una dintre ele — o referință de locație sau o adresă inline, nu ambele.

**adresa de livrare**

> [tab] Referință de locație
>
> **location\_id** `string` *required*
>
> UUID-ul locației de testare la care se expediază kitul.

> [tab] Adresă inline
>
> **name** `string` *required*
>
> Numele destinatarului, al companiei sau al locației.
>
> **company\_name** `string`
>
> Compania care păstrează coletul pentru destinatar — o parte `c/o` sau un departament.
>
> **street** `string` *required*
>
> Numele străzii, fără număr (de ex. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Numărul casei (de ex. `118` sau `12a`).
>
> **address\_line\_2** `string`
>
> Clădire, scară sau etaj.
>
> **city** `string` *required*
>
> **state** `string`
>
> Stat sau provincie. Opțional.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Cod ISO 3166-1 alpha-2 (două litere, de ex. `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Perechile cheie/valoare pe care le-ai trimis. Întotdeauna prezent — `{}` când nu setezi niciuna.

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

Comanda de kit de testare la domiciliu pe care o înlocuiește aceasta. `null` pentru o comandă obișnuită.

**replacement\_reason** `string`

Motivul pe care l-ai furnizat. `null` pentru o comandă obișnuită.

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

Adresele care primesc fiecare câte un e-mail când toate rezultatele de laborator sunt finale, cu
litere mici. Gol când este dezactivat. Vezi
[E-mailuri pentru rezultate gata](https://docs.anivahealth.com/ro/concepts/results.md#e-mailuri-cand-rezultatele-sunt-gata).

**lab\_code** `string`

Codul de probă de laborator sub care sunt raportate rezultatele — tipărit pe kitul fizic, pe care
pacientul îl citește de pe cutie ca cod de activare. `null` până când kitul este ambalat.
Doar citire.

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

Marca temporală a recoltării raportată prin [Activează](https://docs.anivahealth.com/ro/api/home-kit-orders/activate-home-kit.md). `null` până când
kitul este activat.

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

Marcajul temporal ISO 8601 al momentului în care a fost creată comanda de kit de testare la domiciliu.

**updated\_at** `string`

Timestamp ISO 8601 al ultimei actualizări. Poate fi `null`.

**profile** `object` *required*

Profilul pacientului asociat acestei comenzi de kit de testare la domiciliu.

**profil**

**id** `string`

Identificatorul unic al profilului (UUID).

**handle** `string`

Handle-ul profilului sau numele de utilizator. Poate fi `null`.

**first\_name** `string`

Prenume. Poate fi `null`.

**last\_name** `string`

Nume de familie. Poate fi `null`.

**email** `string`

Adresă de e-mail. Poate fi `null`.

**phone** `string`

Număr de telefon în format E.164. Poate fi `null`.

**sex** `integer`

Sex biologic conform ISO/IEC 5218. Poate fi `null`.

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

Data nașterii în format `YYYY-MM-DD`. Poate fi `null`.

**height** `number`

Înălțime în centimetri. Poate fi `null`.

**weight** `number`

Greutate în kilograme. Poate fi `null`.

**language** `string`

Limba preferată: unul dintre cele 32 de coduri din [Creează profil](https://docs.anivahealth.com/ro/api/profiles/create-profile.md).

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

Indică dacă acest profil primește e-mailuri tranzacționale (programatice). Poate fi `null`.

**created\_at** `string`

Timestamp ISO 8601 al creării profilului.

**updated\_at** `string`

Timestamp ISO 8601 al ultimei actualizări a profilului. Poate fi `null`.

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

Panelul atașat acestei comenzi de kit de testare la domiciliu — cel pe care l-ai trimis ca `panel_id`, înregistrat cu ora
creării comenzii. Întotdeauna exact unul. Consultă detaliile panelului (nume, biomarkeri) prin
[Listează panelurile](https://docs.anivahealth.com/ro/api/panels/list-panels.md).

**Câmpuri pentru atașarea panelului**

**panel\_id** `string`

UUID-ul panelului — corelează cu [Listează panelurile](https://docs.anivahealth.com/ro/api/panels/list-panels.md).

**added\_at** `string`

Marcajul temporal ISO 8601 al momentului în care panelul a fost atașat prima dată la această comandă de kit de testare la domiciliu.

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

Biomarkeri atașați în afara panelului. Gol la o creare obișnuită — comenzile de kit de testare la domiciliu se comandă pe
panel, iar modificarea ulterioară a acestei liste necesită scope-ul de capabilitate
`home_kit_orders_individual_biomarker_selection`. La un kit de înlocuire conține
`biomarker_ids` pe care i-ai trimis, adică ceea ce reanalizează laboratorul.

**Câmpuri pentru biomarkeri individuali**

**biomarker\_id** `integer`

Identificatorul biomarkerului — corelează cu
[Listează biomarkerii](https://docs.anivahealth.com/ro/api/biomarkers/list-biomarkers.md) cu `home_kit=true`.

**added\_at** `string`

Marcajul temporal ISO 8601 al momentului în care biomarkerul a fost atașat prima dată la această comandă de kit de testare la domiciliu.

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

Colete asociate acestei comenzi de kit de testare la domiciliu, în ordinea vechimii asocierii. Întotdeauna gol la creare — citește
coletele complete cu [Listează expedierile](https://docs.anivahealth.com/ro/api/shipments/list-shipments.md) și `?home_kit_order_id=`.

**Câmpuri pentru asocierea expedierii**

**id** `string`

Referința expedierii — corelează cu [Obține expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md).

**added\_at** `string`

Marcajul temporal ISO 8601 al momentului în care expedierea a fost asociată acestei comenzi de kit de testare la domiciliu.

## Răspunsuri de eroare

| Status | Descriere |
| - | - |
| `400` | Eroare de validare — de ex. lui `delivery_address` îi lipsește un câmp sau are un cod poștal german care nu are 5 cifre, `panel_id` nu este un UUID valid sau `replacement_reason` lipsește la un kit de înlocuire. |
| `403` | Interzis — cheia ta API nu are acces la această operațiune, profilul este în afara scope-ului tău de permisiuni sau ai setat `results_ready_emails` fără acces `results_view` la pacient. |
| `404` | Profilul, panelul sau comanda de kit de testare la domiciliu de înlocuit nu a fost găsită. |
| `409` | Conflict — `Idempotency-Key` a fost deja folosit cu un corp diferit, cererea inițială nu s-a finalizat sau kitul pe care îl înlocuiești are deja un kit de înlocuire pe drum. |
| `422` | Panelul nu poate fi comandat ca kit de testare la domiciliu — nu este configurat niciun produs fizic de kit pentru el. La un kit de înlocuire: comanda pe care o înlocuiești aparține altui profil, o intrare din `biomarker_ids` nu face parte din ce a solicitat comanda sau ai trimis markeri împreună cu un alt `panel_id`. |
| `500` | Eroare internă de server. |

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