> ## 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ányok

> Így működik a logisztika az Aniva API-ban: mintaszállítmányok a laborba és otthoni tesztkészletek csomagjai, nyomon követéssel és állapottal.

Egy szállítmány egy fizikai csomag: egy futár általi begyűjtés, amely vérmintákat szállít egy vizsgálati helyszínről egy laboratóriumba, az otthoni tesztkészletet használó pácienshez tartó készlet, vagy a minta, amelyet a páciens visszaküld postán. A Shipments API segítségével szállítmányrendeléseket hozhatsz létre, követhetsz nyomon, módosíthatsz és mondhatsz le, emellett egy helyen listáz minden csomagot, függetlenül attól, ki foglalta le.

## Egyetlen lista, szűrve

A `GET /api/v1/shipments` az egyetlen gyűjtemény. Egy szállítmány önálló — több-a-többhöz kapcsolatban áll az időpontokkal, és tartozhat egy otthoni tesztkészlet-rendeléshez —, ezért nincs szülő alá beágyazott lista. Szűkítsd ugyanezt a listát a `?appointment_id=` vagy `?home_kit_order_id=` paraméterrel, lapozd a `limit` / `offset` segítségével, és kövesd a szülő beágyazott `shipments` tömbjét (`{ id, added_at }` mind az időpontokon, mind az otthoni tesztkészlet-rendeléseken) a [Szállítmány lekérdezése](https://docs.anivahealth.com/hu/api/shipments/get-shipment.md) végpontra, ha egyetlen azonosítód van.

## Tartalom, és ki foglalta le

Minden szállítmány két olyan információt tartalmaz, amely a címeiből nem derül ki:

* `contents` — szabad szöveg, amely leírja, mi van a csomagban; létrehozáskor állítják be (`"Medizinisch freigestellte Probe"`, `"Home test kit"`), és a futárnak jelenik meg. Csak tájékoztató jellegű. Az irány nem külön mező: az, hogy egy csomag laboratóriumba tart-e, a `destination` mezőből olvasható ki.
* `booked_by` — ki nyomtatta a címkét: `aniva` vagy `external`. Csak az `aniva` szállítmányoknál használható a [Frissítés](https://docs.anivahealth.com/hu/api/shipments/update-shipment.md) és a [Lemondás](https://docs.anivahealth.com/hu/api/shipments/cancel-shipment.md); az `external` csomag ugyanebben a listában követhető nyomon, de mindkettőre `501` kóddal tér vissza.

A visszaküldési címkét szállító csomag és az a csomag, amelyet ez a címke visszahoz, a `paired_with` mezőn keresztül mutat egymásra.

## Hozzáférés

* Akkor olvashatsz egy csomagot, ha legalább egy hozzákapcsolt időpont vagy otthoni tesztkészlet-rendelés a hozzáférési kontextusodban van, vagy ha a csomag egy hozzáférési kontextusodba tartozó helyszínről indult.
* Az `appointments` és a `home_kit_orders` csak a hozzáférési kontextusodban lévő időpontokat és rendeléseket listázza.
* A [Frissítés](https://docs.anivahealth.com/hu/api/shipments/update-shipment.md), a [Lemondás](https://docs.anivahealth.com/hu/api/shipments/cancel-shipment.md), az [Időpontok csatolása](https://docs.anivahealth.com/hu/api/shipments/attach-appointments-to-shipment.md) és az [Időpontok leválasztása](https://docs.anivahealth.com/hu/api/shipments/detach-appointments-from-shipment.md) műveletekhez minden hozzákapcsolt otthoni tesztkészlet-rendelésnek a hozzáférési kontextusodban kell lennie. Ellenkező esetben a hívás `403` kóddal tér vissza, és csak az Aniva módosíthatja a csomagot.

## Az olvasások soha nem hívják a futárszolgálatot

Minden olvasást az adatbázisunkból szolgálunk ki. Egy háttérszinkronizálás egyezteti az egyes szállítmányokat a futárszolgálattal (a GO! esetében 10 percenként, a DHL esetében óránként), és beállítja a `synced_at` időbélyeget, amely megmutatja, milyen régi a válasz. Nincs kényszerített frissítés — a DHL öt másodpercenként egy nyomkövetési hívást engedélyez, ezért olyan olvasást, amely a futárszolgálatot hívja meg, nem tudunk kínálni.

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

Szállítmány létrehozásakor megadod a kiindulási `location_id` értéket — azt a vizsgálati helyszínt, ahol a futárnak fel kell vennie a csomagot. A `destination_lab` mezővel a célként szolgáló laboratóriumot is megnevezed. A szállítmány az adott laboratórium regisztrált szállítási címére megy.

A helyszínnek az API-kulcsod hozzáférési kontextusán belül kell lennie. Az elérhető helyszínazonosítók megkereséséhez használd a [Helyszínek listázása](https://docs.anivahealth.com/hu/api/locations/list-locations.md) végpontot.

Opcionálisan megadhatod az `appointment_id` mezőt, hogy a szállítmányt már létrehozáskor
egy adott időponthoz kapcsold. A kapcsolat mindkét oldalon beágyazva jelenik meg:

* a szállítmányon egy `{ id, added_at }` elemekből álló `appointments` tömbként;
* az időponton egy `{ id, added_at }` elemekből álló `shipments` tömbként.

Mindkét tömbben a legrégebbi kapcsolat áll elöl. Minden `id` a teljes adatcsomagot adó kanonikus részletvégpontra
([Időpont lekérdezése](https://docs.anivahealth.com/hu/api/appointments/get-appointment.md) /
[Szállítmány lekérdezése](https://docs.anivahealth.com/hu/api/shipments/get-shipment.md)) hivatkozik — azok a partnerek, akik
időpontonként szeretnék követni a futár állapotát, az időpont `shipments` tömbjének minden elemét a
szállítmány részletvégpontjáig követhetik.

Egy szállítmány több időponthoz is kapcsolható, és egy időpont is kapcsolható több
szállítmányhoz. Létrehozás után a kapcsolatot az [Időpontok csatolása
szállítmányhoz](https://docs.anivahealth.com/hu/api/shipments/attach-appointments-to-shipment.md) /
[Időpontok leválasztása szállítmányról](https://docs.anivahealth.com/hu/api/shipments/detach-appointments-from-shipment.md) végpontokkal kezelheted. Minden
módosítás a szállítmány módosítás utáni időpontlistájával tér vissza.

A módosítási szabály: kapcsolatok akkor hozhatók létre vagy távolíthatók el, ha VAGY az időpont már túl van
a vérvételen (`blood_drawn`), vagy a szállítmány kevesebb mint 24 órája jött létre. Ezen az időablakon kívül
a kapcsolat zárolva van, hogy az előzményadatok stabilak maradjanak.

## Életciklus

A küldemények a következő státuszokon mennek keresztül:

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

| Státusz | Jelentés |
| - | - |
| `pending` | A futármegbízás elkészült, és felvételre vár. |
| `in_transit` | A futár felvette a csomagot, és az úton van. |
| `delivered` | A csomagot kézbesítették. |
| `fault` | Probléma adódott szállítás közben, vagy a futárszolgálat visszaküldte a csomagot a feladónak. |
| `cancelled` | A küldeményt lemondták. |

Minden státuszváltozás egy `shipment.*` [webhookot](https://docs.anivahealth.com/hu/concepts/webhooks.md) küld, például
`shipment.delivered` eseményt. A `shipment.updated` minden kiolvasható változáskor aktiválódik, például egy új szkennelésnél.

## Felvételi ütemezési szabályok

A következő szabályok érvényesek a küldemény felvételi ütemezésének létrehozásakor vagy módosításakor. A `pickup_date`
(`YYYY-MM-DD`) és a `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24 órás) helyi idő szerinti értékek,
**amelyeket a feladóhely IANA időzónája szerint értelmezünk** – külön időzónát nem kell küldened mellettük.

| Szabály | Részletek |
| - | - |
| **Csak hétköznap** | A `pickup_date` csak hétfő és péntek közé eshet. |
| **Ma vagy a jövőben** | A `pickup_date` nem lehet múltbeli. |
| **Aznapi határidő** | Az aznapi felvételeket 16:00 (Europe/Berlin) után elutasítjuk. |
| **Időablak tartománya** | A `pickup_time_from` és a `pickup_time_till` csak 09:00–19:00 között lehet. |
| **Legalább 2 órás ablak** | A felvételi időablaknak legalább 2 órásnak kell lennie. |

## Küldemények módosítása

A `PATCH /api/v1/shipments/{id}` hívással módosíthatod a küldemény felvételi ütemezését, csomagszámát, súlyát és megjegyzéseit. Ha bármely logisztikai szempontból lényeges mező megváltozik (felvételi dátum, idő, csomagszám vagy súly), a meglévő logisztikai megbízást automatikusan lemondjuk, és újat hozunk létre. A kérés törzséből kihagyott mezők megmaradnak a meglévő küldeményből – ha például csak a `weight` mezőt frissíted, a megbízás ugyanazzal a felvételi ütemezéssel jön létre újra. A módosított ütemezési mezőket ugyanazok a [felvételi ütemezési szabályok](#felveteli-uetemezesi-szabalyok) alapján ellenőrizzük.

> [!WARNING]
>
> A küldemények nem módosíthatók, miután a futár felvette a csomagot. Az `in_transit`,
> `delivered` vagy `fault` státuszú küldemény frissítésére tett kísérlet `409 Conflict` választ ad.

Ha a logisztikai szolgáltató a frissítés során elutasítja a lemondást vagy az újbóli létrehozást, az API `502 Bad Gateway` választ ad a szolgáltató hibaüzenetével.

## Küldemények lemondása

Küldemény lemondásához használd a `DELETE /api/v1/shipments/{id}` végpontot. Ez meghívja a logisztikai szolgáltató API-ját a megbízás lemondásához, és `cancelled` státuszra frissíti a küldeményt.

> [!WARNING]
>
> A küldemények a felvétel után nem mondhatók le. A már `in_transit`, `delivered` vagy `fault`
> státuszú küldemény lemondására tett kísérlet `409 Conflict` választ ad. A már `cancelled`
> státuszú küldemény lemondása nem végez műveletet, és `200` kóddal visszaadja a küldeményt – lásd:
> [Idempotencia](https://docs.anivahealth.com/hu/concepts/idempotency.md).

A logisztikai szolgáltató saját okokból is elutasíthatja a lemondást (például ha lejárt a lemondási határidő). Ilyenkor az API `502 Bad Gateway` választ ad a szolgáltató hibaüzenetével és hibakódjával.

### Visszaküldési címkék

A DHL visszaküldési címke a kimenő megbízás része. A DHL önmagában nem tudja lemondani a címkét, ezért a visszaküldési címkét követő sor lemondása `409 Conflict` választ ad. Ehelyett mondd le a kimenő csomagot, amíg `pending` státuszú. Ez a címkét is lemondja vele együtt: a kimenő csomag minden `pending` státuszú visszaküldési sora `cancelled` lesz, és kap egy `RETURN_LEG_CANCELLED` bejegyzést a `status_updates` mezőjébe. A páciens által már feladott visszaküldési csomag továbbhalad. Miután a kimenő csomag elindult, a címke érvényes marad, az Aniva pedig manuálisan zárja le a visszaküldési sort.

## A küldemények hivatkozási azonosítói

Minden küldeménynek van egy 11 karakteres hivatkozási azonosítója: egy betű, a dátum és négy karakter, `{letter}YYMMDDXXXX` (például `P2611194821`). A betű azt jelzi, hogy mihez tartozik a küldemény, soha nem az irányát:

| Betű | Küldemény |
| - | - |
| `P` | Küldemény, amelyet ezen az API-n keresztül hozol létre. |
| `M` | Küldemény, amelyet az Aniva csapata hoz létre. |
| `C` | Az Aniva napi feladásához tartozó küldemény. |
| `K` | Otthoni készlet csomagja. |
| `F`, `S` | Az Aniva saját készletének csomagjai. |

Egy 2026. november 20. és 22. közötti küldemény megtartja a szóval kezdődő azonosítóját: `API`, `MAN`, `AUTO` vagy `KIT` (például `AUTO261121UWKX`). Mindkét formátum érvényes marad. Ne ellenőrizd az azonosító hosszát vagy első betűjét. Használd az azonosítót a küldemény lekérdezéséhez, frissítéséhez vagy lemondásához.

## Küldeménycímek

A küldemény válaszában található `origin` és `destination` mezők feloldott címobjektumokat tartalmaznak a következő szerkezettel:

```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"
}
```

Rendelői csomagnál az `origin` címet a létrehozáskor megadott vizsgálati helyszín alapján
oldjuk fel, a `destination` pedig a `destination_lab` mezőben megnevezett laboratórium.
Otthoni tesztcsomagnál a páciens szállítási címe a készlet `destination` címe és a
minta visszaküldésének `origin` címe; a készlet `origin` címe a csomagolást végző telephely. A
cím nem tartalmaz `location_id` mezőt – egy rendelői csomagot a hozzá kapcsolt időpont alapján
tudsz összepárosítani.

## Felvételi időablak

A küldemény válaszában található `pickup` mező az ütemezett futárfelvételi időablakot tartalmazza. Ez
magában foglalja a `from` és `till` időbélyegeket UTC időpontként (ISO 8601 formátumban, `Z` utótaggal, pl.
`2026-04-15T07:00:00Z`), valamint egy `timezone` szöveget (a felvételi helyszín IANA időzónája). A
létrehozáskor vagy módosításkor küldött helyi idő szerinti `pickup_date` / `pickup_time_*` értékeket ezen
időzóna alapján oldjuk fel ezekre az abszolút időpontokra – a `timezone` segítségével jelenítheted meg újra a `from` / `till` értékeket a
felvételi helyszín helyi idejében. A mező értéke `null`, ha nincs ütemezve felvételi időablak.

## Státuszfrissítések naplója

Minden küldemény tartalmaz egy `status_updates` tömböt – a logisztikai szolgáltató által jelentett
összes életciklus-eseményt, a legrégebbitől kezdve. Minden bejegyzés a következőket tartalmazza:

* `state` – az esemény a küldemény státuszai szerint (`pending`, `in_transit`, `delivered`,
  `fault`), így a futárszolgálat kódjainak ismerete nélkül is követheted az idővonalat. `null`, ha az esemény
  nem hordoz állapotot (címkelétrehozás, a futárszolgálat információ nélküli szkennelése, a mező
  bevezetése előtt rögzített bejegyzések). Soha nem `cancelled` – a lemondás tőlünk származik, nem futárszolgálati esemény.
* `code` – a futárszolgálat saját státuszkódja (a GO! `GO10`, `GO90`, `GOY001`, illetve a DHL `VA`, `ZF`,
  `LA`, `ZU` kódjai). `null`, ha a futárszolgálat nem adott meg ilyet. A `status` nyelvi fordításaitól
  függetlenül változatlan marad.
* `detail_code` – a futárszolgálat részletesebb kódja, ahol létezik ilyen: a DHL `statusDetailed` értéke, pl.
  `CNRFC_NRQRD_ZF` (postára irányítva), `HLDCC_SERPT_LA` (ott átvételre kész),
  `DLVRD_SERPT_ZU` (átvéve). Minden más esetben `null`.
* `status` – a futárszolgálat ember által olvasható felirata (pl. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` – a kód magyarázata vagy a futárszolgálat hosszabb mondata. `null`, ha
  egyik sincs.
* `location` – a szkennelés helye a futárszolgálat megnevezése szerint: egy GO! depó, egy DHL város. Szabad
  szöveg, nem koordináta.
* `time` – az esemény ISO 8601 időbélyege a futárszolgálat jelentése szerint (időeltolással).

Amikor a futárszolgálat visszaküldi a csomagot a feladónak, az idővonal kap egy bejegyzést `RETURNED_TO_SENDER`
`code` értékkel. Ennek `status` mezője tartalmazza a futárszolgálat indokát. A küldemény ezután `fault` státuszban marad, akkor
is, miután a futárszolgálat visszakézbesíti nekünk a csomagot.

A lista üres lehet, ha a futárszolgálat még nem jelentett eseményeket.

Az irányadó aktuális állapothoz a legfelső szintű `status` mezőt használd. Ez egyirányúan halad – `pending`
státuszból `in_transit`, majd `delivered` felé –, és a `fault` kerül rá, amíg a legújabb esemény hibát jelez;
a futárszolgálatok nem fontossági sorrendbe rendezik az eseményeiket (a DHL például egy `pre-transit` kódú átirányítási
értesítést fűz az átadási szkennelés után), így a legújabb bejegyzés önmagában nem mutatja meg, hol tart a csomag.

## Példa küldeményre

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

## Példa otthoni tesztcsomagokra

A `GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` hívás párban adja vissza a pácienshez tartó készletet és a visszafelé tartó mintát:

```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
  }
]
```

A visszaküldési sor a visszaküldési címke kinyomtatásának pillanatától létezik, és `pending` marad, amíg a páciens fel nem adja a mintát – ez a valós állapot, nem hiányosság.


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