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

> Einen Logistik-Versandauftrag mit angegebenem Start- und Zielort erstellen

Erstelle einen Versandauftrag vom angegebenen Absendestandort. Mit `destination_lab` gibst du das Ziellabor an. Die Sendung geht an die für dieses Labor hinterlegte Versandadresse.

Erfordert den Scope `shipments_manage`.

Sende einen optionalen `Idempotency-Key`-Header, damit sich das Erstellen sicher wiederholen lässt – bei Wiederholung mit demselben Schlüssel kommt die ursprüngliche Antwort zurück, statt einen zweiten Termin zu erstellen. Siehe [Idempotenz](https://docs.anivahealth.com/de/concepts/idempotency.md).

## Anfrage

### Body-Parameter

**location\_id** `string` *required*

UUID des Absende-Teststandorts. Der Standort muss aktiv sein und im Zugriffskontext deines API-Keys liegen.
Nutze [Standorte auflisten](https://docs.anivahealth.com/de/api/locations/list-locations.md), um verfügbare Standort-IDs zu finden.

**destination\_lab** `string` *required*

Ziellabor. Einer der Werte `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` oder
`quade`. Die Sendung geht an die für dieses Labor hinterlegte Versandadresse. Bei einem Labor
ohne hinterlegte Versandadresse wird `400` zurückgegeben.

**appointment\_id** `string`

Optionale Termin-UUID, um diese Sendung bei der Erstellung mit einem Termin zu verknüpfen. Der Termin muss
im Zugriffskontext deines API-Keys liegen. Die Verknüpfung erscheint direkt als Eintrag im
`appointments`-Array der Sendung und umgekehrt als Eintrag im `shipments`-Array des Termins. Um nach der
Erstellung weitere Termine zu verknüpfen oder die ursprüngliche Verknüpfung zu entfernen, nutze [Termine mit
Sendung verknüpfen](https://docs.anivahealth.com/de/api/shipments/attach-appointments-to-shipment.md) und [Termine von Sendung
lösen](https://docs.anivahealth.com/de/api/shipments/detach-appointments-from-shipment.md).

**pickup\_date** `string` *required*

Abholdatum im Format `YYYY-MM-DD` (z. B. `2026-04-15`), interpretiert in der Zeitzone des
Absendestandorts. Muss ein Wochentag (Montag–Freitag) sein, heute oder in der Zukunft. Abholungen am selben Tag sind
nach 16:00 Uhr (Europe/Berlin) nicht möglich.

**pickup\_time\_from** `string` *required*

Früheste Abholzeit im Format `HH:MM` (z. B. `09:00`), interpretiert als Ortszeit in der
Zeitzone des Absendestandorts. Muss zwischen `09:00` und `19:00` liegen.

**pickup\_time\_till** `string` *required*

Späteste Abholzeit im Format `HH:MM` (z. B. `12:00`), interpretiert als Ortszeit in der Zeitzone
des Absendestandorts. Muss zwischen `09:00` und `19:00` liegen. Das Zeitfenster (`pickup_time_till -
    pickup_time_from`) muss mindestens 2 Stunden betragen.

**package\_count** `integer` (default: 1)

Anzahl der Pakete. Standardwert ist `1`.

**weight** `number` (default: 0.5)

Gewicht in kg. Standardwert ist `0.5`.

**pickup\_remarks** `string`

Hinweise für den Kurier bei der Abholung (Absenderhinweise). Wenn nicht angegeben, werden die für die
Abholadresse hinterlegten Hinweise verwendet (oder keine, falls dort keine hinterlegt sind). Maximal 128 Zeichen.

**contents** `string`

Freitextbeschreibung des Paketinhalts, die dem Kurier angezeigt und als `contents`
zurückgegeben wird. Maximal 40 Zeichen (z. B. `Medizinisch freigestellte Probe`).

**notes** `string`

Optionale interne Notizen. Maximal 128 Zeichen.

## Antwort

Bei Erfolg gibt die API `201 Created` mit der neuen Sendung zurück.

**id** `string` *required*

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

**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. Kann `null` sein.

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

Wer das Etikett gedruckt hat: `aniva` oder `external`. Eine von dir erstellte Sendung ist `aniva`.

**paired\_with** `string`

Referenz des anderen Pakets bei einer Sendung mit zwei Paketen. `null` bei einem einfachen Paket.

**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 Statusereignisse des Logistikanbieters (ältestes zuerst). Jeder Eintrag enthält
`state`, `code`, `detail_code`, `status`, `description`, `location` und `time`. Siehe [Sendung
abrufen](https://docs.anivahealth.com/de/api/shipments/get-shipment.md) für die einzelnen Felder. Direkt nach der Erstellung ein leeres Array.
Die Hintergrund-Synchronisierung fügt Ereignisse hinzu, sobald der Anbieter sie meldet.

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

Termine, die mit dieser Sendung verknüpft sind (älteste Verknüpfung zuerst). Jeder Eintrag hat die Form `{ id, added_at }`;
gleiche jede `id` über [Termin abrufen](https://docs.anivahealth.com/de/api/appointments/get-appointment.md) ab.
Enthält direkt nach der Erstellung den über `appointment_id` übergebenen Termin (falls angegeben).

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

Home-Kit-Bestellungen, die mit dieser Sendung verknüpft sind, in derselben Form `{ id, added_at }`. Leeres Array bei einer
von dir erstellten Sendung.

**synced\_at** `string`

Zeitpunkt des letzten Abgleichs der Sendung mit dem Versanddienstleister als UTC-Zeitpunkt. `null` bis zur ersten
Synchronisierung.

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

Erstellungszeitstempel (ISO 8601).

**updated\_at** `string`

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

## Fehlerantworten

| Status | Beschreibung |
| - | - |
| `400` | Validierungsfehler – z. B. ungültiges Datumsformat, Datum am Wochenende, zu kurzes Abholzeitfenster, Frist für Abholung am selben Tag überschritten. Wird auch zurückgegeben, wenn für `destination_lab` oder den Absendestandort keine Adresse hinterlegt ist. |
| `403` | Zugriff verweigert – dein API-Key hat keinen Zugriff auf diesen Vorgang oder der Standort liegt außerhalb deines Zugriffskontexts. |
| `404` | Standort nicht gefunden oder inaktiv, oder `appointment_id` wurde angegeben, aber der Termin existiert nicht. |
| `409` | Der `Idempotency-Key` wurde bereits mit einem anderen Request-Body verwendet oder die ursprüngliche Anfrage ist noch nicht abgeschlossen. |
| `500` | Interner Serverfehler. |
| `502` | Der Logistikanbieter hat die Anfrage abgelehnt. Enthält die Fehlermeldung des Anbieters. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/shipments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "destination_lab": "labclinic",
    "appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "pickup_date": "2026-04-15",
    "pickup_time_from": "09:00",
    "pickup_time_till": "12:00",
    "notes": "Handle with care — temperature-sensitive samples"
  }'
```

```json 201 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-15T07:00:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-15T07:00:00Z",
  "updated_at": null
}
```

```json 400 theme={null}
{
  "error": "pickup_date must be a weekday (Monday–Friday)"
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: Pickup on weekend/holiday not possible",
  "logistics_error_code": 2001
}
```


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