Zum Hauptinhalt springen
POST
Fordere eine Heimtest-Kit-Bestellung für ein Patientenprofil an. Mit einer Heimtest-Kit-Bestellung wird ein Test-Kit für zu Hause per Post verschickt – Aniva schickt das Kit an die Lieferadresse, der Patient nimmt zu Hause selbst eine Probe und schickt sie per Post zurück. Das unterscheidet sich von einem Termin, bei dem eine venöse Blutabnahme an einem Teststandort stattfindet. Es ist genau ein Panel erforderlich. Ein Heimtest-Kit entspricht 1:1 einem physischen Kit-Produkt – das Panel ist das Kit – und die Bestellung geht direkt nach der Erstellung in die Packwarteschlange, daher muss die Zusammensetzung von Anfang an feststehen. Solange die Bestellung pending ist, kannst du das Panel noch über Heimtest-Kit-Bestellung aktualisieren wechseln.

Ersatz-Kits

Wenn ein Kit keine Ergebnisse liefern kann – der Patient konnte das Röhrchen nicht füllen, die Probe kam mit zu wenig Material an, das Labor konnte sie nicht analysieren –, bestelle Ersatz, indem du replaces_home_kit_order_id sendest. Ein Ersatz 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. Die Bestellung, die du ersetzt, bleibt unberührt – sie behält ihren eigenen Status, ihren eigenen Laborcode und alle Ergebnisse, die bereits darunter erfasst wurden. Daraus ergeben sich zwei Dinge:
  • Das Panel wird übernommen. Lässt du panel_id weg, übernimmt der Ersatz das Panel der ersetzten Bestellung – genau das, was der Patient gekauft hat und welches Branding die Box trägt.
  • Du wählst aus, was erneut analysiert 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 es weg, um das gesamte Panel erneut zu analysieren.
Marker werden als Gruppen des Panels erneut analysiert, nicht einzeln. Wenn du einen Marker einer Gruppe angibst, wird diese gesamte Gruppe erneut analysiert, weil kein Laborauftrag erstellt werden kann, der mehr meldet als angefordert wurde. Ein Ersatz für einen einzelnen Marker kann daher mit mehr als einem Ergebnis eintreffen, und die Anzahl der Röhrchen kann größer sein, als die Markerliste vermuten lässt. Pro Kit darf immer nur ein Ersatz gleichzeitig unterwegs sein.
Wenn du vor der Einführung dieser Felder integriert hast, liest Aniva beim Erstellen auch metadata.original_kit_id und metadata.replacement_reason aus und behandelt die Bestellung als Ersatz. Das ist die einzige Stelle, an der Metadaten interpretiert werden, sie dient nur der Unterstützung dieser früheren Integration, und die Felder oben haben immer Vorrang. Sende die Felder.
Ein 201 bedeutet, dass die Bestellung verbindlich angelegt ist und ans Fulfillment übergeben wird – du musst nichts weiter tun, damit das Kit gepackt und verschickt wird. Erfordert den Scope home_kit_orders_manage. Sende einen optionalen Idempotency-Key-Header, damit sich das Erstellen sicher wiederholen lässt – bei Wiederholung mit demselben Schlüssel kommt die ursprüngliche Antwort zurück, statt einen zweiten Termin zu erstellen. Siehe Idempotenz.

Anfrage

Body-Parameter

string
erforderlich
UUID des Patientenprofils, für das die Heimtest-Kit-Bestellung erstellt wird.
string
erforderlich
UUID des Katalog-Panels, das bestellt werden soll. Genau eines – ein Heimtest-Kit entspricht 1:1 einem physischen Kit-Produkt, das Panel ist also das Kit. Panel-IDs werden von Aniva für dein Partnerkonto bereitgestellt; siehe Panels auflisten. Bei einem Ersatz optional; dort wird standardmäßig das Panel der ersetzten Bestellung verwendet.
string
UUID der Heimtest-Kit-Bestellung, die diese ersetzt. Wenn du sie sendest, wird daraus ein Ersatz-Kit – siehe Ersatz-Kits oben. Die Bestellung muss zum selben Profil gehören, und für sie darf nicht bereits ein Ersatz unterwegs sein.
string
Warum der Ersatz nötig ist, in einem Satz (zum Beispiel Zu wenig Material, HbA1c nicht auswertbar). Erforderlich, wenn du replaces_home_kit_order_id sendest, sonst ignoriert. Höchstens 500 Zeichen.
integer[]
Bei einem Ersatz die Marker, die das Labor erneut analysiert – normalerweise die, die das erste Kit nicht liefern konnte. Jeder muss Teil dessen sein, was die ersetzte Bestellung angefordert hat; gleiche sie über Biomarker auflisten mit home_kit=true ab. Lass es weg, um das gesamte Panel erneut zu analysieren. Wird nur zusammen mit replaces_home_kit_order_id akzeptiert und nicht zusammen mit einer anderen panel_id. Dafür ist kein zusätzlicher Scope nötig: Marker erneut zu analysieren, die der Patient bereits bezahlt hat, ist keine À-la-carte-Auswahl.
object
Deine eigenen Schlüssel-Wert-Paare, die bei jedem Lesezugriff unverändert zurückgegeben und von Aniva nie interpretiert werden. Nutze das Feld für deine Bestellreferenz, damit du Bestellungen zuordnen kannst, ohne unsere IDs zu speichern. 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. Speichere niemals personenbezogene oder klinische Daten in metadata – das Feld wird nicht wie Patientendaten behandelt.
string[]
Bis zu 5 Adressen, die jeweils eine E-Mail erhalten, sobald alle Laborergebnisse final sind. Die E-Mail verlinkt auf die Ergebnisseite im Aniva-Admin-Panel. Dein Schlüssel braucht results_view-Zugriff auf den Patienten, sonst 403. Lass das Feld weg, um die Standardadressen der Gruppe des Patienten zu verwenden. Eine leere Liste schaltet die E-Mails aus. Siehe E-Mails bei fertigen Ergebnissen.
object
erforderlich
Die Adresse, an die das Kit geschickt wird – in einer von zwei Formen: entweder { location_id } als Verweis auf einen bekannten Teststandort oder die Inline-Adressfelder (name, street, city, postal_code, country_code; company_name / house_number / address_line_2 / state / phone / email optional – dasselbe Vokabular 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.

Antwort

Bei Erfolg gibt die API 201 Created mit der neuen Heimtest-Kit-Bestellung zurück.
string
erforderlich
Eindeutige Kennung (UUID) der Heimtest-Kit-Bestellung.
string
erforderlich
UUID des Profils, zu dem diese Heimtest-Kit-Bestellung gehört.
string
erforderlich
Aktueller Status der Heimtest-Kit-Bestellung. Einer der Werte pending, dispatched, activated oder cancelled. Eine neu erstellte Bestellung startet im Status pending.
object
erforderlich
Die Versandadresse für das Kit – 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 direkte Adresse, nicht beides.
object
erforderlich
Die Schlüssel-Wert-Paare, die du angegeben hast. Immer vorhanden – {}, wenn du keine gesetzt hast.
string
Die Heimtest-Kit-Bestellung, die diese ersetzt. Bei einer normalen Bestellung null.
string
Der Grund, den du angegeben hast. Bei einer normalen Bestellung null.
string[]
erforderlich
Adressen in Kleinbuchstaben, die jeweils eine E-Mail erhalten, sobald alle Laborergebnisse final sind. Leer, wenn deaktiviert. Siehe E-Mails bei fertigen Ergebnissen.
string
Labor-Probencode, unter dem die Ergebnisse gemeldet werden – auf dem physischen Kit aufgedruckt und der Aktivierungscode, den der Patient von der Box abliest. null, bis das Kit verpackt ist. Schreibgeschützt.
string
erforderlich
Zeitpunkt der Probenahme, gemeldet über Aktivieren. null, bis das Kit aktiviert wird.
string
erforderlich
ISO-8601-Zeitstempel, wann die Heimtest-Kit-Bestellung erstellt wurde.
string
ISO-8601-Zeitstempel der letzten Aktualisierung. Kann null sein.
object
erforderlich
Das Patientenprofil, das mit dieser Heimtest-Kit-Bestellung verknüpft ist.
HomeKitOrderPanel[]
erforderlich
Das dieser Heimtest-Kit-Bestellung zugeordnete Panel – dasjenige, das du als panel_id angegeben hast, versehen mit dem Erstellungszeitpunkt der Bestellung. Immer genau eines. Rufe Panel-Details (Name, Biomarker) über Panels auflisten ab.
HomeKitOrderIndividualBiomarker[]
erforderlich
Biomarker, die außerhalb des Panels hinzugefügt wurden. Bei einer normalen Erstellung leer – Heimtest-Kit-Bestellungen werden nach Panel bestellt, und das nachträgliche Ändern dieser Liste erfordert den Capability-Scope home_kit_orders_individual_biomarker_selection. Bei einem Ersatz enthält das Feld die von dir gesendeten biomarker_ids, also die Marker, die das Labor erneut analysiert.
HomeKitOrderShipmentLink[]
erforderlich
Pakete, die mit dieser Heimtest-Kit-Bestellung verknüpft sind, beginnend mit der ältesten Verknüpfung. Bei der Erstellung immer leer – rufe die vollständigen Paketdaten über Sendungen auflisten mit ?home_kit_order_id= ab.

Fehlerantworten