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

> Sendungen abrufen, gefiltert nach Termin, Home-Kit-Bestellung oder Status

Rufe die für deinen API-Schlüssel zugänglichen Sendungen ab, neueste zuerst. Jedes Paket steht in dieser einen Liste:
eine Kurierabholung aus einer Praxis, das Kit auf dem Weg zu einem Heimtest-Kit-Patienten und die Probe auf
dem Rückweg. Filtere mit `appointment_id` oder `home_kit_order_id` nach einem übergeordneten Objekt.

Erfordert den Scope `shipments_view` oder `shipments_manage`.

Die Antwort kommt aus unserer Datenbank und ruft nie den Versanddienstleister auf. Eine Hintergrund-Synchronisierung aktualisiert jede
Sendung (alle 10 Minuten bei GO!, stündlich bei DHL) und `synced_at` zeigt bei jedem Eintrag, wann der
Versanddienstleister zuletzt abgefragt wurde.

## Anfrage

### Query-Parameter

**appointment\_id** `string`

Nur Sendungen, die mit diesem Termin (UUID) verknüpft sind. `404`, wenn der Termin nicht existiert, `403`,
wenn er außerhalb deines Zugriffskontexts liegt.

**home\_kit\_order\_id** `string`

Nur Sendungen, die mit dieser Heimtest-Kit-Bestellung (UUID) verknüpft sind. Normalerweise kommen zwei Einträge zurück – das Kit auf dem
Weg zum Patienten und die Probe zurück ins Labor (ihre `destination` ist das Labor). Es gelten dieselben
Regeln für `404` / `403` wie bei `appointment_id`.

**status** `string`

Nur Sendungen in diesem Status. Einer der Werte `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Maximale Anzahl der zurückgegebenen Sendungen. Standardwert ist 100, maximal 500.

**offset** `integer`

Anzahl der zu überspringenden Sendungen. Standardwert ist 0. Die Sortierung ist stabil (`created_at` absteigend, dann
Referenz), sodass sich Seiten nicht überschneiden.

## Antwort

Bei Erfolg gibt die API `200 OK` mit einem Array von Sendungsobjekten zurück.

**id** `string` *required*

Referenz-ID der Sendung.

**status** `string` *required*

Status der Sendung. Einer der Werte `pending`, `in_transit`, `delivered`, `fault` oder `cancelled`.

**logistics\_provider** `string` *required*

Logistikanbieter. Einer der Werte `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` oder `dhl_express`. Ein Home-Kit-Paket ist `dhl_parcel` oder `dhl_warenpost`, wenn es als
Warenpost International ins Ausland geht.

**tracking\_number** `string`

Externe Sendungsnummer des Logistikanbieters. Kann `null` sein.

**contents** `string`

Freitextbeschreibung des Paketinhalts, wie bei der Erstellung angegeben (z. B. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Nur zur Information – ob ein Paket an ein
Labor geht, lässt sich an `destination` ablesen, und das Gegenstück an `paired_with`. Kann `null` sein.

**booked\_by** `string` *required*

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 verfolgt, gibt aber bei beiden `501` zurück.

**paired\_with** `string`

Referenz des anderen Pakets einer zweiteiligen Sendung – das Paket, das ein Rücksendeetikett
enthielt, und das Paket, das mit diesem Etikett zurückkommt. Bei beiden gesetzt. `null` bei einem Paket ohne Rücksendung.

**origin** `object`

Abholadresse. Kann `null` sein.

**Adressobjekt**

**name** `string` *required*

Empfänger-, Firmen- oder Standortname.

**company\_name** `string`

Firma / c/o-Zeile. Kann `null` sein.

**street** `string` *required*

Straßenname ohne Hausnummer.

**house\_number** `string`

Hausnummer. Kann `null` sein.

**address\_line\_2** `string`

Gebäude, Eingang oder Etage. Kann `null` sein.

**city** `string` *required*

Stadt.

**state** `string`

Bundesland oder Provinz. Kann `null` sein.

**postal\_code** `string` *required*

Postleitzahl.

**country\_code** `string` *required*

Ländercode nach ISO 3166-1 alpha-2.

**phone** `string`

Kontakt-Telefonnummer. Kann `null` sein.

**email** `string`

Kontakt-E-Mail-Adresse. Kann `null` sein.

**destination** `object`

Lieferadresse. Gleiche Struktur wie `origin`. Kann `null` sein.

**pickup** `object`

Geplantes Abholzeitfenster. Kann `null` sein.

**pickup-Objekt**

**from** `string` *required*

Beginn des Abholzeitfensters als UTC-Zeitpunkt (ISO 8601 mit `Z`-Suffix).

**till** `string` *required*

Ende des Abholzeitfensters als UTC-Zeitpunkt (ISO 8601 mit `Z`-Suffix).

**timezone** `string` *required*

IANA-Zeitzone des Abholstandorts (z. B. `Europe/Berlin`). Nutze sie, um `from` / `till` in der Ortszeit des Abholstandorts anzuzeigen.

**notes** `string`

Optionale Notizen. Kann `null` sein.

**status\_updates** `object[]` *required*

Chronologische Verlaufsereignisse des Logistikdienstleisters (ältestes zuerst). Leeres Array, wenn der
Dienstleister noch keine Ereignisse gemeldet hat. Nutze dies für Ereignis-UI, Audits und detailliertere Signale
des Versanddienstleisters; verlass dich für den verbindlichen aktuellen Status auf `status`.

**Felder für Status-Updates**

**state** `string | null` *required*

Das Ereignis im Sendungsstatus-Vokabular – `pending`, `in_transit`, `delivered` oder
`fault` –, sodass du einen Verlauf lesen kannst, ohne die Codes des Versanddienstleisters zu kennen. `null`, wenn das
Ereignis keinen Status trägt (Etikettenerstellung, ein Scan ohne Informationen vom Versanddienstleister, Einträge,
die vor diesem Feld erfasst wurden). Nie `cancelled`.

**code** `string | null` *required*

Das eigene Statuskürzel des Versanddienstleisters: bei GO! `GO10` / `GO90` / `GOY001`, bei DHL `VA` / `ZF` / `LA`
/ `ZU`. `null`, wenn der Versanddienstleister keines geliefert hat. Bleibt bei Übersetzungen von
`status` unverändert.

**detail\_code** `string | null` *required*

Das detailliertere Kürzel des Versanddienstleisters, falls vorhanden – bei DHL `statusDetailed`, z. B. `CNRFC_NRQRD_ZF`
(an eine Postfiliale umgeleitet), `HLDCC_SERPT_LA` (dort abholbereit), `DLVRD_SERPT_ZU`
(abgeholt). `null` bei Versanddienstleistern ohne dieses Feld.

**status** `string` *required*

Vom Dienstleister gelieferte Statusbezeichnung (Freitext, z. B. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Eine Erklärung des Codes oder der ausführlichere Satz des Versanddienstleisters. `null`, wenn keines von beidem vorliegt.

**location** `string | null` *required*

Ort des Scans, wie vom Versanddienstleister angegeben – ein GO!-Depot (`"HUB Niederaula"`) oder eine
DHL-Stadt. Freitext, keine Koordinate. `null`, wenn der Versanddienstleister keinen Ort gemeldet hat.

**time** `string` *required*

Zeitpunkt, zu dem das Ereignis erfasst wurde (ISO 8601, mit dem vom Versanddienstleister gemeldeten Zeitversatz).

**appointments** `ShipmentAppointmentLink[]` *required*

Mit dieser Sendung verknüpfte Termine, älteste Verknüpfung zuerst. Jeder Eintrag hat die Form `{ id, added_at }`;
gleiche jede `id` mit [Termin abrufen](https://docs.anivahealth.com/de/api/appointments/get-appointment.md) ab, um das
vollständige Terminobjekt zu erhalten. Leeres Array, wenn keine Termine verknüpft sind.
Es werden nur die Termine in deinem Zugriffskontext aufgelistet.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Mit dieser Sendung verknüpfte Heimtest-Kit-Bestellungen, älteste Verknüpfung zuerst, im gleichen Format `{ id, added_at }`.
Gleiche jede `id` mit [Heimtest-Kit-Bestellung abrufen](https://docs.anivahealth.com/de/api/home-kit-orders/get-home-kit.md) ab. Leeres
Array bei Praxispaketen. Es werden nur die Bestellungen in deinem Zugriffskontext aufgelistet. Siehe
[Zugriff](https://docs.anivahealth.com/de/concepts/shipments.md#zugriff).

**synced\_at** `string`

Wann die Sendung zuletzt mit dem Versanddienstleister abgeglichen wurde, als UTC-Zeitpunkt. Lesezugriffe rufen nie den
Versanddienstleister auf – eine Hintergrund-Synchronisierung hält die Sendungen aktuell –, daher zeigt dies, wie alt die Antwort ist. `null` bis
zur ersten Synchronisierung.

**created\_at** `string` *required*

Erstellungszeitstempel (ISO 8601).

**updated\_at** `string`

Zeitstempel der letzten Aktualisierung (ISO 8601). Kann `null` sein.

## Wiederholte Aufrufe

Aniva speichert die Antwort dieses Endpunkts für jeden API-Key 5 Minuten lang. Ein erneuter Aufruf innerhalb
dieser Zeit erhält die gespeicherte Antwort. Die Header `Cache-Status` und `Age` zeigen, dass die Antwort
gespeichert ist und wie alt sie ist.

Um sofort über eine Änderung informiert zu werden, abonniere die Webhook-Ereignisse `shipment.created` und `shipment.updated`.
Siehe [Wiederholte Lesezugriffe](https://docs.anivahealth.com/de/concepts/webhooks.md#wiederholte-abrufe).

## Fehlerantworten

| Status | Beschreibung |
| - | - |
| `400` | Ungültiger Query-Parameter. |
| `403` | Zugriff verweigert – fehlender Scope, oder der gefilterte Termin bzw. die gefilterte Heimtest-Kit-Bestellung liegt außerhalb deines Zugriffsbereichs. |
| `404` | Der gefilterte Termin oder die gefilterte Heimtest-Kit-Bestellung wurde nicht gefunden. |
| `500` | Interner Serverfehler. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "logistics_provider": "go",
    "tracking_number": "GO1234567890",
    "contents": "Medizinisch freigestellte Probe",
    "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": null,
    "status_updates": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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