> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sendungen

> So funktioniert die Logistik in der Aniva API: Probensendungen ans Labor und Heimtest-Kit-Pakete, mit Sendungsverfolgung und Status.

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](https://docs.anivahealth.com/de/api/shipments/get-shipment.md), 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](https://docs.anivahealth.com/de/api/shipments/update-shipment.md) und [Stornieren](https://docs.anivahealth.com/de/api/shipments/cancel-shipment.md); 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](https://docs.anivahealth.com/de/api/shipments/update-shipment.md), [Stornieren](https://docs.anivahealth.com/de/api/shipments/cancel-shipment.md), [Termine verknüpfen](https://docs.anivahealth.com/de/api/shipments/attach-appointments-to-shipment.md) und [Termine trennen](https://docs.anivahealth.com/de/api/shipments/detach-appointments-from-shipment.md) 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](https://docs.anivahealth.com/de/api/locations/list-locations.md), 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](https://docs.anivahealth.com/de/api/appointments/get-appointment.md) /
[Sendung abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md)) 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](https://docs.anivahealth.com/de/api/shipments/attach-appointments-to-shipment.md) /
[Termine von Sendung trennen](https://docs.anivahealth.com/de/api/shipments/detach-appointments-from-shipment.md). 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:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Status | Bedeutung |
| - | - |
| `pending` | Der Kurierauftrag wurde erteilt und wartet auf die Abholung. |
| `in_transit` | Der Kurier hat das Paket abgeholt und es ist unterwegs. |
| `delivered` | Das Paket wurde zugestellt. |
| `fault` | Während des Transports ist ein Problem aufgetreten, oder der Versanddienstleister hat das Paket an den Absender zurückgeschickt. |
| `cancelled` | Die Sendung wurde storniert. |

Jede Statusänderung sendet einen `shipment.*`-[Webhook](https://docs.anivahealth.com/de/concepts/webhooks.md), 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.

| Regel | Detail |
| - | - |
| **Nur wochentags** | `pickup_date` muss zwischen Montag und Freitag liegen. |
| **Heute oder Zukunft** | `pickup_date` darf nicht in der Vergangenheit liegen. |
| **Frist am selben Tag** | Abholungen am selben Tag werden nach 16:00 Uhr Europe/Berlin abgelehnt. |
| **Zeitraum** | `pickup_time_from` und `pickup_time_till` müssen innerhalb von 09:00–19:00 Uhr liegen. |
| **Mindestfenster von 2 Stunden** | Das Abholzeitfenster muss mindestens 2 Stunden umfassen. |

## 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](#regeln-fuer-abholzeiten) geprüft.

> [!WARNING]
>
> 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.

> [!WARNING]
>
> 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](https://docs.anivahealth.com/de/concepts/idempotency.md).

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:

| Buchstabe | Sendung |
| - | - |
| `P` | Eine Sendung, die du über diese API erstellst. |
| `M` | Eine Sendung, die das Aniva-Team erstellt. |
| `C` | Eine Sendung aus dem täglichen Versand von Aniva. |
| `K` | Ein Home-Kit-Paket. |
| `F`, `S` | Eigene Lagerpakete von Aniva. |

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:

```json theme={null}
{
  "name": "Aniva Berlin Mitte",
  "company_name": null,
  "street": "Unter den Linden",
  "house_number": "42",
  "address_line_2": null,
  "postal_code": "10117",
  "city": "Berlin",
  "state": null,
  "country_code": "DE",
  "phone": "+4930987654321",
  "email": "berlin-mitte@anivahealth.com"
}
```

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

```json theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## 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:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.