Zum Hauptinhalt springen
Nachdem eine Blutabnahme bestätigt wurde und das Labor die Proben verarbeitet hat, stehen die Ergebnisse am Termin bereit. Ergebnisse werden über GET /api/v1/appointments/{id}/results abgerufen und umfassen klinische Biomarker-Ergebnisse, genetische Biomarker-Ergebnisse sowie herunterladbare Laborberichte.

Ergebnisstatus

Das oberste Feld status in der Ergebnisantwort zeigt den gesamten Bearbeitungsfortschritt an: Einzelne Ergebnisse in der Antwort haben einen eigenen Status pro Ergebnis (siehe unten), sodass du Teilergebnisse anzeigen kannst, solange der Gesamtstatus noch in_progress ist. Um zu erfahren, wann sich Ergebnisse ändern, abonniere Webhooks. appointment.results.updated wird bei jeder Änderung am Ergebnis-Body ausgelöst, und appointment.results.completed wird ausgelöst, wenn der oberste Status auf completed wechselt. Heimtest-Kit-Bestellungen senden dieselben Events mit dem Präfix home_kit_order.. Jedes Event enthält die Ergebnis-URL zum Abrufen. Du kannst diesen Endpunkt zum Abgleich weiterhin abfragen. Das Array submissions schlüsselt den obersten Status pro Laboranforderung auf. Eine Blutabnahme über mehrere Röhrchen oder mehrere Labore hat mehrere Einträge, jeweils mit dem lab_code (Röhrchen-Barcode), unter dem sie eingereicht wurde, und einem eigenen Status (in_progress / completed / fault). Ein Eintrag mit dem Status fault wurde vom Labor abgelehnt oder verworfen und meldet nie Ergebnisse: Die Probe wurde häufig an ein anderes Labor weitergeleitet, das dann einen eigenen Eintrag anlegt. Der oberste Status ist completed, sobald jeder Eintrag abgeschlossen ist und mindestens einer Ergebnisse gemeldet hat. Jedes eingegangene Ergebnis und jedes Dokument trägt denselben lab_code, sodass du erkennen kannst, aus welchem Röhrchen ein Wert stammt.

Klinische Ergebnisse

Klinische Ergebnisse stehen für Standardmessungen von Blut-Biomarkern – etwa Vitamin-D-Werte, Cholesterin, Schilddrüsenhormone und Ähnliches. Jedes klinische Ergebnis enthält:
  • id – die Kennung der Laborergebnis-Zeile. Sie bleibt gleich, wenn das Labor diese Zeile korrigiert, nutze sie also für Upserts. null bei einem planned-Ergebnis.
  • biomarker_name und category – was gemessen wurde und die zugehörige Gruppe (z. B. Vitamine, Hormone).
  • lab_code – der Laborcode (Röhrchen-Barcode), unter dem das Ergebnis eingereicht wurde, also einer der Laborcodes der Bestellung. null bei einem planned-Ergebnis und bei Ergebnissen, die das Labor ohne Code gemeldet hat.
  • value und value_operator – der maßgebliche Messwert. Der Operator ist eq (gleich) bei exakten Werten oder lt/gt, wenn das Labor einen Wert unterhalb oder oberhalb des messbaren Bereichs meldet.
  • unit – die Maßeinheit (z. B. ng/mL, µIU/mL).
  • reference_range_lab – normale und optimale Min-/Max-Grenzen, wie vom Labor für dieses Ergebnis gemeldet und auf dieselbe Skala wie value umgerechnet. Eine Grenze, die das Labor offenlässt, ist null, sodass ein einseitiges Intervall wie < 50 als normal_min: null, normal_max: 50 ankommt. Jedes Ergebnis enthält das Intervall, gegen das gemessen wurde, sodass ein Patient mit Ergebnissen aus mehreren Blutabnahmen oder Laboren pro Ergebnis den passenden Bereich erhält.
  • reference_range_lab_absent_reason – warum reference_range_lab null ist. null, wenn der Bereich vorhanden ist, sowie bei einem planned-Ergebnis. Siehe Wenn kein Laborbereich vorliegt.
  • aniva_range – Vergleichswerte, die Aniva zusammengestellt hat, auf derselben Skala wie value. Sie unterscheiden sich nach Alter, Geschlecht und Schwangerschaftswoche. normal_* ist der allgemeine Bereich. optimal_* ist ein engerer Bereich. Die Werte dienen nur zur Information. Sie sind keine medizinische Beratung, keine Diagnose und keine Bewertung des Ergebnisses. Aniva setzt anhand dieser Werte keine Markierung. Nutze reference_range_lab als Maßstab für das Ergebnis. null, wenn dein Schlüssel nicht über den Scope aniva_ranges_view verfügt oder Aniva für diesen Biomarker keine Werte hat.
  • tested_at – das Datum, an dem der Test durchgeführt wurde.
  • comment – Freitext-Hinweis des Labors zu diesem Ergebnis (z. B. Hinweise zum Referenzbereich, Warnungen zur Probenqualität). null, wenn das Labor keinen angehängt hat.
  • status_reason – warum ein likely_wrong-Ergebnis fraglich ist oder ein fault- bzw. undeliverable-Ergebnis unbrauchbar ist. null bei jedem anderen Status. Unterscheidet sich von comment, das die eigene Notiz des Labors ist und bei fehlerhaften Ergebnissen oft leer bleibt.
  • origin – wer das Dokument geliefert hat, aus dem der Wert stammt; dieselben Werte wie bei origin des Dokuments weiter unten. Ein Wert aus einem hochgeladenen Dokument (member_upload, staff_upload, partner_upload) stammt daraus, dass Aniva die Datei ausgelesen hat, nicht aus einem Laborbericht: Gleiche ihn vor der klinischen Nutzung mit der Datei ab. null bei einem planned-Ergebnis.
  • lab_reported – die eigene Berichtszeile des durchführenden Labors, wortgetreu und unkonvertiert. Siehe unten.

Aniva-Bereiche

aniva_range enthält Vergleichswerte, die Aniva aus veröffentlichten Quellen und eigener Kuratierung zusammengestellt hat. Die Bereiche unterscheiden sich nach Alter, Geschlecht und Schwangerschaftswoche. sources listet die veröffentlichten Quellen auf, die Aniva für die Werte hinterlegt hat. Die Liste kann leer sein.
Die Werte sind allgemeine Informationen. Sie sind keine medizinische Beratung, keine Diagnose, kein medizinischer Befund und keine Bewertung eines Ergebnisses. Aniva stellt sie nicht als Medizinprodukt bereit. Aniva vergleicht kein Ergebnis mit ihnen und setzt anhand dieser Werte keine Markierung. reference_range_lab und die ärztliche Beurteilung bleiben der Maßstab für ein Ergebnis.
Regeln für dein Produkt:
  • Zeige den Aniva-Bereich nur zusätzlich zum Bereich des Labors an, niemals an seiner Stelle.
  • Wenn du eine Markierung, eine Warnung oder eine Empfehlung aus dem Aniva-Bereich ableitest, tust du dies in deinem eigenen Namen und in eigener Verantwortung.
  • Zeige den Hinweis aus deiner Vereinbarung mit Aniva überall dort an, wo du den Aniva-Bereich anzeigst.
Um Zugang zu erhalten, unterzeichne die kurze Vereinbarung zu den Aniva-Bereichen. Wir fügen deinem Schlüssel dann den Scope aniva_ranges_view hinzu. Die Werte können sich ohne Vorankündigung ändern.

Normalisierte Werte im Vergleich zur eigenen Zeile des Labors

value, unit und reference_range_lab sind normalisiert: Wir rechnen jede Messung in die kanonische Einheit des Biomarkers um und melden sie unter unserem eigenen Biomarker-Namen, sodass derselbe Analyt über Labore und Zeiträume hinweg vergleichbar ist. Genau das brauchst du für Verläufe und Vergleiche zwischen Laboren, und es ist nicht das, was eine prüfende Ärztin oder ein prüfender Arzt auf dem PDF des Labors sieht – alkalische Phosphatase, die dort als 48 U/l (40 - 129) steht, erreicht dich als 0.8 µkat/L. lab_reported enthält daneben diese gedruckte Zeile: den Analytennamen und Code des Labors, den Wert und die Einheit wie gedruckt, das Referenzintervall sowohl als Text (< 50, > 55, 40 - 129) als auch als eigene unkonvertierte Grenzen des Labors sowie die Auffälligkeitsmarkierung, den Ergebnisstatus und die Notiz des Labors. Nutze lab_reported, wenn ein Mensch deine Daten mit dem Bericht des Labors abgleicht, und die kanonischen Felder für alle Berechnungen. Es werden nur Felder befüllt, die das Labor tatsächlich gesendet hat; nichts in lab_reported wird abgeleitet, vorbelegt oder umgerechnet, und das gesamte Objekt ist null, wenn wir keinen Rohdatensatz für ein Ergebnis haben.

Wenn kein Laborbereich vorliegt

Wenn reference_range_lab null ist, zeigt dir reference_range_lab_absent_reason warum: Manche Labore drucken einen Zielwert oder eine Risikostufe anstelle eines Referenzbereichs, zum Beispiel Ziel: <200. >240 hoch oder <5.7 neg >=6.5 pos. Diese gehören nicht in reference_range_lab, sodass dessen Grenzen null sind und der Grund lab_text_only lautet. Zeige den gedruckten Text wortgetreu an. Ein einseitiger Bereich wie < 20 ist ein Bereich. Er kommt in reference_range_lab an, wobei eine Grenze null ist und der Grund null lautet. Lass die offene Seite bei der Anzeige offen.

Status klinischer Ergebnisse

Wenn du Patienten Ergebnisse anzeigst, nutze das Feld value direkt – es enthält bereits den korrigierten Wert, falls einer vorliegt.
Stelle ein fault-Ergebnis niemals als Befund dar – sein value ist befüllt, aber nachweislich falsch.

Genetische Ergebnisse

Genetische Ergebnisse stellen Befunde auf Genebene aus einer DNA-Analyse dar. Jedes Ergebnis entspricht einem Gen (z. B. APOE, MTHFR) und enthält:
  • id – die Kennung der Laborergebnis-Zeile. Sie bleibt gleich, wenn das Labor diese Zeile korrigiert, nutze sie also für Upserts. null bei einem planned-Ergebnis.
  • gene – das Gensymbol.
  • lab_code – der Laborcode (Röhrchen-Barcode), unter dem das Ergebnis eingereicht wurde. null bei einem planned-Ergebnis und bei Ergebnissen, die das Labor ohne Code gemeldet hat.
  • genotype – der erkannte Genotyp (z. B. E3/E4).
  • clinical_significance – eine ACMG-basierte Klassifizierung des Befunds.
  • risk_description – eine verständliche Erklärung, was der Genotyp bedeutet.
  • comment – Freitext-Hinweis des Labors zu diesem Ergebnis. null, wenn das Labor keinen angehängt hat.
  • status_reason – warum ein likely_wrong-Ergebnis fraglich ist oder ein fault- bzw. undeliverable-Ergebnis unbrauchbar ist. null bei jedem anderen Status.
  • origin – wer das Dokument geliefert hat, aus dem der Wert stammt, wie bei klinischen Ergebnissen.
  • variants – die konkret erkannten genetischen Varianten, jeweils mit Details auf SNV-Ebene.

Werte für klinische Signifikanz

Status genetischer Ergebnisse

Variantenstruktur

Jedes genetische Ergebnis enthält ein variants-Array. Jede Variante umfasst:
  • name – geläufiger Name (z. B. APOE E4).
  • clinical_significance – Signifikanz auf Variantenebene (kann von der Signifikanz auf Genebene abweichen).
  • conditions – zugehörige Krankheiten/Erkrankungen mit Beschreibungen.
  • snvs – die zugrunde liegenden Einzelnukleotid-Varianten, jeweils mit rs_id, allele, reference_allele und optionaler HGVS-Notation.

Dokumente

Das documents-Array in der Ergebnis-Antwort enthält Verweise auf herunterladbare Laborberichtsdateien. Jedes Dokument hat:
  • id – eine Datei-UUID. Übergib sie an GET /api/v1/documents/{id}, um die Datei herunterzuladen.
  • file_name – der Dateiname, derselbe, den der Download sendet (z. B. 20260405 - Quade Befund - 7642001234.pdf).
  • original_file_name – der Dateiname genau so, wie das Labor oder die hochladende Person ihn geliefert hat (z. B. 7642001234_B0012_FA_E.pdf).
  • origin – wer die Datei geliefert hat: lab, member_upload, staff_upload oder partner_upload (du hast sie über Dokument hochladen hochgeladen).
  • content_type – der Medientyp der Datei (z. B. application/pdf). Die meisten Berichte sind PDFs. Hochgeladene Scans können Bilder oder CSV-Dateien sein.
  • etag – die Version des Dateiinhalts; sie ändert sich immer, wenn sich die Bytes ändern. Speichere sie und lade die Datei erst erneut herunter, wenn sie sich ändert. Es ist der standardmäßige HTTP-Entity-Tag, wie ihn auch S3 oder Google Cloud Storage nutzen.
  • size_bytes – die Dateigröße in Bytes.
  • lab_code – der Laborcode (Röhrchen-Barcode), zu dem der Bericht gehört; null, wenn das Labor keinen angegeben hat.
Der Zugriff auf Dokumente wird anhand des Profils geprüft, dem das Dokument gehört.

Ergebnisse per E-Mail an den Kunden senden

Du kannst den Kunden per E-Mail benachrichtigen, dass seine Ergebnisse bereitstehen. Rufe Ergebnisse per E-Mail senden für einen Termin auf oder Ergebnisse per E-Mail senden für eine Heimtest-Kit-Bestellung. Jeder Aufruf sendet eine E-Mail. Aufrufe werden nicht dedupliziert.
  • Die E-Mail geht an die email des Profils. Eine Platzhalteradresse mit @aniva.email wird abgelehnt.
  • Die E-Mail zeigt den Namen und das Logo der primären Profilgruppe des Profils.
  • Die E-Mail ist in der language des Profils, standardmäßig auf Englisch.
  • Setze with_reports auf true, um die Laborberichte anzuhängen.
  • Füge note hinzu, um eine persönliche Notiz in der E-Mail anzuzeigen, maximal 1.000 Zeichen.
Wenn das Profil Transaktions-E-Mails deaktiviert hat, gibt der Aufruf 409 mit dem Grund unsubscribed zurück. Um sie wieder zu aktivieren, setze transactional_emails_enabled über Profil aktualisieren auf true.

E-Mails bei fertigen Ergebnissen

Du kannst eine E-Mail erhalten, wenn die Ergebnisse einer Buchung fertig sind. Gib bei results_ready_emails bis zu 5 Adressen in Termin erstellen oder Heimtest-Kit-Bestellung erstellen an. Ändere die Liste später über Termin aktualisieren oder Heimtest-Kit-Bestellung aktualisieren; [] schaltet die E-Mails aus.
  • Bitte uns, Standard-E-Mail-Adressen für deine Profilgruppe einzurichten. Eine Buchung ohne results_ready_emails erhält diese. Eine Liste ersetzt sie für diese Buchung – nimm also deine Standard-E-Mail-Adresse mit auf, um sie zu behalten. [] sendet keine E-Mail.
  • Jede Adresse erhält eine E-Mail, sobald jedes Laborergebnis der Buchung endgültig vorliegt.
  • Eine Adresse, die nach Abschluss der Ergebnisse hinzugefügt wird, erhält die E-Mail sofort.
  • Die E-Mail verlinkt auf die Ergebnisseite im Aniva-Admin-Panel. Der Kunde erhält sie nicht.
  • Dein Schlüssel braucht results_view-Zugriff auf den Patienten. Ohne diesen gibt die Anfrage 403 zurück.

Ergebnisse in deiner App anzeigen

Embed-Sitzung erstellen gibt eine einmalige URL für eine schreibgeschützte Ergebnisseite zurück. Öffne sie in einer WebView deiner App, damit der Patient die Ergebnisse ohne Login sieht.
  • Dein Schlüssel braucht die Scopes embed und results_view für den Patienten. Bitte Aniva um den Scope embed.
  • Rufe ihn jedes Mal von deinem Server auf, wenn der Patient die Ergebnisse öffnet. Die URL funktioniert einmalig und für 5 Minuten, und die Seite hält anschließend eine 60-Minuten-Sitzung.
  • route öffnet eine der von uns freigegebenen Seiten: die Biomarker-Liste, einen einzelnen Biomarker oder den 3D-Twin.
  • appearance legt das Theme, die Farbe von Buttons und Links sowie die Anzeige deines Logos fest.
  • report beschränkt die Seite auf einen Termin, eine Heimtest-Kit-Bestellung oder einen Laborbericht, den du mit POST /api/v1/documents hochgeladen hast. Der Patient sieht dann nur die Ergebnisse dieses Berichts.
  • Die Seite zeigt nur Laborergebnisse, genau wie diese API. Sie zeigt keine Dateien, keinen Chat und keine Einstellungen.

Beispielantwort für Ergebnisse