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

# Szállítmány létrehozása

> Logisztikai szállítási megbízás létrehozása megadott kiindulási és célhellyel

Küldeményrendelés létrehozása a megadott feladási helyszínről. A céllaboratóriumot a `destination_lab` paraméterrel adod meg. A küldemény ennek a laboratóriumnak a regisztrált szállítási címére megy.

A `shipments_manage` scope szükséges hozzá.

Küldj opcionális `Idempotency-Key` fejlécet, hogy a létrehozás biztonságosan újrapróbálható legyen — ugyanazzal a kulccsal megismételve az eredeti válasz érkezik vissza egy újabb létrehozása helyett. Lásd: [Idempotencia](https://docs.anivahealth.com/hu/concepts/idempotency.md).

## Kérés

### Törzsparaméterek

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

A feladási teszthelyszín UUID-je. A helyszínnek aktívnak kell lennie, és az API-kulcsod hozzáférési körébe kell tartoznia.
Az elérhető helyszínazonosítók lekéréséhez használd a [Helyszínek listázása](https://docs.anivahealth.com/hu/api/locations/list-locations.md) végpontot.

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

Céllaboratórium. A következő értékek egyike lehet: `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` vagy
`quade`. A küldemény az ehhez a laboratóriumhoz regisztrált szállítási címre megy. Regisztrált szállítási cím
nélküli laboratórium esetén a válasz `400`.

**appointment\_id** `string`

Opcionális időpont-UUID, amelyhez a küldeményt a létrehozáskor hozzákapcsolhatod. Az időpontnak
az API-kulcsod hozzáférési körébe kell tartoznia. A kapcsolat beágyazott elemként jelenik meg a küldemény
`appointments` tömbjében, és fordítva, az időpont `shipments` tömbjében. Ha a létrehozás után
további időpontokat szeretnél csatolni, vagy eltávolítanád a kezdeti kapcsolatot, használd az [Időpontok csatolása
küldeményhez](https://docs.anivahealth.com/hu/api/shipments/attach-appointments-to-shipment.md) és az [Időpontok leválasztása
küldeményről](https://docs.anivahealth.com/hu/api/shipments/detach-appointments-from-shipment.md) végpontokat.

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

A felvétel dátuma `YYYY-MM-DD` formátumban (pl. `2026-04-15`), a feladási helyszín időzónájában
értelmezve. Hétköznapnak (hétfő–péntek), valamint mai vagy jövőbeli napnak kell lennie. Aznapi felvétel
16:00 (Europe/Berlin) után nem érhető el.

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

A legkorábbi felvételi idő `HH:MM` formátumban (pl. `09:00`), a feladási helyszín időzónája szerinti
helyi időként értelmezve. `09:00` és `19:00` között kell lennie.

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

A legkésőbbi felvételi idő `HH:MM` formátumban (pl. `12:00`), a feladási helyszín időzónája szerinti
helyi időként értelmezve. `09:00` és `19:00` között kell lennie. Az időablaknak (`pickup_time_till -
    pickup_time_from`) legalább 2 órának kell lennie.

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

Csomagok száma. Alapértelmezett érték: `1`.

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

Tömeg kg-ban. Alapértelmezett érték: `0.5`.

**pickup\_remarks** `string`

Utasítások a futárnak a felvételhez (feladói megjegyzés). Ha nincs megadva, a felvételi címhez
tárolt megjegyzés lép érvénybe (vagy üres marad, ha a címhez nincs ilyen). Legfeljebb 128 karakter.

**contents** `string`

Szabad szöveges leírás a csomag tartalmáról, amely megjelenik a futárnak, és a válaszban
`contents` mezőként tér vissza. Legfeljebb 40 karakter (pl. `Medizinisch freigestellte Probe`).

**notes** `string`

Opcionális belső megjegyzések. Legfeljebb 128 karakter.

## Válasz

Sikeres kérés esetén az API `201 Created` válasszal és az új küldeménnyel tér vissza.

**id** `string` *required*

A küldemény referenciaazonosítója (pl. `P2604151234`).

**status** `string` *required*

A küldemény életciklus-állapota. A következő értékek egyike: `pending`, `in_transit`, `delivered`, `fault` vagy `cancelled`.

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

Logisztikai szolgáltató. Lehetséges értékei: `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` vagy `dhl_express`. Az otthoni tesztkészlet-csomag `dhl_parcel`, illetve `dhl_warenpost`, ha külföldre megy
Warenpost International küldeményként.

**tracking\_number** `string`

A logisztikai szolgáltatótól kapott külső csomagkövetési szám. Lehet `null`.

**contents** `string`

A csomag tartalmának szabad szöveges leírása, ahogyan a létrehozáskor megadták. Lehet `null`.

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

Ki nyomtatta a címkét: `aniva` vagy `external`. Az általad létrehozott küldemény értéke `aniva`.

**paired\_with** `string`

A kétcsomagos szállítmány másik csomagjának referenciája. Egyirányú csomagnál `null`.

**origin** `object`

Felvételi cím. Lehet `null`.

**cím objektum**

**name** `string` *required*

Címzett, cég vagy helyszín neve.

**company\_name** `string`

Cég / c/o sor. Lehet `null`.

**street** `string` *required*

Utcanév, házszám nélkül.

**house\_number** `string`

Házszám. Lehet `null`.

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

Épület, lépcsőház vagy emelet. Lehet `null`.

**city** `string` *required*

Város.

**state** `string`

Állam vagy tartomány. Lehet `null`.

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

Irányítószám.

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

ISO 3166-1 alpha-2 országkód.

**phone** `string`

Kapcsolattartó telefonszáma. Lehet `null`.

**email** `string`

Kapcsolattartó e-mail-címe. Lehet `null`.

**destination** `object`

Kézbesítési cím. Ugyanolyan szerkezetű, mint az `origin`. Lehet `null`.

**pickup** `object`

Ütemezett felvételi időablak. Lehet `null`.

**pickup objektum**

**from** `string` *required*

A felvételi időablak kezdete UTC időpillanatként (ISO 8601, `Z` utótaggal).

**till** `string` *required*

A felvételi időablak vége UTC időpillanatként (ISO 8601, `Z` utótaggal).

**timezone** `string` *required*

A felvétel helyszínének IANA időzónája (pl. `Europe/Berlin`). Ezzel jelenítheted meg a `from` / `till` értékeket a felvétel helyszínének helyi idejében.

**notes** `string`

Opcionális megjegyzések. Lehet `null`.

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

A logisztikai szolgáltató időrendi életciklus-eseményei (a legrégebbitől kezdve). Minden elem
tartalmazza a `state`, `code`, `detail_code`, `status`, `description`, `location` és `time` mezőket. Az egyes mezőket lásd a [Küldemény
lekérdezése](https://docs.anivahealth.com/hu/api/shipments/get-shipment.md) oldalon. A létrehozás után azonnal üres tömb.
A háttérszinkronizálás hozzáadja az eseményeket, amint a szolgáltató jelenti őket.

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

Az ehhez a küldeményhez kapcsolt időpontok, a legrégebben kapcsolttól kezdve. Minden elem `{ id, added_at }` formátumú;
az egyes `id` értékeket az [Időpont lekérdezése](https://docs.anivahealth.com/hu/api/appointments/get-appointment.md) végponttal vetheted össze.
Közvetlenül a létrehozás után az `appointment_id` mezőben megadott időpontot tartalmazza (ha volt ilyen).

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

Az ehhez a küldeményhez kapcsolt otthoni tesztkészlet-rendelések, ugyanabban az `{ id, added_at }` szerkezetben. Az általad
létrehozott küldeményeknél üres tömb.

**synced\_at** `string`

Mikor történt a küldemény utolsó egyeztetése a futárszolgálattal, UTC időpillanatként. Az első
szinkronizálásig `null`.

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

Létrehozási időbélyeg (ISO 8601).

**updated\_at** `string`

Utolsó frissítés időbélyege (ISO 8601). Lehet `null`.

## Hibaválaszok

| Státusz | Leírás |
| - | - |
| `400` | Validációs hiba — pl. érvénytelen dátumformátum, hétvégi dátum, túl szűk felvételi időablak, túllépett aznapi zárási idő. Akkor is ezt adja vissza, ha a `destination_lab` vagy a feladási helyszín nem rendelkezik regisztrált címmel. |
| `403` | Tiltott — az API-kulcsod nem rendelkezik hozzáféréssel ehhez a művelethez, vagy a helyszín a hozzáférési körödön kívül esik. |
| `404` | A helyszín nem található vagy inaktív, vagy megadtál `appointment_id` értéket, de az időpont nem létezik. |
| `409` | Az `Idempotency-Key` már fel lett használva másik kéréstörzzsel, vagy az eredeti kérés még nem fejeződött be. |
| `500` | Belső szerverhiba. |
| `502` | A logisztikai szolgáltató elutasította a kérést. Tartalmazza a szolgáltató hibaüzenetét. |

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