Felder
Von Aniva automatisch generierte UUID. Nutze sie, um Panels hinzuzufügen, die Blutabnahme zu bestätigen und Ergebnisse abzurufen.
Die UUID des Teststandorts, an dem die Blutabnahme stattfindet. Heimtest-Kits sind keine Termine – siehe
Heimtest-Kit-Bestellungen.
Geplanter Zeitpunkt der Blutabnahme im ISO-8601-Format. Wird immer als UTC-Zeitpunkt mit dem Suffix
Z
zurückgegeben (z. B. 2026-04-15T08:30:00Z). Beim Erstellen / Aktualisieren muss der Wert eine Zeitzonenangabe
enthalten (entweder Z oder einen expliziten Offset wie +02:00) – Zeitangaben ohne Zeitzone werden abgelehnt. Muss
in der Zukunft liegen und an von Aniva betriebenen Standorten mindestens 12 Stunden im Voraus (Mindestvorlaufzeit).Aktueller Lebenszyklus-Status. Einer der Werte
pending, confirmed, blood_drawn oder cancelled. Siehe
Lebenszyklus unten. Der genaue Bearbeitungsstand der Laborergebnisse (in_progress vs. completed) ergibt
sich aus Ergebnisse abrufen; den detaillierten Sendungsverlauf (unterwegs,
zugestellt usw.) erhältst du, indem du jedem Eintrag im eingebetteten shipments-Array zu
Sendung abrufen folgst.Freitextgrund, der bei der Stornierung des Termins erfasst wurde (z. B. Nichterscheinen, späte Stornierung,
‘Fehlgeschlagen. Wiederholung erforderlich’).
null, sofern status nicht cancelled ist.Adressen in Kleinbuchstaben, die jeweils eine E-Mail erhalten, sobald alle Laborergebnisse final sind. Leer, wenn deaktiviert. Siehe
E-Mails bei fertigen Ergebnissen.
Art der Blutabnahme:
capillary (aus der Fingerkuppe oder dem Oberarm, in Microtainer) oder venous (aus der Vene,
in Röhrchen). Entspricht der im Termin festgelegten Methode, sonst der default_draw_method des
Standorts. Nach der Blutabnahme ist es die verwendete Methode.ISO-8601-Zeitstempel der letzten Aktualisierung. Null, falls der Termin noch nie aktualisiert wurde.
Laborcodes (Röhrchen-Barcodes), die bei Blutabnahme bestätigen
erfasst wurden, in Scan-Reihenfolge. Leer, bis die Blutabnahme bestätigt ist. Bei einer venösen Blutabnahme ist ein Code auf jedem
Röhrchen aufgedruckt; bei einer kapillaren Blutabnahme gibt es einen Code pro Mikroröhrchen. Ergebnisse und Dokumente verweisen über
lab_code darauf.Panels, die diesem Termin zugeordnet sind, als
{ panel_id, added_at }-Einträge. Siehe
Panels hinzufügen.Einzeln gebuchte Biomarker, die diesem Termin zugeordnet sind, als
{ biomarker_id, added_at }-Einträge. Siehe
Einzelne Biomarker.Sendungen, die mit diesem Termin verknüpft sind, als
{ id, added_at }-Einträge, älteste Verknüpfung zuerst. Siehe
Sendungen verknüpfen.Das vollständige Profilobjekt des Patienten, eingebettet in jeder Terminantwort. Die folgenden Felder
sind eine Teilmenge. Termin abrufen listet alle auf.
Lebenszyklus
Termine haben vier Lebenszyklus-Zustände:Der Terminstatus ist bewusst grob gehalten – detailliertere Fortschritte sind über
eigene Endpunkte abrufbar:
- Bearbeitungsstand der Laborergebnisse →
Ergebnisse abrufen – das oberste
status-Feld istin_progressodercompleted. - Sendungsverlauf (unterwegs, zugestellt usw.) → folge jedem Eintrag im eingebetteten
shipments-Array des Termins zu Sendung abrufen – jede Sendung hat ihren eigenenstatusund einstatus_updates-Ereignisprotokoll.
appointment.*-Webhook, zum Beispiel
appointment.confirmed. Eine neue Uhrzeit oder ein neuer Standort sendet appointment.rescheduled.Termine auflisten
Rufe alle Termine ab, auf die dein API-Schlüssel Zugriff hat:?profile_id={uuid}, um nach einem bestimmten Profil zu filtern. Ohne diesen Parameter gilt ein Standard-Zeitfenster (die letzten 2 Monate bis 1 Monat in die Zukunft).
Termin aktualisieren
Bevor die Blutabnahme bestätigt ist, kannst du den Termin verschieben oder den Teststandort ändern:scheduled_at, location_id, draw_method und results_ready_emails. Gib nur die Felder an, die du ändern möchtest.
Abnahmemethode
Jeder Termin hat einedraw_method: capillary (Fingerkuppe oder Oberarm, in Mikroröhrchen) oder
venous (aus der Vene, in Röhrchen). Sie gilt nur für die Blutabnahme. Urinproben, Abstriche und andere
Nicht-Blutproben werden bei beiden Methoden auf die gleiche Weise genommen.
Standardmäßig ist das die default_draw_method des Standorts. Setze draw_method beim Erstellen oder Aktualisieren, um
eine andere Methode zu nutzen, oder setze es auf null, um zur Standardeinstellung des Standorts zurückzukehren. Der Standort muss
die Methode in draw_methods auflisten und die gebuchten Tests müssen damit möglich sein, sonst gibt die Anfrage
400 zurück. Nach der Blutabnahme kannst du sie nicht mehr ändern. Nach der Blutabnahme ist draw_method die
Methode, die verwendet wurde.
Ein Termin pro Profil, Standort und Zeitpunkt
Ein Profil hat höchstens einen nicht stornierten Termin pro(location_id, scheduled_at)-Paar – einer
Person kann nicht am selben Ort zur selben Zeit zweimal Blut abgenommen werden, unabhängig davon, wie viele parallele Buchungen der
Standort zulässt.
Sowohl Termin erstellen als auch
Termin aktualisieren setzen das durch und geben 409 mit einer
appointment_id zurück, die auf den bereits bestehenden Termin verweist. Behandle diese Antwort als bereits
gebucht statt als Fehler für einen erneuten Versuch: Rufe den genannten Termin ab, verschiebe ihn oder storniere ihn.
In der Praxis ist wiederholtes Erstellen sicher. Eine Anfrage, die du nach einem Netzwerk-Timeout
erneut sendest oder die ein Nutzer zweimal auslöst, ergibt einen einzigen Termin statt zwei – wodurch
du doppelte Buchungen für denselben Patienten nie nachträglich bereinigen musst.
Änderungen sind nur vor der Blutabnahme erlaubt – also solange der Termin den Status
pending
oder confirmed hat. Sobald der Termin auf blood_drawn steht oder cancelled wurde, lässt er
sich nicht mehr ändern. Die einzige Ausnahme ist results_ready_emails: Dieses Feld kannst du
auch nach der Blutabnahme noch allein ändern.Termin stornieren
Storniere einen Termin, der nicht mehr benötigt wird:cancelled gesetzt. Der stornierte Termin wird in der Antwort zurückgegeben.
Optional kannst du im Body eine cancellation_reason (bis zu 500 Zeichen) als Grund mitsenden. Sie
wird am Termin gespeichert und bei späteren Lesezugriffen als cancellation_reason zurückgegeben.
Eine Stornierung ist nur vor der Blutabnahme erlaubt – also solange der Termin den Status
pending oder confirmed hat. Termine, die bereits auf blood_drawn stehen, lassen sich nicht
mehr stornieren.Panels hinzufügen
Bevor du die Blutabnahme bestätigst, füge die gewünschten Bluttest-Panels mit diesem Aufruf hinzu:panel_ids ein Array aus Panel-UUIDs. Die Panel-IDs erhältst du von Aniva für dein Partnerkonto.
Panels müssen vor der Blutabnahme hinzugefügt werden – also solange der Termin den Status
pending oder confirmed hat. Sobald der Termin auf blood_drawn steht, kannst du keine Panels
mehr hinzufügen oder ändern.Panels entfernen
Wenn du vor der Blutabnahme Panels entfernen musst, rufe diesen Endpunkt auf:panel_ids ein Array aus Panel-UUIDs. Das Entfernen ist idempotent: Ein nicht hinzugefügtes Panel wird ignoriert.
Wie beim Hinzufügen ist das Entfernen nur vor der Blutabnahme erlaubt – also solange der Termin
den Status
pending oder confirmed hat. Sobald der Termin auf blood_drawn steht, lassen sich
keine Panels mehr entfernen.Einzelne Biomarker
Du kannst einzelne Biomarker als À-la-carte-Tests zu einem Termin hinzufügen, unabhängig von vorgefertigten Panels. Das ist praktisch, wenn ein Behandler statt einer vorgegebenen Zusammenstellung eine individuelle Auswahl möchte. Die hinzugefügten Biomarker erscheinen in der Terminantwort als Arrayindividual_biomarkers (auf derselben Ebene wie panels). Die Routing-Entscheidungen trifft nachgelagert die Bestelllogistik-Pipeline anhand der jeweiligen Laborzuordnungen pro Biomarker.
Biomarker hinzufügen (idempotent – bereits hinzugefügte Biomarker bleiben erhalten):
biomarker_ids-Array und prüfen die resultierende Auswahl gegen die Vollständigkeitsregeln jedes Labors – lässt sich ein Auftrag nicht sauber platzieren (z. B. ein CRP/HDL-Verhältnis ohne CRP und HDL), gibt der Endpunkt 400 mit den zusätzlich erforderlichen Biomarkern zurück und speichert nichts. Nutze Biomarker auflisten, um Biomarker-IDs zu finden.
Wie bei Panel-Änderungen können einzelne Biomarker nur vor der Blutabnahme hinzugefügt oder
entfernt werden – also solange der Termin den Status
pending oder confirmed hat. Sobald der
Termin auf blood_drawn steht, ist der individuelle Snapshot eingefroren.Vorschau der benötigten Probengefäße
Nachdem du Panels oder einzelne Biomarker hinzugefügt hast, kannst du dir vorab anzeigen lassen, welche physischen Probengefäße für die Probenahme benötigt werden:containers-Array der Antwort enthält Typ, Namen, Kappenfarbe, Volumen, Hersteller-Artikelnummer und Anzahl für jedes benötigte Gefäß. So können Behandler vor der Blutabnahme das richtige Material vorbereiten. Die Antwort enthält außerdem ein pricing-Objekt – die Gesamtabrechnung für den Termin (die angefallenen Positionen, die hinzugefügten Panels und eine Zeile pro geliefertem Biomarker, jeweils mit deinem Tarifpreis neben dem Endkundenpreis; siehe Preise), das befüllt wird, wenn der Termin hinzugefügte Tests hat und dein Key den Scope prices_view besitzt, andernfalls null. routing wird bewusst nie ausgegeben und ist immer null.
Die Vorschau spiegelt die aktuell hinzugefügten Panels und Biomarker wider. Wenn du danach Panels
hinzufügst oder entfernst, rufe den Vorschau-Endpunkt erneut auf, um aktualisierte Angaben zu den
benötigten Probengefäßen zu erhalten.
Blutabnahme bestätigen
Übermittle nach der Blutabnahme die Laborcodes (Röhrchen-Barcodes), um die Laborauftrags-Pipeline auszulösen:lab_code, wenn auf allen Röhrchen derselbe Code steht (venöse Blutabnahme), oder lab_codes
mit einem Eintrag pro Code – jeweils mit den abgedeckten panel_ids –, wenn jedes Panel in eigene
Röhrchen mit eigenem Code abgenommen wird (kapillare Blutabnahme). Jedes Panel bildet dann unter
seinem Code einen eigenen Laborauftrag. Die Codes werden am Termin als lab_codes zurückgegeben.
Bei einer kapillaren Blutabnahme wird die Probe auf Mikrotainer aufgeteilt. Zuerst kommen die Panels,
in Buchungsreihenfolge. Einzelne Biomarker füllen dann den freien Platz in den Panel-Mikrotainern.
Wenn sie mehr Platz brauchen, kommen neue Mikrotainer hinzu. Wir verteilen sie gleichmäßig. Jeder
Mikrotainer fasst höchstens 150 µl an einzelnen Biomarkern. Aufrufe, die Panels oder Biomarker
ändern, antworten mit 400, wenn die resultierende Auswahl gegen diese Regel verstößt.
Dadurch wechselt der Terminstatus zu blood_drawn und die Laborverarbeitung wird gestartet. Diese Aktion lässt sich nicht rückgängig machen.
Sendungsabholung
Um den Verlauf nach der Blutabnahme zu verfolgen, folge jedem Eintrag im eingebettetenshipments-Array
des Termins zu Sendung abrufen – jede Sendung hat ihren eigenen
status und einen status_updates-Verlauf.
Sendungen verknüpfen
Ein Termin kann mit einer oder mehreren Sendungen verknüpft sein (und umgekehrt – es handelt sich um eine n:m-Beziehung). Die aktuellen Verknüpfungen erscheinen eingebettet auf beiden Seiten:- am Termin als
shipments-Array mit{ id, added_at }-Einträgen; - an der Sendung als
appointments-Array mit{ id, added_at }-Einträgen.
id verweist für die vollständige
Payload auf den jeweiligen Detail-Endpunkt (Sendung abrufen /
Termin abrufen).
Sendungen werden beim Erstellen über das Feld appointment_id in
Sendung erstellen verknüpft. Danach verwaltest du Verknüpfungen
von der Sendung aus mit Termine mit Sendung verknüpfen
und Termine von Sendung trennen; beide geben die
aktualisierte Terminliste für diese Sendung zurück. Um die Sendungen eines Termins vollständig
abzurufen, nutze Sendungen auflisten mit ?appointment_id=.
Für Änderungen gilt: Verknüpfungen können erstellt oder entfernt werden, wenn ENTWEDER
- der Termin nach der Blutabnahme liegt (
blood_drawn) oder - die Sendung vor weniger als 24 Stunden erstellt wurde.
Laborergebnisse abrufen
Sobald das Labor die Blutproben verarbeitet hat, rufe klinische und genetische Ergebnisse ab:planned),
damit du nachverfolgen kannst, was noch aussteht. Das übergeordnete Feld status ist in_progress,
bis jede Einreichung abgeschlossen ist, und danach completed (oder fault, wenn keine Ergebnisse
gemeldet wurden) – daran erkennst du, ob die Laborarbeit für den Termin abgeschlossen ist. Ein
appointment.results.completed-Webhook informiert dich, sobald es so weit
ist, sodass du nicht pollen musst. Das Array submissions schlüsselt dies pro Laborauftrag auf,
jeweils mit eigenem lab_code. Jedes eingegangene Ergebnis und Dokument trägt den lab_code, unter
dem es eingereicht wurde. PDFs der Laborberichte sind im Array documents referenziert – lade sie
mit GET /api/v1/documents/{id} herunter.