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

# Sendung abrufen

> Eine Sendung anhand ihrer Referenz-ID abrufen

Rufe eine einzelne Sendung anhand ihrer Referenz-ID ab. Die Antwort kommt aus unserer Datenbank und fragt
niemals den Versanddienstleister ab. Eine Hintergrund-Synchronisierung aktualisiert jede Sendung (alle 10 Minuten für GO!, stündlich für
DHL), und `synced_at` zeigt dir, wann der Versanddienstleister zuletzt abgefragt wurde.

Erfordert den Scope `shipments_view` oder `shipments_manage`.

## Anfrage

### Pfadparameter

**id** `string` *required*

Referenz-ID der Sendung (z. B. `P2611194821`).

## Antwort

Bei Erfolg gibt die API `200 OK` mit dem Sendungsobjekt 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 60 Minuten pro API-Schlüssel. Ein wiederholter Aufruf innerhalb
dieser Zeit erhält die gespeicherte Antwort, solange die Sendung unverändert ist. Nach einer Änderung bekommst du eine neue
Antwort. Die Header `Cache-Status` und `Age` zeigen an, dass die Antwort
gespeichert ist und wie alt sie ist.

In einer gespeicherten Antwort können `synced_at` und `updated_at` älter sein als in einer neuen Antwort.

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ültiges ID-Format. |
| `403` | Zugriff verweigert – dein API-Schlüssel hat keinen Zugriff auf diesen Vorgang oder die Sendung liegt außerhalb deines Zugriffskontexts. Ein Paket liegt in deinem Zugriffskontext, wenn mindestens ein verknüpfter Termin oder eine verknüpfte Heimtest-Kit-Bestellung darin liegt. |
| `404` | Sendung nicht gefunden. |
| `500` | Interner Serverfehler. |

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}
```

```json 404 theme={null}
{
  "error": "Shipment not found"
}
```


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