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

# Heimtest-Kit-Bestellungen

> So funktionieren Heimtest-Kit-Bestellungen in der Aniva API: Bestellung eines Einsende-Kits, Versand, Probenrücksendung und Laborergebnisse.

Eine **Heimtest-Kit-Bestellung** sendet ein Test-Kit zur Selbstentnahme per Post an einen Patienten. Aniva verschickt das Kit, der Patient entnimmt zu Hause selbst eine Probe und schickt sie per Post zurück. Das unterscheidet sich von einem [Termin](https://docs.anivahealth.com/de/concepts/appointments.md), also einer venösen Blutabnahme durch eine medizinische Fachkraft an einem physischen Teststandort.

> [!NOTE]
>
> Endpunkte für Heimtest-Kit-Bestellungen erfordern den Scope `home_kit_orders_view` (Lesen) oder
> `home_kit_orders_manage` (Schreiben). [Aktivieren](https://docs.anivahealth.com/de/api/home-kit-orders/activate-home-kit.md)
> akzeptiert auch den enger gefassten Scope `home_kit_orders_activate`.
> [Ergebnisse abrufen](https://docs.anivahealth.com/de/api/home-kit-orders/get-results.md) und
> [Ergebnisse per E-Mail senden](https://docs.anivahealth.com/de/api/home-kit-orders/email-results.md) erfordern zusätzlich
> `results_view` – Laborergebnisse und Dokumente sind immer dadurch geschützt.

## Felder

**id** `string` *required*

Von Aniva automatisch generierte UUID. Verwende sie, um die Bestellung zu aktualisieren, ihr
Panel zu wechseln, sie zu aktivieren, zu stornieren und Ergebnisse abzurufen.

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

Die UUID des Profils, zu dem diese Heimtest-Kit-Bestellung gehört.

**status** `string` *required*

Aktueller Lebenszyklus-Status. Einer der Werte `pending`, `dispatched`, `activated` oder
`cancelled`. Siehe [Lebenszyklus](#lebenszyklus) unten. Der genaue Bearbeitungsstand der
Laborergebnisse (`in_progress` vs. `completed`) ergibt sich aus
[Ergebnisse abrufen](https://docs.anivahealth.com/de/api/home-kit-orders/get-results.md).

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

Die Adresse, an die das Kit gesendet wird – in einer von zwei Formen: entweder `{location_id}` als
Verweis auf einen bekannten Teststandort oder die direkten Adressfelder (`name`, `street`, `city`,
`postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` /
`phone` / `email` optional – dieselben Felder wie in der Locations-API). Gib genau eine Variante
an – eine Standortreferenz oder eine Inline-Adresse, nicht beides.

**Lieferadresse**

> [tab] Standortreferenz
>
> **location\_id** `string` *required*
>
> UUID des Teststandorts, an den das Kit versendet wird.

> [tab] Inline-Adresse
>
> **name** `string` *required*
>
> Name des Empfängers, des Unternehmens oder des Standorts.
>
> **company\_name** `string`
>
> Unternehmen, das das Paket für den Empfänger annimmt – etwa ein `c/o`-Zusatz oder eine
> Abteilung.
>
> **street** `string` *required*
>
> Straßenname ohne Hausnummer (z. B. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Hausnummer (z. B. `118` oder `12a`).
>
> **address\_line\_2** `string`
>
> Gebäude, Eingang oder Etage.
>
> **city** `string` *required*
>
> **state** `string`
>
> Bundesland oder Provinz. Optional.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> ISO-3166-1-Alpha-2-Code (zwei Buchstaben, z. B. `DE`).
>
> **phone** `string`
>
> Telefonnummer des Empfängers. Der Versanddienstleister nutzt sie, um den Empfänger über
> das Paket zu informieren.
>
> **email** `string`
>
> E-Mail-Adresse des Empfängers. Der Versanddienstleister nutzt sie, um den Empfänger über
> das Paket zu informieren.

> [!NOTE]
>
> **Packstation oder Postfiliale (nur Deutschland):** Setze `street` auf `Packstation` oder
> `Postfiliale`, `house_number` auf die dreistellige Stationsnummer und `address_line_2` auf die
> DHL-Postnummer des Empfängers (6–10 Ziffern, Leerzeichen erlaubt). Ohne die Postnummer kann das
> Paket nicht gebucht werden. Ein Postfach wird nicht unterstützt.

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

ISO-8601-Zeitstempel, wann die Heimtest-Kit-Bestellung erstellt wurde.

**updated\_at** `string`

ISO-8601-Zeitstempel der letzten Aktualisierung. Null, wenn die Heimtest-Kit-Bestellung noch nie
aktualisiert wurde.

**profile** `object`

Das vollständige Profilobjekt des Patienten, eingebettet in jede Antwort einer
Heimtest-Kit-Bestellung.

**Eigenschaften**

**id** `string`

UUID des zugehörigen Profils.

**handle** `string`

Profil-Handle oder Benutzername. Kann `null` sein.

**first\_name** `string`

Vorname des Patienten. Kann `null` sein.

**last\_name** `string`

Nachname des Patienten. Kann `null` sein.

**email** `string`

E-Mail-Adresse des Patienten. Kann `null` sein.

**phone** `string`

Telefonnummer im E.164-Format. Kann `null` sein.

**sex** `integer`

Biologisches Geschlecht nach ISO/IEC 5218. Kann `null` sein.

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

Geburtsdatum im Format `YYYY-MM-DD`. Kann `null` sein.

**height** `number`

Körpergröße in Zentimetern. Kann `null` sein.

**weight** `number`

Gewicht in Kilogramm. Kann `null` sein.

**language** `string`

Bevorzugte Sprache: einer der 32 Codes unter [Profil erstellen](https://docs.anivahealth.com/de/api/profiles/create-profile.md).

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

Ob dieses Profil Transaktions-E-Mails (programmatische E-Mails) erhält. Kann `null` sein.

**created\_at** `string`

ISO-8601-Zeitstempel der Profilerstellung.

**updated\_at** `string`

ISO-8601-Zeitstempel der letzten Profilaktualisierung. Kann `null` sein.

**panels** `object[]`

Das der Heimtest-Kit-Bestellung zugeordnete Panel – immer genau ein Eintrag
`{ panel_id, added_at }`, da ein Heimtest-Kit 1:1 einem physischen Kit-Produkt entspricht.
Gleiche die `panel_id` mit [Panels auflisten](https://docs.anivahealth.com/de/api/panels/list-panels.md) ab.

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

Biomarker, die der Heimtest-Kit-Bestellung zusätzlich zum Panel zugeordnet sind. Jeder Eintrag
hat die Form `{ biomarker_id, added_at }`. Gleiche jede `biomarker_id` mit
[Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md) mit `home_kit=true` ab. Bei einer normalen
Bestellung sind dies einzeln gewählte Tests zusätzlich zum Panel; bei einem
[Ersatz-Kit](#ersatz-kits) sind es die Tests, die das Labor erneut durchführt.

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

Die Heimtest-Kit-Bestellung, die durch diese ersetzt wird, wenn es sich um ein
[Ersatz-Kit](#ersatz-kits) handelt. `null` bei einer normalen Bestellung.

**replacement\_reason** `string`

Warum der Ersatz verschickt wurde, in einem Satz. `null` bei einer normalen Bestellung.

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

E-Mail-Adressen in Kleinbuchstaben, die jeweils eine E-Mail erhalten, sobald alle Laborergebnisse
endgültig vorliegen. Immer vorhanden – leer, wenn deaktiviert. Lege sie beim
[Erstellen](https://docs.anivahealth.com/de/api/home-kit-orders/create-home-kit.md) oder
[Aktualisieren](https://docs.anivahealth.com/de/api/home-kit-orders/update-home-kit.md) fest. Siehe
[E-Mails bei fertigen Ergebnissen](https://docs.anivahealth.com/de/concepts/results.md#e-mails-bei-fertigen-ergebnissen).

**metadata** `object`

Deine eigenen Schlüssel-Wert-Paare, die unverändert zurückgegeben und von Aniva nie interpretiert
werden. Beim Lesen immer vorhanden – `{}`, wenn du keine gesetzt hast. Höchstens 20 Schlüssel;
Schlüssel entsprechen `[A-Za-z0-9_-]` und sind höchstens 40 Zeichen lang; Werte sind ein String,
eine Zahl oder ein Boolean, wobei Strings höchstens 500 Zeichen lang sind; insgesamt 16.384 Bytes
serialisiert. Schlüssel, die mit `aniva_` beginnen, sind reserviert. Beim
[Aktualisieren](https://docs.anivahealth.com/de/api/home-kit-orders/update-home-kit.md) werden Metadaten **zusammengeführt**:
weggelassene Schlüssel bleiben erhalten, ein mit `null` gesendeter Schlüssel wird gelöscht und
`{}` löscht alles. Die Validierung erfolgt nach dem Alles-oder-nichts-Prinzip. Speichere niemals
personenbezogene oder klinische Daten in `metadata` – sie werden nicht als Patientendaten
behandelt.

**lab\_code** `string`

Der Probencode des Labors. Ein Code, drei Aufgaben: Unter ihm werden Laborergebnisse gemeldet,
er ist auf dem physischen Kit aufgedruckt und der Patient liest ihn als Aktivierungscode von der
Box ab. Wird beim Packen des Kits zugewiesen – `null`, solange die Bestellung den Status
`pending` hat, außer nachdem Aniva ein Kit erneut versendet hat (siehe
[Lebenszyklus](#lebenszyklus)). Immer schreibgeschützt. Ordne ein vorliegendes Kit mit
`GET /api/v1/home-kit-orders?lab_code=…` wieder seiner Bestellung zu.

**activated\_at** `string`

Der über [Aktivieren](https://docs.anivahealth.com/de/api/home-kit-orders/activate-home-kit.md) gemeldete Entnahmezeitpunkt –
wann der Patient die Probe tatsächlich entnommen hat, als UTC-Zeitpunkt. `null`, bis das Kit
aktiviert ist. Dies ist der Entnahmezeitpunkt, der im Laborbericht steht.

**shipments** `object[]`

Die mit dieser Bestellung verknüpften Pakete, älteste Verknüpfung zuerst, jeweils als
`{ id, added_at }` – das Kit auf dem Weg zum Patienten und, bei Kits mit verfolgtem Rückversand,
die Probe auf dem Rückweg ins Labor, sichtbar ab dem Moment, in dem die Etiketten gedruckt werden.
Leer, solange die Bestellung den Status `pending` hat, außer nachdem Aniva ein Kit erneut
versendet hat. Rufe die vollständigen Pakete in einem Aufruf mit
`GET /api/v1/shipments?home_kit_order_id={id}` ab – siehe
[Sendungen](https://docs.anivahealth.com/de/concepts/shipments.md).

## Lebenszyklus

Heimtest-Kit-Bestellungen haben vier Lebenszyklus-Status:

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

| Status | Bedeutung |
| - | - |
| `pending` | Die Bestellung wurde angelegt, das Kit ist aber noch nicht verpackt. Sie kann [aktualisiert](https://docs.anivahealth.com/de/api/home-kit-orders/update-home-kit.md) (Adresse, Panel-Wechsel, Metadaten) oder [storniert](https://docs.anivahealth.com/de/api/home-kit-orders/cancel-home-kit.md) werden. |
| `dispatched` | Das Kit ist verpackt und etikettiert – es ist auf dem Weg zum Patienten (oder bereits dort). Die Zusammenstellung aus Panel und Biomarkern ist jetzt **gesperrt**, und du kannst es nicht mehr [stornieren](https://docs.anivahealth.com/de/api/home-kit-orders/cancel-home-kit.md). Aniva kann den Status noch ändern: zurück auf `pending`, wenn ein Kit verloren geht und Aniva ein neues schickt, oder auf `cancelled`, wenn das Paket unzustellbar zurückkommt und nicht erneut verschickt wird. |
| `activated` | Der Patient hat seine Probe entnommen, gemeldet über [Aktivieren](https://docs.anivahealth.com/de/api/home-kit-orders/activate-home-kit.md) mit dem Entnahmezeitpunkt. Der Laborauftrag wird unter dem `lab_code` des Kits ausgelöst. Endstatus – analog zu `blood_drawn` bei einem Termin. |
| `cancelled` | Die Heimtest-Kit-Bestellung wurde storniert: von dir aus `pending` oder von Aniva aus `dispatched`, wenn das Paket unzustellbar zurückkam. Endstatus – keine weiteren Übergänge, und eine erneute Stornierung hat keinen Effekt und gibt die Bestellung zurück. |

Wenn Aniva ein verlorenes Kit erneut verschickt, geht die Bestellung zurück auf `pending`, behält aber ihren `lab_code` und ihre
früheren Pakete in `shipments`. Das neue Kit trägt denselben Code. Ein unbenutztes Rücksendeetikett liegt im
neuen Paket. Nur Aniva führt diese beiden Statuswechsel durch; die API bietet sie nicht an. Jeder Wechsel sendet einen
`home_kit_order.pending`- oder `home_kit_order.cancelled`-[Webhook](https://docs.anivahealth.com/de/concepts/webhooks.md).

> [!NOTE]
>
> Der Status einer Heimtest-Kit-Bestellung ist bewusst grob gehalten. Der Versandverlauf zum und vom
> Patienten wird über die [Sendungen](https://docs.anivahealth.com/de/concepts/shipments.md) der Bestellung verfolgt – `dispatched` bedeutet, dass das Kit
> ein Etikett und einen Laborcode hat, nicht dass es bereits unterwegs ist; der `status` der Hinsendung zeigt, ob
> das der Fall ist. Die Verarbeitung der Laborergebnisse läuft über Einsendungen. Der Abschluss der Laborergebnisse (`in_progress` vs.
> `completed`) ist über [Ergebnisse abrufen](https://docs.anivahealth.com/de/api/home-kit-orders/get-results.md) abrufbar – das `status`-Feld auf oberster
> Ebene bleibt `in_progress`, bis jede Einsendung abgeschlossen ist, und wechselt dann auf `completed` – oder auf `fault`, wenn
> jede Einsendung ohne Ergebnis fehlgeschlagen ist.

## Pakete verfolgen

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

Was zurückkommt, hängt vom Kit ab. Ein Blut-Kit erscheint als zwei Sendungen, sobald Aniva es verpackt
hat: das Paket von Aniva an den Patienten und das vom
Patienten an das Labor (seine `destination` ist das Labor), verknüpft über `paired_with`. Das
Rücksendepaket bleibt auf `pending` – mit bereits bekannter Sendungsnummer –, bis der Patient es
abschickt. Ein Darmmikrobiom-Kit erscheint als eine Sendung: das Kit an den Patienten. Sein Rücksendeumschlag ist
vorfrankiert und ohne Sendungsverfolgung, sodass für den Rückweg nichts gebucht wird. `booked_by` gibt an, wer das
Etikett gebucht hat: `"aniva"` oder `"external"`. Nur ein `"aniva"`-Paket lässt sich hier ändern, und nach dem Druck des Etiketts
nur noch seine `notes`. Jedes Paket enthält alle `status_updates` des Versanddienstleisters,
einschließlich des `detail_code` von DHL bei einer Umleitung in eine Postfiliale.

`home_kit_orders` an der Sendung listet nur die Bestellungen in deinem Zugriffskontext auf. Siehe
[Zugriff](https://docs.anivahealth.com/de/concepts/shipments.md#zugriff).

> [!WARNING]
>
> Die Zusammenstellung einer Heimtest-Kit-Bestellung lässt sich nur ändern, solange sie auf `pending` steht. Sobald die Bestellung
> `dispatched` ist (oder später – `activated`/`cancelled`), geben Panel-Wechsel und die `/biomarkers`-Endpunkte
> `409 Conflict` zurück: Das physische Kit wird anhand des gewählten Panels gepackt, sodass sein Inhalt
> feststeht, sobald es auf dem Weg zum Patienten ist. Falls du die Tests einer bereits gesperrten
> Bestellung doch noch ändern musst, melde dich direkt bei Aniva – meist ist das noch möglich, und wir nehmen die
> Änderung für dich vor, damit der Inhalt des Kits konsistent bleibt. Wenn das Kit bereits verwendet wurde und
> keine Ergebnisse liefern konnte, bestelle stattdessen ein [Ersatz-Kit](#ersatz-kits).

## Heimtest-Kit-Bestellungen auflisten

Rufe alle Heimtest-Kit-Bestellungen ab, auf die dein API-Schlüssel Zugriff hat:

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

Übergib optional `?profile_id={uuid}`, um nach einem bestimmten Profil zu filtern, oder `?lab_code={code}`, um
ein vorliegendes physisches Kit seiner Bestellung zuzuordnen – der typische erste Schritt bei der Aktivierung.

## Heimtest-Kit-Bestellung anlegen

Fordere eine Heimtest-Kit-Bestellung für ein Patientenprofil an:

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

Übergib die `profile_id`, eine `delivery_address` und eine einzelne `panel_id`. Die Bestellung wird im Status `pending` angelegt.

Übergib optional einen `Idempotency-Key`-Header, damit ein erneuter Versuch kein zweites Kit bestellt – siehe [Idempotenz](https://docs.anivahealth.com/de/concepts/idempotency.md).

Genau ein Panel, denn ein Heimtest-Kit entspricht 1:1 einem physischen Kit-Produkt – das Panel ist das Kit. Bestellbar sind nur Panels, die Aniva als Heimtest-Kits konfiguriert hat; jedes andere Panel wird mit `422` abgelehnt. Es ist bereits beim Anlegen erforderlich, weil die Bestellung sofort in die Packwarteschlange gelangt und direkt gepackt werden kann. Solange die Bestellung auf `pending` steht, kannst du das Panel über [Aktualisieren](https://docs.anivahealth.com/de/api/home-kit-orders/update-home-kit.md) wechseln.

Um ein zweites Kit für eines zu verschicken, das keine Ergebnisse liefern konnte, übergib `replaces_home_kit_order_id` statt ein Panel auszuwählen – siehe [Ersatz-Kits](#ersatz-kits).

## Ersatz-Kits

Manchmal kann ein Kit keine Ergebnisse liefern: Der Patient konnte das Röhrchen nicht füllen, die Probe kam mit zu wenig Material an oder das Labor konnte einen Teil nicht auswerten. Bestelle dafür ein **Ersatz-Kit**:

```
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]
}
```

Ein Ersatz-Kit ist eine **neue Bestellung mit einem neuen Laborcode**, auch wenn das erste Kit nie aktiviert wurde: Das Labor braucht einen neuen Auftrag, und zwei Proben unter demselben Code lassen sich nicht auseinanderhalten. Beide Bestellungen bleiben abrufbar und sind über `replaces_home_kit_order_id` verknüpft.

**Die ersetzte Bestellung bleibt unverändert.** Sie behält ihren Status, ihren Laborcode und alle bereits eingegangenen Ergebnisse, sodass ein Patient, der das erste Kit doch noch abschickt, alles erhält, was das Labor daraus auswerten kann.

**Das Panel wird übernommen.** Lässt du `panel_id` weg, erhält das Ersatz-Kit das Panel der ersetzten Bestellung – das hat der Patient gekauft, und danach ist die Box gestaltet. Sende ein anderes Panel nur bei einem vollständigen Panel-Ersatz; ein Panel zusammen mit einer Marker-Teilmenge wird mit `422` abgelehnt, weil eine Teilmenge nur im Kontext des Panels gilt, aus dem sie stammt. Das Panel eines Ersatz-Kits lässt sich auch im Nachhinein nicht mehr wechseln.

**Du entscheidest, was wiederholt wird.** Sende `biomarker_ids` mit den fehlgeschlagenen Markern, und das Labor analysiert nur diese erneut, sodass das Kit nur die dafür nötigen Röhrchen enthält. Lass das Feld weg, um das gesamte Panel zu wiederholen – die richtige Wahl, wenn gar nichts ausgewertet wurde. Dafür ist kein zusätzlicher Scope nötig: Marker erneut zu testen, für die der Patient bereits bezahlt hat, ist keine À-la-carte-Auswahl. Diese Marker lassen sich nachträglich nicht entfernen, da sie den gesamten Auftrag ausmachen.

> [!NOTE]
>
> Marker werden in den **Gruppen** des Panels wiederholt, nicht einzeln. Wenn du einen Marker einer Gruppe angibst, wird
> die gesamte Gruppe erneut getestet, weil ein Laborauftrag, der mehr meldet als angefordert, nicht
> aufgegeben werden kann. Ein Ersatz-Kit für einen einzelnen Marker kann daher mehrere Ergebnisse liefern, und
> die Anzahl der Röhrchen kann größer sein, als die Markerliste vermuten lässt.

Es darf immer nur ein Ersatz-Kit pro Kit unterwegs sein – solange ein Ersatz-Kit auf `pending` oder `dispatched` steht, gibt eine zweite Anfrage für dieselbe Bestellung `409` mit Verweis darauf zurück. Die Ergebnisse gehen unter dem eigenen `lab_code` des Ersatz-Kits über dessen eigenes [Ergebnisse abrufen](https://docs.anivahealth.com/de/api/home-kit-orders/get-results.md) ein.

Ein Ersatz-Kit ist nicht für ein Paket gedacht, das nie angekommen ist. Gib stattdessen Aniva Bescheid: Das ist ein erneuter Versand derselben Bestellung unter demselben Laborcode, keine neue Bestellung.

## Heimtest-Kit-Bestellung aktualisieren

Ändere die Lieferadresse, wechsle das Panel, aktualisiere deine Metadaten oder tausche die E-Mail-Adressen für Ergebnisbenachrichtigungen aus:

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

Gib nur die Felder an, die du ändern möchtest. `panel_id` **ersetzt** das hinterlegte Panel – bei genau einem Panel pro Kit ist ein Wechsel die einzig sinnvolle Panel-Aktion, weshalb es keine Endpunkte zum Hinzufügen oder Entfernen von Panels gibt. Adresse und Panel lassen sich nur ändern, solange der Status `pending` ist; `metadata` bleibt über die gesamte Lebensdauer der Bestellung beschreibbar. `results_ready_emails` bleibt beschreibbar, bis die Bestellung `cancelled` ist.

## Heimtest-Kit-Bestellung stornieren

Storniere eine Heimtest-Kit-Bestellung, die nicht mehr benötigt wird:

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

Dadurch wird der Status der Heimtest-Kit-Bestellung auf `cancelled` gesetzt. Die stornierte Heimtest-Kit-Bestellung wird in der Antwort zurückgegeben.

Nur eine Bestellung im Status `pending` lässt sich stornieren. Ab `dispatched` ist das Kit verpackt und etikettiert – einen automatischen Rückruf gibt es nicht – und der Aufruf gibt `409` zurück. Wenn ein bereits versendetes Kit gestoppt werden muss, melde dich direkt bei Aniva.

Wird eine `pending`-Bestellung storniert, deren Kit bereits beim Fulfillment in Auftrag gegeben wurde, wird sie auch dort storniert, und der Aufruf ist nur erfolgreich, wenn das Fulfillment zustimmt:

* `409` – das Kit wurde bereits verpackt und etikettiert und lässt sich nicht mehr zurückrufen, auch wenn die Bestellung noch auf `pending` steht.
* `502` – das Fulfillment hat die Stornierung abgelehnt (die Fehlermeldung enthält die Begründung) oder war nicht erreichbar. **Nichts wurde geändert** – die Bestellung ist weiterhin aktiv und kann erneut storniert werden.

Eine Stornierung mit Fehler lässt die Bestellung exakt so, wie sie war; nur ein `200` bestätigt, dass kein Kit mehr verschickt wird.

Das Stornieren einer bereits auf `cancelled` stehenden Bestellung gibt dasselbe `200` zurück, unabhängig davon, aus welchem Status heraus sie storniert wurde.

## Heimtest-Kit-Bestellung aktivieren

Sobald der Patient seine Probe entnommen hat, melde es:

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

Übergib `activated_at` – den Zeitpunkt, zu dem der Patient die Probe tatsächlich entnommen hat, als UTC-Zeitpunkt. Das ist der Entnahmezeitpunkt, der im Laborbericht steht; sende also den tatsächlichen Zeitpunkt der Entnahme, nicht deine Verarbeitungszeit. Die Aktivierung ist endgültig: Die Bestellung wechselt auf `activated` und kann nicht mehr storniert oder geändert werden. Das Heimtest-Kit-Gegenstück zu [Blutabnahme bestätigen](https://docs.anivahealth.com/de/api/appointments/confirm-blood-draw.md), ohne Barcode – der Code des Kits wird beim Verpacken angebracht, sodass du ihn nie kennen musst. Die Bestellung muss bis dahin ihren `lab_code` haben; eine Bestellung ohne Code gibt `409` zurück.

Durch die Aktivierung wird auch der Laborauftrag ausgelöst: Das Panel des Kits wird unter seinem `lab_code` im Labor bestellt, sodass die zurückgesendete Probe erwartet wird und die Ergebnisse beim Eingang direkt zugeordnet werden. Das geschieht nach der Antwort, und ein laborseitiges Problem wird von Aniva gelöst statt in deiner Anfrage angezeigt.

## Einzelne Biomarker

Du kannst einer Heimtest-Kit-Bestellung einzelne Biomarker als À-la-carte-Tests außerhalb des Panels hinzufügen. Das ist hilfreich, wenn du zusätzlich zum Kit eine individuelle Auswahl möchtest. Die hinzugefügten Biomarker erscheinen in der Antwort der Heimtest-Kit-Bestellung als Array `individual_biomarkers` (auf derselben Ebene wie `panels`).

Beide Biomarker-Endpunkte erfordern zusätzlich zu `home_kit_orders_manage` den Capability-Scope `home_kit_orders_individual_biomarker_selection` – Heimtest-Kits werden pro Panel bestellt, daher werden einzelne Marker pro Partner freigeschaltet. Frag Aniva, wenn deine Integration das braucht.

Biomarker hinzufügen (idempotent – bereits hinzugefügte Biomarker bleiben erhalten):

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

Biomarker entfernen (idempotent – eine nicht zugeordnete ID wird ignoriert):

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

Beide Endpunkte erwarten ein `biomarker_ids`-Array. Nutze [Biomarker auflisten](https://docs.anivahealth.com/de/api/biomarkers/list-biomarkers.md) mit `home_kit=true`, um Biomarker-IDs zu finden. Biomarker können nur geändert werden, solange das Kit `pending` ist (siehe [Lebenszyklus](#lebenszyklus)).

## Laborergebnisse abrufen

Sobald das Labor die zurückgesendete Probe verarbeitet hat, ruf die klinischen und genetischen Ergebnisse ab:

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

Die Antwort enthält neben den eingegangenen Ergebnissen auch geplante Tests (Status `planned`), sodass du verfolgen kannst, was noch aussteht. Ergebnisse werden unter dem `lab_code` der Bestellung abgelegt und treffen Marker für Marker ein, während das Labor sie analysiert, sodass Teil-Payloads normal sind. Das `status`-Feld auf oberster Ebene ist bis zum Abschlussbericht `in_progress`, danach `completed` (oder `fault`, wenn jeder Laborauftrag ohne Bericht fehlgeschlagen ist) – darüber erkennst du, ob die Laborarbeit für die Heimtest-Kit-Bestellung abgeschlossen ist. Ein `home_kit_order.results.completed`-[Webhook](https://docs.anivahealth.com/de/concepts/webhooks.md) benachrichtigt dich, sobald es so weit ist, sodass du nicht pollen musst. Laborbericht-PDFs werden im `documents`-Array referenziert – nutze `GET /api/v1/documents/{id}`, um sie herunterzuladen.

## Beispiel für eine Heimtest-Kit-Bestellung

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