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 andestinationab.booked_by– wer das Etikett gedruckt hat:anivaoderexternal. Nuraniva-Sendungen akzeptieren Aktualisieren und Stornieren; einexternal-Paket wird in derselben Liste verfolgt, gibt bei beidem aber501zurück.
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.
appointmentsundhome_kit_orderslisten 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
403zurü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 setztsynced_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 dielocation_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.
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 überPATCH /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.
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 mitDELETE /api/v1/shipments/{id}. Dabei wird die API des Logistikdienstleisters aufgerufen, um den Auftrag zu stornieren, und der Status wird auf cancelled aktualisiert.
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 Retourenlabel409 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 Felderorigin und destination in der Sendungsantwort enthalten aufgelöste Adressobjekte mit der folgenden Struktur:
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 Feldpickup 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 einstatus_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). Niemalscancelled– eine Stornierung kommt von uns, nicht vom Versanddienstleister.code– der eigene Statuscode des Versanddienstleisters (GO10,GO90,GOY001bei GO!;VA,ZF,LA,ZUbei DHL).null, wenn der Versanddienstleister keinen liefert. Bleibt über verschiedene Sprachversionen vonstatushinweg stabil.detail_code– der feinere Code des Versanddienstleisters, sofern vorhanden: bei DHLstatusDetailed, z. B.CNRFC_NRQRD_ZF(in eine Postfiliale umgeleitet),HLDCC_SERPT_LA(dort abholbereit),DLVRD_SERPT_ZU(abgeholt). Andernfallsnull.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).
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:
pending, bis der Patient die Probe aufgibt – das ist der tatsächliche Zustand, keine Lücke.