Zum Hauptinhalt springen
Ein Termin ist eine geplante Blutabnahme für ein Patientenprofil an einem physischen Teststandort, durchgeführt von einer medizinischen Fachkraft. Kits, die per Post an einen Patienten gesendet werden, sind keine Termine – siehe Heimtest-Kit-Bestellungen.

Felder

string
erforderlich
Von Aniva automatisch generierte UUID. Nutze sie, um Panels hinzuzufügen, die Blutabnahme zu bestätigen und Ergebnisse abzurufen.
string
erforderlich
Die UUID des Profils, zu dem dieser Termin gehört.
string
Die UUID des Teststandorts, an dem die Blutabnahme stattfindet. Heimtest-Kits sind keine Termine – siehe Heimtest-Kit-Bestellungen.
string
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).
string
erforderlich
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.
string
Freitextgrund, der bei der Stornierung des Termins erfasst wurde (z. B. Nichterscheinen, späte Stornierung, ‘Fehlgeschlagen. Wiederholung erforderlich’). null, sofern status nicht cancelled ist.
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
erforderlich
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.
string
erforderlich
ISO-8601-Zeitstempel der Erstellung des Termins.
string
ISO-8601-Zeitstempel der letzten Aktualisierung. Null, falls der Termin noch nie aktualisiert wurde.
string[]
erforderlich
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.
object[]
erforderlich
Panels, die diesem Termin zugeordnet sind, als { panel_id, added_at }-Einträge. Siehe Panels hinzufügen.
object[]
erforderlich
Einzeln gebuchte Biomarker, die diesem Termin zugeordnet sind, als { biomarker_id, added_at }-Einträge. Siehe Einzelne Biomarker.
object[]
erforderlich
Sendungen, die mit diesem Termin verknüpft sind, als { id, added_at }-Einträge, älteste Verknüpfung zuerst. Siehe Sendungen verknüpfen.
object
erforderlich
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 ist in_progress oder completed.
  • Sendungsverlauf (unterwegs, zugestellt usw.) → folge jedem Eintrag im eingebetteten shipments-Array des Termins zu Sendung abrufen – jede Sendung hat ihren eigenen status und ein status_updates-Ereignisprotokoll.
Jede Statusänderung sendet einen appointment.*-Webhook, zum Beispiel appointment.confirmed. Eine neue Uhrzeit oder ein neuer Standort sendet appointment.rescheduled.
Das Bestätigen eines Termins (Wechsel zu blood_drawn) ist unumkehrbar. Sobald du den oder die Laborcodes übermittelst, wird die Laborauftrags-Pipeline gestartet und lässt sich nicht mehr rückgängig machen. Aktualisierungen und Stornierungen sind nur erlaubt, solange der Termin den Status pending oder confirmed hat.

Termine auflisten

Rufe alle Termine ab, auf die dein API-Schlüssel Zugriff hat:
Übergib optional ?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:
Übergib zum Aktualisieren eine beliebige Kombination aus scheduled_at, location_id, draw_method und results_ready_emails. Gib nur die Felder an, die du ändern möchtest.

Abnahmemethode

Jeder Termin hat eine draw_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:
Dadurch wird der Terminstatus auf 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:
Übergib im Feld 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:
Übergib im Feld 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 Array individual_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 entfernen (idempotent – nicht hinzugefügte Biomarker werden ignoriert):
Beide Endpunkte erwarten ein 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:
Das 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:
Sende 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

POST /api/v1/appointments/pickup wurde entfernt, ebenso der Terminstatus shipment_picked_up. Der Endpunkt antwortet jetzt mit 405 Method Not Allowed, weil der Pfad an die Route für Termine nach ID durchgereicht wird. In seiner letzten Phase war der Endpunkt ein No-op, der den Aufruf annahm und nichts tat – das Entfernen ändert also kein Verhalten, auf das du dich verlassen hast.
Um den Verlauf nach der Blutabnahme zu verfolgen, folge jedem Eintrag im eingebetteten shipments-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.
Beide Arrays beginnen mit der ältesten Verknüpfung. Jede 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.
Außerhalb dieses Zeitfensters ist die Verknüpfung gesperrt, damit historische Datensätze unverändert bleiben.

Laborergebnisse abrufen

Sobald das Labor die Blutproben verarbeitet hat, rufe klinische und genetische Ergebnisse ab:
Die Antwort enthält neben den eingegangenen Ergebnissen auch geplante Tests (Status 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.

Beispieltermin