Zum Hauptinhalt springen
Eine Sendung ist ein physisches Paket: eine Kurierabholung mit Blutproben von einem Teststandort zu einem Labor, das Kit auf dem Weg zu einem Heimtest-Kit-Patienten oder die Probe, die dieser Patient zurückschickt. Mit der Shipments-API kannst du Versandaufträge erstellen, verfolgen, ändern und stornieren und siehst jedes Paket an einem Ort – egal, wer es gebucht hat.

Eine Liste, gefiltert

GET /api/v1/shipments ist die einzige Sammlung. Eine Sendung steht für sich allein – sie hat eine n:m-Beziehung zu Terminen und kann zu einer Heimtest-Kit-Bestellung gehören –, sodass es keine unter einem übergeordneten Objekt verschachtelte Liste gibt. Grenze dieselbe Liste mit ?appointment_id= oder ?home_kit_order_id= ein, paginiere sie mit limit / offset und folge dem eingebetteten shipments-Array des übergeordneten Objekts ({ id, added_at } sowohl bei Terminen als auch bei Heimtest-Kit-Bestellungen) zu Sendung abrufen, wenn du eine einzelne ID hast.

Inhalt und wer gebucht hat

Jede Sendung enthält zwei Angaben, die aus den Adressen nicht hervorgehen:
  • contents – Freitext, der beschreibt, was im Paket ist; er wird bei der Erstellung festgelegt ("Medizinisch freigestellte Probe", "Home test kit") und dem Kurier angezeigt. Nur zur Information. Die Richtung ist kein eigenes Feld: Ob ein Paket an ein Labor geht, liest du an destination ab.
  • booked_by – wer das Etikett gedruckt hat: aniva oder external. Nur aniva-Sendungen akzeptieren Aktualisieren und Stornieren; ein external-Paket wird in derselben Liste verfolgt, gibt bei beidem aber 501 zurück.
Ein Paket mit einem Rücksendeetikett und das Paket, das mit diesem Etikett zurückgeschickt wird, verweisen über paired_with aufeinander.

Zugriff

  • Du kannst ein Paket lesen, wenn mindestens ein verknüpfter Termin oder eine verknüpfte Heimtest-Kit-Bestellung in deinem Zugriffskontext liegt oder wenn es von einem Standort in deinem Zugriffskontext abgeschickt wurde.
  • appointments und home_kit_orders listen nur die Termine und Bestellungen in deinem Zugriffskontext auf.
  • Aktualisieren, Stornieren, Termine verknüpfen und Termine trennen erfordern, dass jede verknüpfte Heimtest-Kit-Bestellung in deinem Zugriffskontext liegt. Andernfalls gibt der Aufruf 403 zurück und nur Aniva kann das Paket ändern.

Lesezugriffe rufen nie den Versanddienstleister auf

Jeder Lesezugriff wird aus unserer Datenbank bedient. Eine Synchronisierung im Hintergrund gleicht jede Sendung mit ihrem Versanddienstleister ab (alle 10 Minuten für GO!, stündlich für DHL) und setzt synced_at, woran du das Alter jeder Antwort erkennst. Ein erzwungenes Aktualisieren gibt es nicht – DHL erlaubt nur eine Tracking-Abfrage alle fünf Sekunden, weshalb ein Lesezugriff direkt beim Versanddienstleister nicht möglich wäre.

Sendung erstellen

Beim Erstellen einer Sendung gibst du als Ursprung die location_id an – den Teststandort, an dem der Kurier abholen soll. Außerdem nennst du das Ziellabor über destination_lab. Die Sendung geht an die hinterlegte Versandadresse dieses Labors. Der Standort muss im Zugriffskontext deines API-Schlüssels liegen. Nutze Standorte auflisten, um verfügbare Standort-IDs zu finden. Optional kannst du appointment_id übergeben, um die Sendung direkt bei der Erstellung mit einem bestimmten Termin zu verknüpfen. Die Verknüpfung erscheint auf beiden Seiten direkt im Objekt:
  • bei der Sendung als appointments-Array mit { id, added_at }-Einträgen;
  • beim Termin als shipments-Array mit { id, added_at }-Einträgen.
Beide Arrays sind mit der ältesten Verknüpfung zuerst sortiert. Jede id verweist auf den jeweiligen Detail-Endpunkt (Termin abrufen / Sendung abrufen) für die vollständigen Daten – Partner, die den Kurierverlauf pro Termin sehen möchten, folgen jedem Eintrag im shipments-Array des Termins zum Detail-Endpunkt der Sendung. Eine Sendung kann mit mehreren Terminen verknüpft sein und ein Termin mit mehreren Sendungen. Nach der Erstellung verwaltest du die Verknüpfungen über Termine mit Sendung verknüpfen / Termine von Sendung trennen. Jede Änderung gibt die aktualisierte Terminliste der Sendung zurück. Für Änderungen gilt folgende Regel: Verknüpfungen können erstellt oder entfernt werden, wenn ENTWEDER die Blutabnahme des Termins bereits erfolgt ist (blood_drawn) oder die Sendung vor weniger als 24 Stunden erstellt wurde. Außerhalb dieses Zeitfensters ist die Verknüpfung gesperrt, damit historische Daten unverändert bleiben.

Lebenszyklus

Sendungen durchlaufen die folgenden Status:
Jede Statusänderung sendet einen shipment.*-Webhook, zum Beispiel shipment.delivered. shipment.updated wird bei jeder Änderung ausgelöst, die du auslesen kannst, etwa bei einem neuen Scan.

Regeln für Abholzeiten

Die folgenden Regeln gelten beim Erstellen oder Aktualisieren der Abholzeiten einer Sendung. pickup_date (YYYY-MM-DD) und pickup_time_from / pickup_time_till (HH:MM, 24-Stunden-Format) sind lokale Zeitangaben und werden in der IANA-Zeitzone des Ausgangsstandorts interpretiert – du sendest keine Zeitzone mit.

Sendungen ändern

Du kannst Abholzeiten, Paketanzahl, Gewicht und Notizen einer Sendung über PATCH /api/v1/shipments/{id} aktualisieren. Wenn sich logistikrelevante Felder ändern (Abholdatum, Uhrzeit, Paketanzahl oder Gewicht), wird der bestehende Logistikauftrag automatisch storniert und ein neuer erstellt. Felder, die du im Update-Body weglässt, werden aus der bestehenden Sendung übernommen – wenn du zum Beispiel nur weight aktualisierst, wird der Auftrag mit denselben Abholzeiten neu erstellt. Aktualisierte Felder für die Abholzeiten werden nach denselben Regeln für Abholzeiten geprüft.
Sendungen können nicht mehr geändert werden, nachdem der Kurier das Paket abgeholt hat. Versuche, eine Sendung im Status in_transit, delivered oder fault zu aktualisieren, liefern 409 Conflict.
Wenn der Logistikdienstleister die Stornierung oder Neuerstellung während einer Aktualisierung ablehnt, gibt die API 502 Bad Gateway mit der Fehlermeldung des Anbieters zurück.

Sendungen stornieren

Storniere eine Sendung mit DELETE /api/v1/shipments/{id}. Dabei wird die API des Logistikdienstleisters aufgerufen, um den Auftrag zu stornieren, und der Status wird auf cancelled aktualisiert.
Sendungen können nach der Abholung nicht mehr storniert werden. Versuche, eine Sendung zu stornieren, die bereits in_transit, delivered oder fault ist, liefern 409 Conflict. Das Stornieren einer Sendung, die bereits cancelled ist, bewirkt nichts und liefert 200 mit der Sendung – siehe Idempotenz.
Der Logistikdienstleister kann die Stornierung auch aus eigenen Gründen ablehnen (z. B. wenn die Stornierungsfrist abgelaufen ist). In diesem Fall gibt die API 502 Bad Gateway mit der Fehlermeldung und dem Fehlercode des Anbieters zurück.

Retourenlabels

Ein DHL-Retourenlabel gehört zum jeweiligen Hinversandauftrag. DHL kann das Label nicht einzeln stornieren, daher liefert das Stornieren des Eintrags für ein Retourenlabel 409 Conflict. Storniere stattdessen das Hinversandpaket, solange es pending ist. Damit wird das Label mitstorniert: Jeder Rücksendungseintrag des Hinversandpakets im Status pending wird zu cancelled und erhält einen RETURN_LEG_CANCELLED-Eintrag in status_updates. Ein Rücksendepaket, das der Patient bereits aufgegeben hat, bleibt weiter unterwegs. Sobald das Hinversandpaket versendet wurde, bleibt das Label gültig und Aniva schließt den Rücksendungseintrag manuell.

Sendungsreferenz-IDs

Jede Sendung hat eine 11-stellige Referenz-ID: einen Buchstaben, das Datum und vier Zeichen, {letter}YYMMDDXXXX (zum Beispiel P2611194821). Der Buchstabe zeigt, wozu die Sendung gehört, nie ihre Richtung: Eine Sendung vom 20. bis 22. November 2026 behält ihre ID mit einem Wort davor: API, MAN, AUTO oder KIT (zum Beispiel AUTO261121UWKX). Beide Formate bleiben gültig. Prüfe weder die Länge noch den ersten Buchstaben einer ID. Nutze die ID, um die Sendung abzurufen, zu aktualisieren oder zu stornieren.

Sendungsadressen

Die Felder origin und destination in der Sendungsantwort enthalten aufgelöste Adressobjekte mit der folgenden Struktur:
Bei einem Praxispaket wird die origin-Adresse aus dem Teststandort ermittelt, den du beim Erstellen angegeben hast, und destination ist das Labor, das du in destination_lab genannt hast. Bei einem Home-Kit-Paket ist die Lieferadresse des Patienten die destination des Kits und das origin der Probenrücksendung; der Standort, der das Kit packt, ist sein origin. Die Adresse enthält keine location_id – ordne ein Praxispaket über den verknüpften Termin zu.

Abholzeitfenster

Das Feld pickup in der Sendungsantwort enthält das geplante Kurier-Abholzeitfenster. Es umfasst die Zeitstempel from und till als UTC-Zeitpunkte (ISO 8601 mit Z-Suffix, z. B. 2026-04-15T07:00:00Z) sowie einen timezone-String (IANA-Zeitzone des Abholstandorts). Die lokalen Werte pickup_date / pickup_time_*, die du beim Erstellen oder Aktualisieren gesendet hast, werden mithilfe dieser Zeitzone in diese absoluten Zeitpunkte umgerechnet – nutze timezone, um from / till wieder in der Ortszeit des Abholstandorts anzuzeigen. Das Feld ist null, wenn kein Abholzeitfenster geplant wurde.

Protokoll der Statusaktualisierungen

Jede Sendung enthält ein status_updates-Array – jedes Lebenszyklus-Ereignis, das der Logistikdienstleister gemeldet hat, beginnend mit dem ältesten. Jeder Eintrag enthält:
  • state – das Ereignis im Sendungsstatus-Vokabular (pending, in_transit, delivered, fault), damit du einen Verlauf lesen kannst, ohne die Codes des Versanddienstleisters zu kennen. null, wenn das Ereignis keinen Status trägt (Label-Erstellung, ein Scan ohne Informationen, Einträge aus der Zeit vor diesem Feld). Niemals cancelled – eine Stornierung kommt von uns, nicht vom Versanddienstleister.
  • code – der eigene Statuscode des Versanddienstleisters (GO10, GO90, GOY001 bei GO!; VA, ZF, LA, ZU bei DHL). null, wenn der Versanddienstleister keinen liefert. Bleibt über verschiedene Sprachversionen von status hinweg stabil.
  • detail_code – der feinere Code des Versanddienstleisters, sofern vorhanden: bei DHL statusDetailed, z. B. CNRFC_NRQRD_ZF (in eine Postfiliale umgeleitet), HLDCC_SERPT_LA (dort abholbereit), DLVRD_SERPT_ZU (abgeholt). Andernfalls null.
  • status – die lesbare Bezeichnung des Versanddienstleisters (z. B. "Shipment picked up", "Die Sendung wurde abgeholt.").
  • description – eine Erklärung des Codes oder der längere Satz des Versanddienstleisters. null, wenn beides fehlt.
  • location – wo der Scan stattgefunden hat, so wie der Versanddienstleister es nennt: ein GO!-Depot, eine DHL-Stadt. Freitext, keine Koordinate.
  • time – ISO-8601-Zeitstempel des Ereignisses, wie vom Versanddienstleister gemeldet (mit Offset).
Wenn der Versanddienstleister das Paket an den Absender zurückschickt, erhält der Verlauf einen Eintrag mit dem code RETURNED_TO_SENDER. Sein status enthält den Grund des Versanddienstleisters. Die Sendung bleibt dann fault, auch nachdem der Versanddienstleister das Paket wieder bei uns zugestellt hat. Die Liste kann leer sein, wenn der Versanddienstleister noch keine Ereignisse gemeldet hat. Nutze das Top-Level-Feld status für den maßgeblichen aktuellen Zustand. Er bewegt sich in eine Richtung – von pending über in_transit zu delivered – und wird von fault überlagert, solange das neueste Ereignis einen Fehler meldet; Versanddienstleister sortieren ihre Ereignisse nicht nach Bedeutung (DHL hängt nach dem Übergabe-Scan eine Umleitungsankündigung mit pre-transit-Code an), sodass der neueste Eintrag allein nicht zeigt, wo ein Paket steht.

Beispielsendung

Beispiel für Home-Kit-Pakete

GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… liefert das Kit auf dem Weg zum Patienten und die Probe auf dem Rückweg als Paar zurück:
Der Rücksendungseintrag existiert ab dem Moment, in dem das Retourenlabel gedruckt wird, und bleibt pending, bis der Patient die Probe aufgibt – das ist der tatsächliche Zustand, keine Lücke.