Endpunkte für Heimtest-Kit-Bestellungen erfordern den Scope
home_kit_orders_view (Lesen) oder
home_kit_orders_manage (Schreiben). Aktivieren
akzeptiert auch den enger gefassten Scope home_kit_orders_activate.
Ergebnisse abrufen und
Ergebnisse per E-Mail senden erfordern zusätzlich
results_view – Laborergebnisse und Dokumente sind immer dadurch geschützt.Felder
Von Aniva automatisch generierte UUID. Verwende sie, um die Bestellung zu aktualisieren, ihr
Panel zu wechseln, sie zu aktivieren, zu stornieren und Ergebnisse abzurufen.
Aktueller Lebenszyklus-Status. Einer der Werte
pending, dispatched, activated oder
cancelled. Siehe Lebenszyklus unten. Der genaue Bearbeitungsstand der
Laborergebnisse (in_progress vs. completed) ergibt sich aus
Ergebnisse abrufen.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.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.ISO-8601-Zeitstempel der letzten Aktualisierung. Null, wenn die Heimtest-Kit-Bestellung noch nie
aktualisiert wurde.
Das vollständige Profilobjekt des Patienten, eingebettet in jede Antwort einer
Heimtest-Kit-Bestellung.
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 ab.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 mit home_kit=true ab. Bei einer normalen
Bestellung sind dies einzeln gewählte Tests zusätzlich zum Panel; bei einem
Ersatz-Kit sind es die Tests, die das Labor erneut durchführt.Die Heimtest-Kit-Bestellung, die durch diese ersetzt wird, wenn es sich um ein
Ersatz-Kit handelt.
null bei einer normalen Bestellung.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 oder
Aktualisieren fest. Siehe
E-Mails bei fertigen Ergebnissen.
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 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.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). Immer schreibgeschützt. Ordne ein vorliegendes Kit mit
GET /api/v1/home-kit-orders?lab_code=… wieder seiner Bestellung zu.Der über Aktivieren 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.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.Lebenszyklus
Heimtest-Kit-Bestellungen haben vier Lebenszyklus-Status:
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.
Der Status einer Heimtest-Kit-Bestellung ist bewusst grob gehalten. Der Versandverlauf zum und vom
Patienten wird über die Sendungen 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 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
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.
Heimtest-Kit-Bestellungen auflisten
Rufe alle Heimtest-Kit-Bestellungen ab, auf die dein API-Schlüssel Zugriff hat:?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: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.
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 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
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: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.
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.
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 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: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: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 aufpendingsteht.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.
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: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, 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 Arrayindividual_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):
biomarker_ids-Array. Nutze Biomarker auflisten mit home_kit=true, um Biomarker-IDs zu finden. Biomarker können nur geändert werden, solange das Kit pending ist (siehe Lebenszyklus).
Laborergebnisse abrufen
Sobald das Labor die zurückgesendete Probe verarbeitet hat, ruf die klinischen und genetischen Ergebnisse ab: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 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.